DocBook XML/SGML Processing Using OpenJade

Saqib Ali

saqib@seagate.com

Questo HOWTO spiega come configurare OpenJade per trattare documenti DocBook in SGML e XML.

Traduzione a cura di Giuseppe Briotti, <g.briotti (at) mclink.it>. Revisione a cura di Beatrice Torracca.

Sommario

1. Introduzione ..............................................................................................................................................................3 1.1. Copyright e Licenza .......................................................................................................................................3 1.2. Ringraziamenti ...............................................................................................................................................3 1.3. Cosa è DocBook?...........................................................................................................................................3 1.4. Cosa è un DSSSL? .........................................................................................................................................4 1.5. Cosa è necessario avere? ................................................................................................................................4 1.6. Presupposti .....................................................................................................................................................4

2. Requisiti .....................................................................................................................................................................4 2.1. Pre-requisiti ....................................................................................................................................................5 2.2. OpenJade ........................................................................................................................................................5 2.3. Le DTD DocBook ..........................................................................................................................................5 2.4. Entità ISO.......................................................................................................................................................5 2.5. DSSSL di Norman Walsh...............................................................................................................................5 2.6. Fogli di stile DSL personalizzati da LDP.......................................................................................................5 2.7. HTMLDOC (Opzionale) ................................................................................................................................6 2.8. XSL di Norman Walsh (Opzionale) ...............................................................................................................6 2.9. XSL personalizzati da LDP (Opzionali) ........................................................................................................6

3. Installazione degli strumenti di elaborazione - OpenJade ....................................................................................6 3.1. Installazione di OpenJade...............................................................................................................................6 3.2. Installazione del DSSSL di Norman Walsh ...................................................................................................7 3.3. Installazione dei DTD di DocBook................................................................................................................8 3.4. Installazione delle Entità ISO.........................................................................................................................8 3.5. Installazione del DSL di LDP ........................................................................................................................9 3.6. Installazione di HTMLDOC.........................................................................................................................10 4. Utilizzo di OpenJade...............................................................................................................................................11

4.1. Trasformazione da SGML............................................................................................................................11 4.2. Trasformazione da XML ..............................................................................................................................11 4.3. Da HTML a PDF (opzionale).......................................................................................................................12

5. Server per XML DocBook 4.1.2.............................................................................................................................12 5.1. Tomcat + Cocoon .........................................................................................................................................13 5.2. Installazione dei fogli di stile XSL di Norman Walsh..................................................................................13 5.3. Installazione dei fogli di stile XSL di LDP..................................................................................................14 5.4. Configurazione di sitemap.xmap..................................................................................................................14 5.5. Accedere a contenuti XML DocBook 4.1.2 da un browser web..................................................................15

6. Ulteriori informazioni.............................................................................................................................................15 6.1. News group...................................................................................................................................................15 6.2. Mailing List..................................................................................................................................................16 6.3. IRC ...............................................................................................................................................................16 6.4. Siti web.........................................................................................................................................................16 6.5. Applicazioni per la scrittura e la modellazione in XML..............................................................................17

1. Introduzione

Alcuni acronimi:

1. SGML - Standard Generalized Markup Language

2. XML - Extensible Markup Language

3. RTF - Rich Text Format

4. HTML - HyperText Markup Language

5. PDF - Portable Document Format

L’obiettivo di questo documento è di configurare OpenJade per convertire il formato di documenti DocBook, stilati in Standard Generalized Markup Language (SGML) 3.2 e 4.2 e in Extensible Markup Language (XML), nei formati HyperText Markup Language (HTML), Rich Text Format (RTF) e Portable Document Format (PDF).

1.1. Copyright e Licenza

This document is Copyright 2001 by Saqib Ali. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.

Di seguito la traduzione del paragrafo precedente, con l’avvertenza che è il testo originale inglese che ha valore legale:

Copyright 2001 by Saqib Ali. È concesso il permesso di copiare, distribuire e/o modifcare questo documento nei termini della licenza GNU sulla libera documentazione, versione 1.1 o qualsiasi versione successiva pubblicata dalla Free Software Foundation; senza i vincoli sulle Sezioni Immodificabili, sulla Prima di copertina e sull’Ultima di copertina. Copia della licenza è disponibile sul sito http://www.gnu.org/copyleft/fdl.html.

1.2. Ringraziamenti

Tutte le lodi sono di Allah, il Signore dei Mondi. Tutti i ringraziamenti vanno ad Allah. Qualunque errore in questo documento è una mia colpa.

Inoltre, mi piacerebbe ringraziare le seguenti persone per i loro validi contributi a questo documento:

1. Eric Safern <esafern (at) lrn.com> - per gli aggiornamenti relativi a Cocoon e JRE.

http://www.timebytes.com/

2. Greg Ferguson <gferg (at) hoop.timonium.sgi.com> - per le utili indicazioni/suggerimenti sulla mailing list di docbook.

3. Kristin Thomas <kristint (at) us.ibm.com> - per la revisione iniziale di questo documento.

4. Luc de Louw <luc (at) delouw.ch> - per i suggerimenti sulla sezione HTMLDOC (PDF -> HTML).

5. Lloyd D Budd <ldp (at) foolswisdom.org> - per i suggerimenti che hanno consentito di migliorare molte delle sezioni del documento.

6. Andrew Shugg <andrew (at) neep.com.au> - per aver corretto gli errori nella versione 2.0 di questo documento. Neep Consulting (http://www.neep.com.au/)

DocBook XML/SGML Processing Using OpenJade

1.3. Cosa è DocBook?

DocBook è una definizione di tipo di documento (Document Type Definition - DTD). Una DTD definisce la sintassi di un documento. DocBook descrive i tipi di struttura ed i formati da utilizzare nei documenti tecnici. È comunemente utilizzato per la sua semplicità e completezza. Una DTD definisce la sintassi di un documento: è essenzialmente un "libro di regole" che descrive gli insiemi di tag ed attributi che saranno utilizzati nella definizione di specifici tipi di contenuto. Così DocBook è un "libro di regole" che viene utilizzato per scrivere documenti. Ogni tag utilizzato nella scrittura del documento, deve essere definito molto specificatamente e formalmente nel DTD.

1.4. Cosa è un DSSSL?

Un Document Style Semantics and Specification Language (DSSSL) definisce come convertire un documento scritto in Standard Generalized Markup Language (SGML) in un formato leggibile quale HTML, RTF e PDF.

1.5. Cosa è necessario avere?

Gli strumenti necessari a configurare OpenJade per convertire SGML e XML sono i seguenti:

• OpenJade

• Le DTD di DocBook

• Le Entità ISO

• Il DSSSL di Norman Walsh

• Il DSL di LDP

• HTMLDOC (opzionale)

• Gli XSL di Norman Walsh (opzionali)

• Gli XSL di LDP (opzionali)

Nota: Tutti i pacchetti citati sono liberamente distribuiti e disponibili in rete. Il prossimo capitolo spiega come scaricare questi pacchetti.

1.6. Presupposti

In questo documento si presume che il lettore abbia installato sul proprio sistema quanto segue:

• gzip - disponibile su http://www.gnu.org/directory/

• gcc e GNU make - disponibili su http://www.gnu.org/directory/

• unzip - disponibile su http://www.info-zip.org/pub/infozip/

• Strumenti standard Unix, quali: tar, mkdir, mv...

DocBook XML/SGML Processing Using OpenJade

2. Requisiti

Si deve scaricare e compilare un solo pacchetto (OpenJade). Questo HOWTO illustrerà la procedura di compilazione, ma il lettore dovrebbe avere familiarità con l’installazione da codice sorgente.

La maggior parte dei pacchetti necessari sono disponibili sul sito web The Linux Documentation Project (TLDP) (http://www.tldp.org/authors/index.html#resources).

2.1. Pre-requisiti

Creare una directory /tmp/downloads. Sarà utilizzata per archiviare il codice sorgente scaricato.

2.2. OpenJade

OpenJade sarà utilizzato per trattare documenti DocBook. OpenJade può essere scaricato da: http://openjade.sourceforge.net/.

Al momento della stesura del presente documento, era disponibile la versione OpenJade 1.3.1. Il file da scaricare è openjade-1.3.x.tar.gz.

2.3. Le DTD DocBook

Tutte le DTD DocBook sono disponibili sul sito The Linux Documentation Project all’indirizzo http://www.tldp.org/authors/index.html#resources.

Scaricare le seguenti DTD: DocBook SGML v4.1 (http://www.tldp.org/authors/tools/docbk41.zip), DocBook SGML v3.1 (http://www.tldp.org/authors/tools/docbk31.zip) e DocBook XML v4.1.2 (http://www.tldp.org/authors/tools/docbkx412.zip).

Nota: Scaricare tutti gli archivi zip.

2.4. Entità ISO

Per comodità degli utenti, The Linux Documentation Project (http://www.tldp.org) ha compresso tutte le entità in un unico grande file tar, collocato all’indirizzo http://www.tldp.org/authors/tools/entities.tar.gz. Grazie al TLDP per questo.

2.5. DSSSL di Norman Walsh

Il DSSSL sviluppato da Norman Walsh può essere scaricato dal sito web del progetto DocBook: http://sourceforge.net/project/showfiles.php?group_id=21935.

Al momento della stesura del presente documento era disponibile il file docbook-dsssl-1.7.6.

2.6. Fogli di stile DSL personalizzati da LDP

LDP DSL è un foglio di stile personalizzato usato da The Linux Documentation Project (TLDP) (http://www.tldp.org). È una estensione del DSSSL di Norman Walsh. Sono state aggiunte cose come gli sfondi e gli Indici. Può essere scaricato da http://www.tldp.org/authors/tools/ldp.dsl.

Il file ldp.dsl richiede il DSSSL di Norman Walsh.

2.7. HTMLDOC (Opzionale)

HTMLDOC può essere utilizzato per convertire l’HTML in PDF. Se preferite produrre documenti in PDF, potrete scaricare HTMLDOC da http://www.easysw.com/htmldoc/software.php.

2.8. XSL di Norman Walsh (Opzionale)

Questo non è necessario. Ma qualora si volesse utilizzare Tomcat + Cocoon come server di contenuti per documenti XML DocBook 4.1.2, saranno necessari i fogli di stile XML creati da Norman Walsh.

I fogli di stile sono disponibili sul sito http://sourceforge.net/projects/docbook/.

Si può scaricare il pacchetto chiamato docbook-xsl.

Nota: Recentemente è stata rilasciata la versione 1.57.0 del pacchetto. Quanto qui detto è stato verificato con l’ultima versione, apportando al testo le opportune modifiche. Chi dovesse incontrare ancora errori, è pregato di avvisarmi via e-mail all’indirizzo <saqib@seagate.com>.

2.9. XSL personalizzati da LDP (Opzionali)

I fogli di stile personalizzati da LDP possono essere scaricati da http://my.core.com/~dhorton/docbook/tldp-xsl/.

3. Installazione degli strumenti di elaborazione - OpenJade

In questa sezione verrà spiegata l’installazione degli strumenti nelle directory appropriate. Tutti gli strumenti vanno posti nella directory /usr/local/dbtools/. Questa directory può essere creata con il seguente comando:

# mkdir /usr/local/dbtools

3.1. Installazione di OpenJade

Questa operazione è la parte più facile, ma anche quella che richiede più tempo. Si rammenti che OpenJade richiede un lungo tempo di compilazione. Per installare OpenJade, si completino i seguenti passi:

1. Cambiare la directory corrente in /tmp/downloads.

    # cd /tmp/downloads

2. Decomprimere il file.

  # gzip -d openjade-1.3.x.tar.gz

3. Estrarre i file dall’archivio.

  # tar -xvf openjade-1.3.x.tar

4. Cambiare la directory corrente in openjade-1.3.

  # cd openjade-1.3.x

5. Eseguire il comando ./configure.

  # ./configure --prefix=/usr/local/dbtools/openjade

6. Eseguire il comando make.

  # make

7. Eseguire il comando make install. Completato questo passo, i file binari di OpenJade saranno installati in

  /usr/local/dbtools/openjade.
  # make install
8. Copiare la directory dsssl da /tmp/downloads/openjade-1.3.x in /usr/local/dbtools/openjade
  # cp -dpR dsssl /usr/local/dbtools/openjade/

3.2. Installazione del DSSSL di Norman Walsh

In questa fase si installerà il DSSSL di Norman Walsh in una collocazione appropriata. Il DSSSL non necessita di compilazione.

1. Cambiare la directory corrente in /tmp/downloads.

  # cd /tmp/downloads

2. Decomprimere il file.

  # gzip -d docbook-dsssl-1.76.tar.gz

3. Estrarre il file dall’archivio.

  # tar -xvf docbook-dsssl-1.76.tar

4. Spostare il file in /usr/local/dbtools/docbook-dsssl.
  # mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl

3.3. Installazione dei DTD di DocBook

In questa sezione installeremo i DTD di DocBook.

1. Cambiare la directory corrente in /usr/local/dbtools.

  # cd /usr/local/dbtools

2. Creare tre nuove directory chiamate dtd3.1, dtd4.1 e dtd4.1.2.

  # mkdir dtd3.1
  # mkdir dtd4.1
  # mkdir dtd4.1.2

3. Cambiare la directory corrente in dtd3.1.

  # cd dtd3.1

4. Decomprimere il file DocBook SGML v3.1 in questa directory.

  # unzip /tmp/downloads/docbk31.zip

5. Cambiare la directory corrente in dtd4.1.

  # cd ../dtd4.1

6. Decomprimere il file DocBook SGML v4.1 in questa directory.

  # unzip /tmp/downloads/docbk41.zip

7. Cambiare la directory corrente in dtd4.1.2.

  # cd ../dtd4.1.2

8. Decomprimere il file DocBook XML v4.1.2 in questa directory.

  # unzip /tmp/downloads/docbk412.zip

DocBook XML/SGML Processing Using OpenJade

3.4. Installazione delle Entità ISO

In questa sezione installeremo le entità ISO scaricate dal sito web di LDP. Per prime si installino le entità ISO per le DTD SGML, versione 3.1.

1. Cambiare la directory corrente in /usr/local/dbtools/dtd3.1.

  # cd /usr/local/dbtools/dtd3.1

2. Copiare il file /tmp/downloads/entities.tar.gz in questa directory.

  # cp /tmp/downloads/entities.tar.gz .

3. Decomprimere il file.

  # gzip -d entities.tar.gz

4. Estrarre i file dall’archivio.

  # tar -xvf entities.tar

Si installino ora le entità ISO per le DTD SGML, versione 4.1.

1. Cambiare la directory corrente in /usr/local/dbtools/dtd4.1.

  # cd /usr/local/dbtools/dtd4.1

2. Copiare il file /tmp/downloads/entities.tar.gz in questa directory.

  # cp /tmp/downloads/entities.tar.gz .

3. Decomprimere il file.

  # gzip -d entities.tar.gz

4. Estrarre i file dall’archivio.

  # tar -xvf entities.tar

3.5. Installazione del DSL di LDP

Infine, si installino i fogli di stile personalizzati di LDP.

1. Cambiare la directory corrente in /tmp/downloads.

  # cd /tmp/downloads

  2. Copiare il file ldp.dsl nella directory /usr/local/dbtools/docbook-dsssl/print/ldp.dsl.
    # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/print/ldp.dsl

  3. Copiare il file ldp.dsl nella directory /usr/local/dbtools/docbook-dsssl/html/ldp.dsl.
    # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/html/ldp.dsl

3.6. Installazione di HTMLDOC

Questo passo è opzionale. È richiesto solo se si vuole produrre documentazione PDF da documenti scritti in HTML.

Ritornare alla directory di download.

# cd /tmp/downloads directory

Estrarre dall’archivio il codice sorgente di HTMLDOC.

# gzip -d htmldoc-1.8.xx-source.tar.gz
# tar -xvf htmldoc-1.8.xx-source.tar
# cd htmldoc-1.8.xx-1

Lanciare il comando configure per impostare la posizione dell’installazione.

# ./configure --prefix=/usr/local/dbtools/htmldoc
# make

Al momento della stesura di questo documento era disponibile la versione 1.8.20-1 di HTMLDOC. Questa versione aveva un piccolo problema di font nel Makefile. Si dovrebbe presentare al momento di installare i font, poiché i font corretti non sono disponibili sul sistema.

L’errore che si presenta al momento di lanciare il comando make install è questo:

# make install
Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
/bin/cp: cannot stat `ZapfChancery.afm': No such file or directory
/bin/cp: cannot stat `ZapfChancery.pfa': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.afm': No such file or directory
/bin/cp: cannot stat `ZapfDingbats.pfa': No such file or directory
make[1]: *** [install] Error 1

Per correggere questo problema di installazione, si modifichi il file fonts/Makefile commentando le righe che fanno riferimento ai font ZapfChancery e ZapfDingbats.

Quindi si esegua l’installazione:

# make install

Making all in htmldoc...
Making all in doc...
Installing in fonts...
Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
Installing in data...
Installing in doc...
Installing in htmldoc...

4. Utilizzo di OpenJade

In questa sezione si utilizzerà OpenJade per convertire documenti dal formato DocBook SGML/XML nei formati HTML, RTF e PDF.

4.1. Trasformazione da SGML

4.1.1. Impostare la variabile di ambiente SGML_CATALOG_FILES per l’SGML

La variabile SGML_CATALOG_FILES deve essere impostata per puntare ai file di catalogo appropriati. Per impostare la variabile, si utilizzi il seguente comando per la shell Bourne:

# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

Con la shell C si utilizzi invece:

# setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

4.1.2. Da SGML a HTML

Per convertire documenti da SGML a HTML, si usi il seguente comando:

# /usr/local/dbtools/openjade/bin/openjade -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml

(NdT. In questo ed in altri esempi seguenti, si utilizza come file da trasformare il sorgente del presente documento)

Per creare in uscita un file non-chunked (tutto in una pagina):

# /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml

4.1.3. Da SGML a RTF

Per convertire documenti da SGML a RTF, si usi il seguente comando:

# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print DocBook-OpenJade-SGML-XML-HOWTO.sgml

DocBook XML/SGML Processing Using OpenJade

4.2. Trasformazione da XML

È possibile scaricare un file di esempio in XML DocBook 4.1.2 da http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml.

4.2.1. Impostare la variabile di ambiente SGML_CATALOG_FILES per XML La variabile SGML_CATALOG_FILES deve essere impostata per puntare ai file di catalogo appropriati. Per impostare la variabile, si utilizzi il seguente comando per la shell Bourne:

# export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

Con la shell C si utilizzi invece:

# setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog:/usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

4.2.2. Da XML a HTML Per convertire documenti da XML a HTML, si usi il seguente comando:

# /usr/local/dbtools/openjade/bin/openjade -t xml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

4.2.3. Da XML a RTF Per convertire documenti da XML a RTF, si usi il seguente comando:

# /usr/local/dbtools/openjade/bin/openjade -t rtf -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl DocBook-OpenJade-SGML-XML-HOWTO.xml

4.3. Da HTML a PDF (opzionale)

Per conversioni da HTML a PDF si dovrà usare HTMLDOC. Occorre prima creare un file HTML non-chunked dall’SGML:

# /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html DocBook-OpenJade-SGML-XML-HOWTO.sgml

Quindi si esegua HTMLDOC per produrre il file PDF.

# /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html

5. Server per XML DocBook 4.1.2

Ci sono tre modi per utilizzare l’XML DocBook 4.1.2 su un server web:

• Pre-processando i documenti da riga di comando - Open Jade, XSLT

• Utilizzando degli script - PHP, Perl, Python • Con un server per applicazioni - Tomcat + Cocoon

Usare un server per applicazioni come Cocoon è la scelta migliore.

Cocoon in azione: Per vedere un esempio di web server su cui girano Tomcat + Cocoon che agiscono da server di contenuti per XML DocBook 4.1.2, si può visitare il sito http://www.xml-dev.com:8080/cocoon/mount/docbook/.

In questa sezione vedremo l’utilizzo di Tomcat + Cocoon come server di contenuti per documenti XML DocBook 4.1.2.

5.1. Tomcat + Cocoon

Tomcat è il Java Servlet Container. Per ulteriori informazioni si visiti il sito http://jakarta.apache.org/tomcat/index.html.

Apache Cocoon è un ambiente per la pubblicazione di documenti XML. Per ulteriori informazioni si visiti il sito http://xml.apache.org/cocoon/index.html.

Questo HOWTO non entrerà nei dettagli sulla configurazione di Tomcat + Cocoon, poiché questa problematica è illustrata in http://xml.apache.org/cocoon/installing/index.html. Configurare Tomcat + Cocoon è una facile procedura, che dovrebbe richiedere meno di cinque minuti.

Una volta che si abbiano Cocoon + Tomcat configurati ed operativi, si passi alla sezione seguente, relativa al server di documenti XML DocBook 4.1.2.

Nota: Un importante avviso: gli utenti del settore hanno riscontrato problemi di compatibilità utilizzando i fogli di stile DocBook con alcune versioni del parser XML Xalan. Xalan è il parser fornito col JRE (Java Runtime Environment) di Sun, ed è quindi quello utilizzato in maniera predefinita.

Ci si assicuri, come minimo, di utilizzare l’ultima versione di JRE di Sun (al momento della stesura di questo documento è la 1.4.2).

Si consideri anche l’opportunità di aggiornare il parser Xalan all’ultima versione. Al momento, con l’ultima JRE di Sun, la 1.4.2, è fornito Xalan 2.4.1, mentre lo stesso Xalan è giunto alla versione 2.5.1.

Per controllare la versione di Xalan installata, si esegua:

 # java org.apache.xalan.xslt.EnvironmentCheck

Per ulteriori informazioni, si visiti il sito http://xml.apache.org/xalan-j/faq.html.

5.2. Installazione dei fogli di stile XSL di Norman Walsh

In questa fase verranno installati i fogli di stile XSL di Norman Walsh nella directory /usr/local/dbtools/.

Cambiare la directory corrente in /tmp/downloads e decomprimere il file docbook-xsl.

# cd /tmp/downloads/
# gzip -d docbook-xsl-1.53.0.tar.gz

# tar -xvf docbook-xsl-1.53.0.tar

Per installare docbook-xsl, occorre spostare i file in /usr/local/dbtools.

# mv docbook-xsl-1.53.0 /usr/local/dbtool/docbook-xsl

Quindi si installino gli XSL di LDP.

5.3. Installazione dei fogli di stile XSL di LDP

Decomprimere il file tldp-xsl-xxxxx.tar.gz e copiare tutti i file nella directory

/usr/local/dbtools/docbook-xsl/html.
# cd /tmp/downloads
# gzip tldp-xsl-xxxxx.tar.gz
# tar -xvf tldp-xsl-xxxxx.tar
# mv tldp-html*.xsl /usr/local/dbtools/docbook-xsl/html

5.4. Configurazione di sitemap.xmap

$COCOON_HOME punta alla directory delle applicazioni web di Cocoon (Cocoon Web Application Directory).

Questa directory è solitamente /usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/.

Si crei una directory dal nome docbook all’interno di $COCOON_HOME/mount. Qui è dove si collocheranno tutti i propri documenti XML DocBook 4.1.2.

# mkdir $COCOON_HOME/mount/docbook

Creare un file dal nome sitemap.xmap nella directory $COCOON_HOME/mount/docbook con il seguente contenuto:

# cd $COCOON_HOME/mount/docbook
# vi sitemap.xmap
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
     <!-- usare i componenti convenzionali -->
     <map:components>
         <map:generators default="file"/>
         <map:transformers default="xslt"/>
         <map:readers default="resource"/>
         <map:serializers default="html"/>
         <map:selectors default="browser"/>
         <map:matchers default="wildcard"/>
         <map:transformers default="xslt"/>
     </map:components>
     <map:pipelines>
         <map:pipeline>

<map:match pattern="">
<map:generate src="samples.xml"/>
<map:transform src="/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/mount/editor/stylesheets/simple-page2html.xsl"/>
<map:serialize/>
</map:match>
<!-- rispondere alle richeste *.html con
      i propri documenti processati da .xsl -->
<map:match pattern="*.html">
     <map:generate src="{1}.xml"/>
     <map:transform src="/usr/local/dbtools/docbook-xsl/html/tldp-html.xsl"/>
     <map:serialize type="html"/>
</map:match>
<!-- successivamente, rispondere a richieste *.pdf con
      i propri documenti processati da doc2pdf.xsl -->
<map:match pattern="*.pdf">
     <map:generate src="{1}.xml"/>
     <map:transform src="/usr/local/dbtools/docbook-xsl/fo/docbook.xsl"/>
     <map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="*.xml">
     <map:generate src="{1}.xml"/>
     <map:serialize type="xml"/>
</map:match>

</map:pipeline>
</map:pipelines>
</map:sitemap>

5.5. Accedere a contenuti XML DocBook 4.1.2 da un browser web

Collocare un file XML DocBook 4.1.2 nella directory $COCOON_HOME/mount/docbook/.

Un file di esempio è disponibile sul sito http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml.

Ora è possibile accedere al documento, utilizzando un browser, all’indirizzo http://localhost:8080/cocoon/mount/sample.html (HTML) o http://localhost:8080/cocoon/mount/sample.pdf (PDF).

6. Ulteriori informazioni

Questa sezione contiene alcuni link a risorse correlate disponibili su Internet.

Chi volesse suggerire ulteriori risorse, può inviarmi le informazioni per email all’indirizzo <saqib@seagate.com>. Grazie.

DocBook XML/SGML Processing Using OpenJade

6.1. News group

Alcuni news group di interesse sono:

1. comp.text.sgml (facilemente accessibile da Google! Groups (http://groups.google.com/groups?group=comp.text.sgml))

2. comp.text.xml (facilemente accessibile da Google! Groups (http://groups.google.com/groups?group=comp.text.xml))

3. htmldoc.general (il server è news.easysw.com (nttp://news.easysw.com))

6.2. Mailing List

Di seguito alcune mailing list pertinenti.

1. DocBook mailing list presso OASIS. Visitare il sito http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml (http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml) per ulteriori informazioni.

2. DocBook mailing list presso TLDP. Visitare il sito http://www.tldp.org/mailinfo.html per ulteriori informazioni.

3. xml-doc presso Yahoo Groups. Visitare il sito http://groups.yahoo.com/group/xml-doc/ per ulteriori informazioni.

6.3. IRC

1. DocBook IRC Channel. #docbook su irc://irc.openprojects.net

6.4. Siti web

1. http://www.oasis-open.org/ OASIS gestisce diversi DTD per DocBook

2. http://www.xml-dev.com/blog/ XML / XHTML WebLog

3. http://docbook.org/wiki/moin.cgi/ The DocBook Wiki

4. http://www.docbook.org/tdg/en/ Versione in linea di "DocBook: The Definitive Guide"

5. http://www.bureau-cornavin.com/opensource/crash-course/index.html Writing Documentation Using DocBook: A Crash Course

6. http://www-106.ibm.com/developerworks/library/l-docbk.html A gentle guide to DocBook (ottimo documento introduttivo).

7. http://www.tldp.org/LDP/LDP-Author-Guide/index.html La guida per gli autori del Linux Documentation Project (TLDP).

8. http://www.tldp.org/authors/index.html#resources Risorse per DocBook fornite dal TLDP.

9. http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/ Il "DocBook Demystification HOWTO" di Eric Raymond.

DocBook XML/SGML Processing Using OpenJade

10. http://www.xml-dev.com:8080/cocoon/mount/docbook/ Sito di esempio per la configurazione di Tomcat + Cocoon + DocBook.

6.5. Applicazioni per la scrittura e la modellazione in XML

Nota: Una completa lista di editor per XML può essere trovato sul sito http://www.xml-dev.com/blog/#19.

1. eXchaNGeR - Il browser (ed editor) XML http://xngr.org/.

2. XERLIN - Applicazione per la modellazione XML http://www.xerlin.org/.

3. DocPro di Command Prompt, INC. http://www.commandprompt.com/entry.lxp?lxpe=2.

4. YAWC Pro di XML Workshop LTD. http://www.yawcpro.com/. Può essere utilizzato per convertire documenti dal formato MS Word nel formato Simple DocBook XML.

5. Logictran - Convertitore RTF. http://www.logictran.com/. Da Word/RTF a HTML/XML.

6. MajiX - Convertitore da Word a XML. http://tetrasys.dhs.org/.

7. XMETAL di SoftQuad http://www.softquad.com/.

8. Tagless Editor di i4i (non è supportato il DTD DocBook) http://www.i4i.com/.

9. XML Editor di XMLmind http://www.xmlmind.com/xmleditor/.

10. upCast e downCast di Inifinity Loop http://www.infinity-loop.de/en/products.html.

11. W2XML di DocSoft http://www.docsoft.com/w2xmlv2.htm.

12. XMLWrite di Wattle Software http://xmlwriter.net/.

13. oXygen XML Editor - Basato su Java http://www.oxygenxml.com/.

14. Xeena di IBM http://www.alphaworks.ibm.com/tech/xeena.

15. Excosoft Client XMLhttp://www.excosoft.se/eweb/site/exc_pd.html.

16. Timelux Xpress http://www.timelux.lu/html/Xpress2001.html.

17. Morphon http://www.morphon.com/.

18. Conglomerate http://conglomerate.org/.