DocBook XML/SGML Processing Using OpenJade

Saqib Ali

    <saqib@seagate.com>
   Diario delle Revisioni
   Revisione v2.2.8 2003-07-16 Revisionato da: es
   Aggiunte informazioni sulla sincronizzazione di JRE con
   Cocoon.
   Revisione v2.2.7 2003-07-09 Revisionato da: es
   Corretti collegamenti interrotti a LDP XSL e ad altri file
   specifici di LDP XSL.
   Revisione v2.2.6 2003-06-16 Revisionato da: sa
   Verificate le istruzioni con DocBook XSL 1.57.
   Revisione v2.2.5 2003-05-16 Revisionato da: sa
   Corretti i collegamenti interrotti nella sezione delle risorse
   esterne.
   Revisione v2.2.4 2003-04-20 Revisionato da: sa
   Aggiornati i collegamenti al nuovo sito delle demo. Aggiunti
   nuovi collegamenti nella sezione delle risorse.
   Revisione v2.2.3 2002-11-22 Revisionato da: sa
   Inseriti i suggerimenti degli utenti. Aggiunti nuovi
   collegamenti nella sezione delle risorse.
   Revisione v2.2.2 2002-10-09 Revisionato 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.1 2002-10-09 Revisionato da: sa
   Corretta la URL ai file di esempio.
   Revisione v2.2   2002-09-29 Revisionato da: as
   Piccole correzioni alla sezione su Cocoon.
   Revisione v2.1   2002-09-15 Revisionato da: sa
   Piccole correzioni alla sezione su Cocoon.
   Revisione v2.0   2002-09-10 Revisionato da: sa
   Aggiunta la sezione relativa all'utilizzo di Tomcat e Cocoon
   come server di contenuti per DocBook XML 4.1.2.
   Revisione v1.5   2002-08-11 Revisionato da: sa
   Inserita la sezione su XML con il relativo file di esempio.
   Revisione v1.4   2002-08-08 Revisionato da: sa
   Alcune importanti correzioni e modifiche suggerite da Lloyd D
   Budd. Grazie Lloyd. :)
   Revisione v1.3   2002-08-02 Revisionato da: sa
   Aggiunta la sezione sulle "ulteriori informazioni".
   Revisione v1.2   2002-07-23 Revisionato da: sa
   Aggiunta la sezione sulla conversione HTML -> PDF utilizzando
   HTMLDOC. Grazie a Luc De Louw per il suggerimento.
   Revisione v1.1   2002-07-19 Revisionato da: KET
   Corretti errori grammaticali, numerate le procedure.
   Revisione v1.0   2002-06-29 Revisionato da: sa
   Primo rilascio pubblico.

   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

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

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

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.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, DocBook SGML
   v3.1 e DocBook XML v4.1.2.

     Nota: Scaricare tutti gli archivi zip.
     _________________________________________________________

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

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/c
atalog

   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/c
atalog
     _________________________________________________________

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/dbtool
s/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/dtd
s/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/d
ocbook.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.
     _________________________________________________________

6.1. News group

   Alcuni news group di interesse sono:

    1. comp.text.sgml (facilemente accessibile da Google! Groups)
    2. comp.text.xml (facilemente accessibile da Google! Groups)
    3. htmldoc.general (il server è 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/i
       ndex.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/ind
       ex.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

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