DocBook XML/SGML Processing Using OpenJade

Saqib Ali

 saqib@seagate.com 

Diario delle revisioni
Revisione v2.2.82003-07-16Corretto da: es
Aggiunte informazioni sulla sincronizzazione di JRE con Cocoon.
Revisione v2.2.72003-07-09Corretto da: es
Corretti collegamenti interrotti a LDP XSL e ad altri file specifici di LDP XSL.
Revisione v2.2.62003-06-16Corretto da: sa
Verificate le istruzioni con DocBook XSL 1.57.
Revisione v2.2.52003-05-16Corretto da: sa
Corretti i collegamenti interrotti nella sezione delle risorse esterne.
Revisione v2.2.42003-04-20Corretto da: sa
Aggiornati i collegamenti al nuovo sito delle demo. Aggiunti nuovi collegamenti nella sezione delle risorse.
Revisione v2.2.32002-11-22Corretto da: sa
Inseriti i suggerimenti degli utenti. Aggiunti nuovi collegamenti nella sezione delle risorse.
Revisione v2.2.22002-10-09Corretto da: as
Con questo aggiornamento sono stati corretti alcuni ulteriori errori tipografici e rimossi alcuni spazi che rendevano sgradevole l'aspetto della conversione in HTML.
Revisione v2.2.12002-10-09Corretto da: sa
Corretta la URL ai file di esempio.
Revisione v2.22002-09-29Corretto da: as
Piccole correzioni alla sezione su Cocoon.
Revisione v2.12002-09-15Corretto da: sa
Piccole correzioni alla sezione su Cocoon.
Revisione v2.02002-09-10Corretto da: sa
Aggiunta la sezione relativa all'utilizzo di Tomcat e Cocoon come server di contenuti per DocBook XML 4.1.2.
Revisione v1.52002-08-11Corretto da: sa
Inserita la sezione su XML con il relativo file di esempio.
Revisione v1.42002-08-08Corretto da: sa
Alcune importanti correzioni e modifiche suggerite da Lloyd D Budd. Grazie Lloyd. :)
Revisione v1.32002-08-02Corretto da: sa
Aggiunta la sezione sulle "ulteriori informazioni".
Revisione v1.22002-07-23Corretto da: sa
Aggiunta la sezione sulla conversione HTML -> PDF utilizzando HTMLDOC. Grazie a Luc De Louw per il suggerimento.
Revisione v1.12002-07-19Corretto da: KET
Corretti errori grammaticali, numerate le procedure.
Revisione v1.02002-06-29Corretto da: sa
Primo rilascio pubblico.

Sommario
1. Introduzione
1.1. Copyright e Licenza
1.2. Ringraziamenti
1.3. Cosa è DocBook?
1.4. Cosa è un DSSSL?
1.5. Cosa è necessario avere?
1.6. Presupposti
2. Requisiti
2.1. Pre-requisiti
2.2. OpenJade
2.3. Le DTD DocBook
2.4. Entità ISO
2.5. DSSSL di Norman Walsh
2.6. Fogli di stile DSL personalizzati da LDP
2.7. HTMLDOC (Opzionale)
2.8. XSL di Norman Walsh (Opzionale)
2.9. XSL personalizzati da LDP (Opzionali)
3. Installazione degli strumenti di elaborazione - OpenJade
3.1. Installazione di OpenJade
3.2. Installazione del DSSSL di Norman Walsh
3.3. Installazione dei DTD di DocBook
3.4. Installazione delle Entità ISO
3.5. Installazione del DSL di LDP
3.6. Installazione di HTMLDOC
4. Utilizzo di OpenJade
4.1. Trasformazione da SGML
4.2. Trasformazione da XML
4.3. Da HTML a PDF (opzionale)
5. Server per XML DocBook 4.1.2
5.1. Tomcat + Cocoon
5.2. Installazione dei fogli di stile XSL di Norman Walsh
5.3. Installazione dei fogli di stile XSL di LDP
5.4. Configurazione di sitemap.xmap
5.5. Accedere a contenuti XML DocBook 4.1.2 da un browser web
6. Ulteriori informazioni
6.1. News group
6.2. Mailing List
6.3. IRC
6.4. Siti web
6.5. Applicazioni per la scrittura e la modellazione in XML

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 - per gli aggiornamenti relativi a Cocoon e JRE. http://www.timebytes.com/

  2. Greg Ferguson - per le utili indicazioni/suggerimenti sulla mailing list di docbook.

  3. Kristin Thomas - per la revisione iniziale di questo documento.

  4. Luc de Louw - per i suggerimenti sulla sezione HTMLDOC (PDF -> HTML).

  5. Lloyd D Budd - per i suggerimenti che hanno consentito di migliorare molte delle sezioni del documento.

  6. Andrew Shugg - per aver corretto gli errori nella versione 2.0 di questo documento. Neep Consulting


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).


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.4. Entità ISO

Per comodità degli utenti, The Linux Documentation Project 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.6. Fogli di stile DSL personalizzati da LDP

LDP DSL è un foglio di stile personalizzato usato da The Linux Documentation Project (TLDP). È 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.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.

NotaNota
 

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 .


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.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 

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:

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

NotaCocoon 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.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 . Grazie.


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 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.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.

  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

NotaNota
 

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/.