
DocBook Install mini-HOWTORobert B Easter

   reaster@reaster.com

   Diario delle revisioni
   Revisione v1.8 2002-02-04 Corretto da: rbe

   Il DocBook-Install-mini-HOWTO  una guida pratica dettagliata per
   principianti che consente rapidamente di installare DocBook e di
   convertire file dal formato SGML ai formati HTML, PS e PDF su un
   sistema GNU/Linux; per altri sistemi pu essere analogo. Poich
   l'installazione di DocBook richiede file forniti in vari pacchetti
   distribuiti separatamente, pu essere disorientante per i
   principianti.

   Traduzione a cura di Giuseppe Briotti <g.briotti (at) mclink.it> e
   revisione a cura di Beatrice Torracca <beatricet (at) libero.it>.
     _________________________________________________________________

   Sommario
   1. Introduzione

        1.1. Informazioni su questo documento
        1.2. Cosa  DocBook
        1.3. Breve panoramica

   2. Scaricare i pacchetti

        2.1. OpenJade
        2.2. DTD DocBook per SGML
        2.3. Entit ISO8879 per SGML
        2.4. DSSSL DocBook
        2.5. SGMLtools-Lite
        2.6. HTMLdoc
        2.7. DocBook2X

   3. Installazione dei pacchetti

        3.1. Prima dell'installazione
        3.2. Installazione di OpenJade
        3.3. Le DTD DocBook per SGML
        3.4. Il DSSSL di DocBook
        3.5. SGMLtools-Lite
        3.6. htmldoc
        3.7. DocBook2X e SGMLS.pm (sgmlspl)
        3.8. $SGML_CATALOG_FILES

   4. Usare DocBook

        4.1. Generazione di HTML
        4.2. Generazione di rtf e tex
        4.3. Generazione di dvi e ps
        4.4. Generazione di pdf
        4.5. Utilizzare make
        4.6. Generazione di una pagina man

   A. Note Legali

        A.1. Copyright e Licenze
        A.2. Liberatoria

   B. GNU Free Documentation License

        0. PREAMBLE
        1. APPLICABILITY AND DEFINITIONS
        2. VERBATIM COPYING
        3. COPYING IN QUANTITY
        4. MODIFICATIONS
        5. COMBINING DOCUMENTS
        6. COLLECTIONS OF DOCUMENTS
        7. AGGREGATION WITH INDEPENDENT WORKS
        8. TRANSLATION
        9. TERMINATION
        10. FUTURE REVISIONS OF THIS LICENSE
        How to use this License for your documents

1. Introduzione

1.1. Informazioni su questo documento

L'ultima versione in inglese di questo mini-HOWTO pu essere trovata
all'indirizzo:

http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/

Si legga la sezione "Note Legali" in appendice per le informazioni sul
copyright, le licenze e la liberatoria riguardanti questo documento.
     _________________________________________________________________

1.2. Cosa  DocBook

DocBook  una definizione di tipo di documento (DTD, Document Type
Definition) per il linguaggio a marcatura SGML (Standard Generalized Markup
Language) che definisce un insieme di marcatori per documenti di testo, che
funzionano in modo molto simile a quanto avviene nel pi familiare
linguaggio HTML usato per il web.

DocBook  pensato per la realizzazione di libri ed articoli. Come tale,
fornisce marcatori specificatamente progettati per descrivere libri ed
articoli. Ad esempio, i marcatori DocBook <book> e <article> sono usati per
creare libri ed articoli. All'interno di questi documenti, vengono
utilizzati i marcatori <chapter>, <sect1> e <para>. I file DocBook SGML sono
archiviati in file di testo con l'estensione sgml o gml.

Quando trattato, un singolo file DocBook SGML pu produrre in uscita file
nei formati html, pdf, ps, txt ed altri ancora, adatti tanto alla
pubblicazione in linea che alla stampa. Il processo di conversione 
governato dai fogli di stile, che possono generare automaticamente indici,
numerazione delle pagine, numerazione di capitoli e sezioni ed altre
caratteristiche.

DocBook  anche progettato per realizzare le pagine man di unix, consentendo
di creare documenti <refentry>. Se non si conosce cosa sia una pagina man,
si provi a digitare il comando man man su un terminale.
     _________________________________________________________________

1.3. Breve panoramica

Di seguito una breve descrizione dei pacchetti su cui lavoreremo nelle
prossime sezioni:

   OpenJade. OpenJade  una implementazione del Document Style Semantics
   and Specification Language (DSSSL), secondo gli standard
   internazionali ISO/IEC 10179:1996. OpenJade utilizza il linguaggio
   DSSSL per elaborare file nei formati SGML e XML. In particolare,
   utilizza il codice contenuto nei file Modular DocBook Stylesheets per
   trasformare file DocBook SGML/XML in altri formati quali html, tex,
   rtf, txt ed altri ancora. OpenJade  il motore fondamentale per
   convertire un file DocBook in altri formati. Il formato TeX in uscita
    utilizzato principalmente come formato intermedio per ottenere file
   dvi, pdf, e ps attraverso le macro di TeX ed i convertitori dvi.

   DocBook SGML DTD. Il file DocBook Document Type Definition (DTD) sono
   file SGML che definiscono il linguaggio DocBook. Esso stabilisce
   l'insieme di marcatori validi e le regole del loro utilizzo. OpenJade
   richiede l'accesso ai file DTD per ogni tipo di documento che viene
   analizzato.

   Entit ISO8879 per SGML. Le Entit definiscono come rappresentare
   alcuni caratteri speciali per i quali non esiste un tasto o che hanno
   un particolare significato in SGML. Esempi familiari gi dall'HTML
   includono "&amp;"='&', "&gt;"='>' e "&lt;"='<'.

   DocBook DSSSL (Modular DocBook Stylesheets). I file DSSSL (estensione
   dsl) per un particolare DTD, in questo caso DocBook, specificano come
   convertire file DocBook in html, rtf, tex, ecc. Un file dsl  un dato
   per l'openjade, insieme al file DocBook sgml da trattare, e dice ad
   openjade come trasformare e rappresentare il documento in un file di
   altro formato. Il file dsl per formati in linea (html)  spesso
   differente da quello per la stampa (dvi, pdf, ps).

   SGMLtools-Lite. SGMLtools-Lite  una interfaccia per eseguire il
   comando openjade e le macro TeX, jadetex e pdfjadetex incluse nel
   pacchetto OpenJade. Convertire un file DocBook in ps o pdf  un
   processo che richiede due o tre fasi. OpenJade crea un file tex che
   diventa il dato in ingresso per jadetex per produrre un file dvi, e
   per pdfjadetex se si vuole creare un file pdf. Un file ps  ottenuto
   passando poi il file dvi al comando dvips. Lo script sgmltools
   fornisce un singolo comando con cui realizzare tutti questi processi.

   HTMLdoc. HTMLdoc  un programma libero che consente di convertire file
   html in file pdf o ps.

   SGMLSpm e docbook2X. Insieme, questi due programmi sono utilizzati per
   generare pagine man. SGMLSpm  una libreria di moduli perl5 per
   convertire l'output analizzato da onsgmls, un programma incluso nel
   pacchetto OpenJade. SGMLSpm include una applicazione chiamata sgmlspl,
   per usare la libreria SGMLSpm. Sgmlspl ha bisogno di "file di
   specifica", che sono disponibili da varie altre fonti in Internet, per
   ogni tipo di trasformazioni di documento che occorre compiere.
   DocBook2X  un pacchetto che fornisce i file di specifica per
   trasformare i file DocBook in pagine man.
     _________________________________________________________________

2. Scaricare i pacchetti

In questa sezione, verranno individuati e scaricati i programmi da Internet.
     _________________________________________________________________

2.1. OpenJade

OpenJade  un progetto software open-source attivamente mantenuto e basato
sul pacchetto Jade di James Clark. Scaricare l'ultimo rilascio stabile
dall'indirizzo:

http://openjade.sourceforge.net/

OpenJade include inoltre il pacchetto OpenSP e le macro TeX, jadetex e
pdfjadetex, per convertire file nei formati dvi e pdf. Con questo pacchetto
sono forniti i seguenti programmi:

     * openjade
     * onsgmls
     * osgmlnorm
     * ospam
     * ospent
     * osx

   Per usare jadetex e pdfjadetex per creare file dvi, ps e pdf, 
   necessario avere una installazione funzionante di TeX (tex). Se non ne
   avete una, controllate la vostra distribuzione Linux per individuare
   un pacchetto binario che possa essere scaricato ed installato.
   Altrimenti,  possibile scaricare la distribuzione teTeX del TeX dal
   sito:

   http://www.tug.org/tetex/
     _________________________________________________________________

2.2. DTD DocBook per SGML

Le DTD DocBook per SGML e XML sono mantenute da un comitato tecnico al sito
Oasis-Open.ORG. Scaricare l'ultima versione (ed ogni altra versione pi
vecchia di cui si possa aver bisogno) dell'SGML DocBook dal sito:

http://www.oasis-open.org/docbook/sgml/index.shtml
     _________________________________________________________________

2.3. Entit ISO8879 per SGML

Le entit definiscono la rappresentazione di simboli o caratteri speciali o
non presenti sulla tastiera, inclusi i simboli matematici, e le entit che
potrebbero essere familiari dall'uso di HTML. Questi file delle entit
devono essere installati per avere una configurazione corretta.

     * Risorse disponibili sul sito OASIS:
          + http://www.oasis-open.org/cover/topics.html#entities
          + http://www.oasis-open.org/cover/ISOEnts.zip
          + http://www.oasis-open.org/cover/isoENT-tar.gz

   Il file ISOEnts.zip pu essere semplicemente decompresso con unzip
   nella directory dove sono state decompresse le DTD DocBook (sempre con
   unzip) senza richiedere niente altro che i file contenuti in
   isoENT-tar.gz. Ancora una volta, i file in isoENT-tar.gz devono essere
   decompressi nella directory delle DTD DocBook (si veda la prossima
   sezione sull'installazione per ulteriori dettagli), ma i nomi di
   questi file hanno l'estensione ".ent". Occorre modificare l'estensione
   di questi file in ".gml". Ci si pu fare manualmente o  possibile
   scaricare ed utilizzare il file seguente, realizzato dall'autore, che
   contiene tutti i file di ISOEnts.zip e di isoENT-tar.gz:

   http://reaster.com/iso8879-entities.tar.gz
     _________________________________________________________________

2.4. DSSSL DocBook

I file del Document Style Semantics and Specification Language (DSSSL) per
DTD DocBook (SGML/XML) realizzati da Norman Walsh sono mantenuti al DocBook
Open Repository al sito SourceForge. Questi file, anche conosciuti come
Modular DocBook Stylesheets (fogli di stile modulari per DocBook), dicono ad
openjade cosa fare al momento di convertire i propri file SGML DocBook in
altri formati. Un file "dsl" specifica cose come riassociare i marcatori da
un DTD in un altro DTD ed altre conversioni programmate, definite nel
linguaggio DSSSL. Il linguaggio DSSSL  strutturato in un gruppo di
linguaggi differenti, ma alla base di tutti vi  il Core Expression Language
che  basato su Scheme.

Il pacchetto e la documentazione del DSSSL DocBook possono essere scaricati
dal sito del DocBook DSSSL Stylesheets Project

Il Linux Documentation Project ha un foglio di stile personalizzato che
mette a disposizione alcune interessanti caratteristiche di stile. pu
essere scaricato dal sito:

http://www.linuxdoc.org/authors/tools/ldp.dsl
     _________________________________________________________________

2.5. SGMLtools-Lite

SGMLtools-Lite  una interfaccia utente per openjade, jadetex, pdfjadex,
dvips ed altri programmi. Consente di generare tutti i formati possibili con
questi strumenti mediante un singolo comando. L'ultima versione pu essere
scaricata dal sito:

http://sourceforge.net/projects/sgmltools-lite/

Questo pacchetto  opzionale, ma talvolta rende le cose pi facili.
     _________________________________________________________________

2.6. HTMLdoc

HTMLdoc  un programma gratuito per convertire siti web nei formati Portable
Document Format (pdf) o PostScript (ps). Per il pdf, crea anche un albero di
segnalibri che rendono facile la navigazione. Sia htmldoc che pdfjadetex
emettono file pdf, ma dal formato leggermente differente. Si provino
entrambi per verificare quale di essi si adatta meglio per un determinato
file docbook. Si guardino i collegamenti seguenti per i siti da cui
scaricare.

Si pu scaricare l'ultima versione di HTMLdoc dal sito ftp della Easy
Software Products.
     _________________________________________________________________

2.7. DocBook2X

DocBook2X richiede il perl5 ed il modulo perl SGMLS.pm, disponibili presso
il Comprehensive Perl Archive Network (CPAN). SGMLS.pm comprende le librerie
ed un programma chiamato sgmlspl che traduce i file DocBook in altri formati
utilizzando dei file di specifica. I file di specifica sono file in perl che
forniscono la logica per la traduzione in un determinato formato.

http://www.cpan.org/

http://docbook2x.sourceforge.net/
     _________________________________________________________________

3. Installazione dei pacchetti

3.1. Prima dell'installazione

Le sezioni seguenti suggeriscono come si dovrebbero installare i pacchetti
scaricati per creare ed impostare l'ambiente SGML DocBook. Gli esempi
possono fare riferimento a versioni pi vecchie dei pacchetti, ma si
dovrebbero adattare gli esempi, utilizzando le versioni pi recenti.

Per le informazioni pi aggiornate ed autorevoli, si legga sempre la
documentazione fornita con il pacchetto che si sta installando. Spesso, si
troveranno i file README ed INSTALL dopo aver decompresso gli archivi.

Le istruzioni dettagliate che seguono potrebbero non funzionare esattamente
come mostrato, poich i pacchetti cambiano ogni volta. Comunque, le
istruzioni dovrebbero fornire una idea generale sulla procedura per far
funzionare SGML DocBook.
     _________________________________________________________________

3.2. Installazione di OpenJade

3.2.1. openjade

I comandi da eseguire sono i seguenti, ma ci si ricordi di leggere i file
forniti con OpenJade per verificare se occorre fare qualcosa di particolare
per la propria piattaforma:
                cd /usr/local
                tar -xvzf ~/openjade-1.3.tar.gz
                cd openjade-1.3
                ./configure --prefix=/usr/local/openjade-1.3
                make
                make install

                # una volta installati, i file oggetto, ecc. possono essere can
cellati.
                make clean

L'installazione mette le librerie nella directory
/usr/local/openjade-1.3/lib, perci  preferibile aggiungerla al
/etc/ld.so.conf e lanciare ldconfig. Aggiungere /usr/local/openjade-1.3/bin
alla variabile $PATH.

   Si potrebbe rimanere sorpresi dal fatto che si sono scaricati i
   sorgenti di openjade direttamente nella directory /usr/local. L'autore
   ha sperimentato qualche problema nell'installazione di openjade.
   Comunque, con le nuove versioni di OpenJade, si pu provare una
   collocazione convenzionale (/usr/local/src) dei sorgenti del pacchetto
   openjade, modificando l'opzione --prefix che identifica la posizione
   di installazione, e vedere come va.
     _________________________________________________________________

3.2.2. jadetex & pdfjadetex

Come detto, jadetex e pdfjadetex sono macro TeX fornite nel pacchetto di
OpenJade. Possono essere trovati in /usr/local/openjade-3.1/dsssl. Una utile
guida sull'installazione di queste macro  stata realizzata da Frank
Atanassow Christoph e pu essere trovata agli indirizzi:

ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf

http://reaster.com/installjadetex.pdf

Quanto segue  basato sulle istruzioni contenute in install.pdf:
     _________________________________________________________________

3.2.2.1. Creare il contesto "hugelatex" (se necessario)

Le macro tex jadetex e pdfjadetex richiedono pi memoria che una regolare
esecuzione di tex. La configurazione predefinita del limite di memoria di
tex  spesso troppo vincolante. Il file di configurazione di tex, texmf.cnf,
pu essere modificato e le variabili che limitano l'uso della memoria
possono essere aumentate. Tuttavia, invece che modificare il file di
configurazione texmf.cnf, che consentirebbe a tex di utilizzare pi memoria
in tutte le istanze,  possibile creare un contesto tex personalizzato,
chiamato hugelatex. Se sul proprio sistema  gi configurato il contesto
hugelatex,  possibile saltare questa sottosezione (si verifichi con which
hugelatex).

Verificare se  stato installato un TeX funzionante ed individuarne la
directory:
                bash$ which tex
                /usr/share/texmf/bin/tex
                bash$ kpsewhich -expand-var='$TEXMFMAIN'
                /usr/share/texmf
                bash$

   Con il comando which si dovrebbe trovare la collocazione del programma
   tex. Se non viene trovato, sar necessario installare teTeX e quindi
   tornare a questo punto. kpsewhich  uno strumento fornito con teTeX
   che individua la directory principale di tex se tutto va bene.

   Una volta che il percorso della directory texmf  noto, si pu
   iniziare l'installazione:
                cd /usr/share/texmf
                cd tex/latex
                cp -r config config-temp
                cd config-temp
                tex -ini -progname=hugelatex latex.ini
                mv latex.fmt hugelatex.fmt
                mv hugelatex.fmt /usr/share/texmf/web2c
                cd ..
                rm -r config-temp
                cd /usr/share/texmf/bin
                ln -s tex hugelatex
                cd /usr/share/texmf/web2c

   La directory web2c contiene il file di configurazione texmf.cnf. Fare
   una copia di riserva di questo file: cp texmf.cnf texmf.cnf.orig. Si
   modifichi il file con un qualunque editor, aggiungendo le seguenti
   linee alla fine del file:
                % hugelatex settings
                extra_mem_top.hugelatex = 8000000
                extra_mem_bot.hugelatex = 8000000
                hash_extra.hugelatex = 15000
                pool_size.hugelatex = 5000000
                string_vacancies.hugelatex = 45000
                max_strings.hugelatex = 55000
                pool_free.hugelatex = 47500
                nest_size.hugelatex = 500
                param_size.hugelatex = 1500
                save_size.hugelatex = 5000
                stack_size.hugelatex = 15000

                % jadetex
                extra_mem_top.jadetex = 8000000
                extra_mem_bot.jadetex = 8000000
                hash_extra.jadetex = 20000
                pool_size.jadetex = 5000000
                string_vacancies.jadetex = 45000
                max_strings.jadetex = 55000
                pool_free.jadetex = 47500
                nest_size.jadetex = 500
                param_size.jadetex = 1500
                save_size.jadetex = 5000
                stack_size.jadetex = 15000

                % pdfjadetex
                extra_mem_top.pdfjadetex = 8000000
                extra_mem_bot.pdfjadetex = 8000000
                hash_extra.pdfjadetex = 20000
                pool_size.pdfjadetex = 5000000
                string_vacancies.pdfjadetex = 45000
                max_strings.pdfjadetex = 55000
                pool_free.pdfjadetex = 47500
                nest_size.pdfjadetex = 500
                param_size.pdfjadetex = 1500
                save_size.pdfjadetex = 5000
                stack_size.pdfjadetex = 15000

   Nell'esempio, siamo andati avanti aggiungendo anche le voci per
   jadetex e pdfjadetex, che saranno configurati in seguito. Si possono
   fare delle prove modificando queste impostazioni di memoria, se si
   dovessero verificare problemi con questi valori.

   Dopo averlo configurato come sopra, hugelatex potrebbe non funzionare,
   finch non sia stato lanciato il programma texhash:
                root# texhash
                texhash: Updating /usr/share/texmf/ls-R...
                texhash: Updating /var/cache/fonts/ls-R...
                texhash: Done.
                root#
     _________________________________________________________________

3.2.2.2. jadetex & pdfjadetex

La configurazione di jadetex e pdfjadetex  simile a quella di hugelatex.
                cd /usr/local/openjade-1.3/dsssl
                make -f Makefile.jadetex install
                # il comando make crea ed installa i
                # file .fmt in /usr/share/texmf/web2c

                # si creino i link simbolici...
                cd /usr/share/texmf/bin
                ln -s tex jadetex
                ln -s pdftex pdfjadetex

                # alla fine, si esegua texhash.
                root# texhash

Questo Makefile utilizza il contesto hugelatex, quindi hugelatex deve essere
stato gi configurato. Quando tex  lanciato come hugelatex, jadetex o
pdfjadetex, riceve il suo nome di programma (contesto) dalla variabile
argv[0] nell'ambiente. Quindi, esegue una scansione del file texmf.cnf, ed
utilizza ogni impostazione trovata, specifica del contesto scelto. Anche i
file di formato (.fmt) in /usr/share/texmf/web2c sono caricati in base al
contesto.

   Il comando jadetex da un file tex, generato da openjade, crea un file
   dvi. pdfjadetex da un file tex, generato da openjade, crea un file
   pdf. Il programma dvips da un file dvi crea un file PostScript ps che
    possibile inviare alla stampante o visualizzare con ghostscript gs.
     _________________________________________________________________

3.3. Le DTD DocBook per SGML

3.3.1. Decomprimere le DTD DocBook per SGML

Le DTD DocBook sono semplicemente dei file di testo sgml, quindi non c'
nulla da compilare. Semplicemente decomprimere gli archivi con unzip da
qualche parte:
                # DocBook DTD V4.1 in
                # /usr/local/share/sgml/docbook/4.1

                cd /usr/local/share
                mkdir sgml; cd sgml
                mkdir docbook; cd docbook
                mkdir 4.1; cd 4.1
                unzip -a ~/docbk41.zip

Se si installa doctools-1.2 dalla distribuzione XFree86, verranno poste
alcune versioni pi vecchie delle DTD DocBook, quali la 2.4.1/ e la 3.0/ in
sottodirectory di docbook.

   Vi sono alcune differenze tra le varie versioni delle DTD DocBook. I
   file xxissues.txt documentano questi problemi. Sono stati aggiunti,
   rimossi e rinominati dei marcatori tra una versione e l'altra.

   Se dovesse essere necessario utilizzare la DTD DocBook V3.1, 
   disponibile allo stesso indirizzo dal quale  stata scaricata la
   versione V4.1. La versione V3.1  molto usata, quindi  una buona idea
   quella di scaricarla ed installarla nella sottodirectory 3.1/.
     _________________________________________________________________

3.3.2. Decomprimere le entit ISO8879

Per ogni versione di DTD DocBook installata, si vada nella relativa
directory e vi si decomprima il file iso8879-entities.tar.gz:
                cd /usr/local/share/sgml/docbook/4.1
                tar -xvzf ~/iso8879-entities.tar.gz

In ogni directory DocBook, ci dovrebbe essere un file docbook.cat od un file
catalog, od entrambi. Se entrambi sono presenti, dovrebbero essere identici.
Se  presente solo il file docbook.cat, si prosegua creando un link
simbolico:

                # se necessario...
                cd /usr/local/share/sgml/docbook/4.1
                ln -s docbook.cat catalog
     _________________________________________________________________

3.4. Il DSSSL di DocBook

L'installazione del DSSSL DocBook, che funziona con tutte le versioni di
DocBook, consiste solo nella decompressione con unzip dell'archivio da
qualche parte.
                cd /usr/local/share/sgml
                mkdir dsssl; cd dsssl
                unzip -a ~/db160.zip

                # se si  scaricato il foglio di stile personalizzato ldp.dsl,
                # lo si copi...
                cd docbook
                cp ~/ldp.dsl html
                cp ~/ldp.dsl print
                # copiarlo in entrambe le directory.

Questo  tutto quanto  necessario per installare il DSSSL, eccettuata
l'impostazione della variabile $SGML_CATALOG_PATH, che verr discussa dopo.
Non ci si dimentichi di riordinare le modalit ed i proprietari/gruppi dei
file decompressi: spesso sono mischiati ed inadatti.
     _________________________________________________________________

3.5. SGMLtools-Lite

Se lo si desidera,  possibile installare SGMLtools-Lite, ma questo 
opzionale. L'installazione  convenzionale:
                cd /usr/src
                tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
                cd sgmltools-lite-3.0.2
                ./configure
                make install

Questi comandi installano lo script sgmltools in python nella directory
/usr/local/bin. Si noti che  necessario python, quindi se non lo si ha,
questo pacchetto  inutile.

   Una cosetta da fare per far funzionare lo script sgmltools, 
   modificarlo ed impostare il percorso di openjade: vi `which
   sgmltools`. Se ne consulti la documentazione per saperne di pi.
     _________________________________________________________________

3.6. htmldoc

3.6.1. Dai file binari

 preferibile scaricare una distribuzione binaria di htmldoc per la propria
piattaforma. L'installazione  semplice: basta solo decomprimere l'archivio
e lanciare la configurazione. Si legga la documentazione fornita col
pacchetto per ulteriori informazioni.
     _________________________________________________________________

3.6.2. Dai file sorgenti

Se si scaricano i sorgenti,  necessario anche il Fast Light Tool Kit od
altrimenti non si riuscir a fare il link:

http://www.fltk.org/

L'installazione  del tipo autoconf. Semplicemente si lanci lo script
configure, make, make install. Se tutto va bene, verr installato nella
directory /usr/bin.
     _________________________________________________________________

3.6.3. ldp_print

Il programma htmldoc ha (o aveva) qualche difetto nella elaborazione di file
html prodotti da openjade. Per esempio, gli elenchi puntati non sono resi
adeguatamente e le aree ombreggiate non lo sono sempre.

Per correggere questo problema,  disponibile uno script in perl (ldp_print)
sul sito LinuxDoc.org. Lo script lpd_print analizza un file html unico (non
spezzetato) prodotto da openjade e quindi esegue htmldoc su di esso per
produrre file pdf e ps correttamente resi.

     Suggerimento: Procuratevelo!

                tar -xvzf ldp_print.tar.gz
                cd ldp_print

                # copiare la libreria da qualche parte, dove
                # il perl lo possa trovare.
                cp fix_print_html.lib /usr/lib/perl5/site_perl

                cp ldp_print /usr/local/bin

   Si dia un'occhiata allo script, nel caso ci siano righe di codice da
   adattare al proprio sistema. Forse un giorno i bachi di htmldoc
   saranno corretti e questo script non sar pi necessario.
     _________________________________________________________________

3.7. DocBook2X e SGMLS.pm (sgmlspl)

3.7.1. sgmlspl

Prima che i file di specifica di DocBook2X siano utilizzabili, occorre
installare il modulo SGMLS.pm per perl versione 5, ammesso che sia
installato perl versione 5. L'installazione di questo modulo non 
automatica, come per la maggior parte dei moduli perl. Utilizza un Makefile
che deve essere modificato prima di lanciare il comando make.
                cd /usr/src
                tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
                cd SGMLSpm

                # Modificare il Makefile
                vi Makefile
                # Nelle opzioni utente del Makefile
                # si imposti ogni cosa correttamente per
                # il proprio sistema.
                # Ad esempio:
                #       PERL = /usr/bin/perl
                #       BINDIR = /usr/local/bin
                #       PERL5DIR = /usr/lib/perl5/site_perl
                #       MODULEDIR = ${PERL5DIR}/SGMLS
                #       SPECDIR = ${PERL5DIR}
                #       HTMLDIR= /usr/local/apache/htdocs

                make install

sgmlspl verr copiato in /usr/local/bin.
     _________________________________________________________________

3.7.2. docbook2X (docbook2man-spec.pl)

DocBook2X non contiene programmi da compilare od installare con install,
sebbene abbia alcuni script a cui dare un'occhiata, quindi tutto quello che
c' da fare  decomprimerlo da qualche parte.
                cd /usr/local/share/sgml
                tar -xvzf ~/docbook2X-0.6.0.tar.gz
                cd docbook2X

Nella directory decompressa c' il file docbook2man-spec.pl ed una patch per
correggerne alcuni errori. Applicare la patch  opzionale ma raccomandabile.

                patch docbook2man-spec.pl docbook2man-spec.pl.patch

   Dopo, nella sezione Usare DocBook, si vedr come usare sgmlspl e
   docbook2man-spec.pl per generare una pagina man da un documento
   DocBook <refentry>.
     _________________________________________________________________

3.8. $SGML_CATALOG_FILES

La variabile d'ambiente $SGML_CATALOG_FILES  utilizzata da openjade (ed
altri programmi SGML) per localizzare le DTD e i DSL (fogli di stile). I
programmi SGML non possono funzionare se non trovano questi file, che sono
stati decompressi in diverse directory. Ammesso che l'installazione sia
stata compiuta come indicato, di seguito  spiegato come impostare la
variabile $SGML_CATALOG_FILES all'interno del file /etc/profile:
###############################################################################
###########
# SGML DocBook - openjade sgmltools-lite
JADE_HOME=/usr/local/openjade-1.3
SGML_SHARE=/usr/local/share/sgml

PATH=$PATH:$JADE_HOME/bin

# fogli di stile DSSSL
#       Modular DocBook Stylesheets di Norman Walsh
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
#       fogli di stile OpenJade
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
#       fogli di stile sgmltools-lite
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmlto
ols.cat

# DocBook DTD
#       da OASIS-Open.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
#       Questi pi vecchi sono stati installati con doctools-1.2 di XFree86.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog

# file di catalogo sgmltools-lite per LinuxDoc
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog

export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
###############################################################################
###########

Salvato il file profile, si effettui il logout e quindi il login perch le
modifiche abbiano effetto.

   L'installazione  completata! Nella prossima sezione si verificher
   l'installazione e si convertiranno alcuni file DocBook.
     _________________________________________________________________

4. Usare DocBook

Una volta che tutto  installato,  tempo di verificare quanto fatto e
vedere come usare openjade e gli altri strumenti.

   Figura 1. File di esempio DocBook SGML - test.sgml
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<article lang="en">
<articleinfo>
        <title>This is a Test</title>

        <author>
                <firstname>John</firstname>
                <surname>Doe</surname>
                <othername role="mi">L</othername>
                <affiliation>
                        <address>
                        <email>j.doe@jdoe dot com</email>
                        </address>
                </affiliation>
        </author>

        <revhistory>
                <revision>
                <revnumber>v1.0</revnumber>
                <date>2000-12-30</date>
                <authorinitials>jld</authorinitials>
                </revision>
        </revhistory>

        <abstract>
        <para>
        This is a test DocBook document.
        </para>
        </abstract>

</articleinfo>

<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
        <sect2>
        <title>Test 1.1</title>
        <para>
        Test section 1.1
        </para>
        </sect2>

        <sect2>
        <title>Test 1.2</title>
        <para>
        <screen>
                -- Test section 1.2
                openjade -t sgml -d $DSLFILE test.sgml
        </screen>
        </para>
        </sect2>

</sect1>

<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>

        <sect2>
        <title>Test 2.1</title>
        <para>
        Test section 2.1
        </para>
        </sect2>

        <sect2>
        <title>Test 2.2</title>
        <para>
        Test section 2.2
        </para>
        </sect2>

</sect1>
</article>

Per una guida a DocBook ed una spiegazione degli elementi DocBook, si veda:

   DocBook: The Definitive Guide. http://www.docbook.org/tdg/en/
     _________________________________________________________________

4.1. Generazione di HTML

4.1.1. docbook.dsl

   Figura 2. Generazione di HTML utilizzando docbook.dsl
bash$ ls -l
total 4
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
bash$ echo $SGML_SHARE
/usr/local/share/sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml
[omissis - le voci di catalogo DTDDECL non sono supportate, ripetuto]
bash$ ls -l
total 12
-rw-r--r--   1 reaster  users        1885 Dec 31 17:34 t1.htm
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1544 Dec 31 17:34 x27.htm
bash$

Gli avvisi riguardanti DTDDECL possono essere ignorati. Possono essere un
po' noiosi, ma questi avvisi sono normali quando si usa openjade. Altri
avvisi ed errori devono essere controllati e spesso indicano errori di
sintassi che devono essere corretti.

   Vengono creati due file htm, uno per ogni <sect1>. I nomi dei file non
   sono molto descrittivi. La sezione uno compare sulla medesima pagina
   delle informazioni sull'articolo. Questi sono i risultati ottenuti con
   il foglio di stile predefinito docbook.dsl, fornito con i Modular
   DocBook Stylesheets.

   I fogli di stile possono essere personalizzati per migliorare le
   impostazioni predefinite. Se si  scaricato il file ldp.dsl del Linux
   Documentation Project e lo si  installato come mostrato nella sezione
   3.3, si avr gi a disposizione un foglio di stile personalizzato.
     _________________________________________________________________

4.1.2. ldp.dsl

   Figura 3. Generazione di HTML utilizzando ldp.dsl
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml
bash$ ls -l
total 16
-rw-r--r--   1 reaster  users        2006 Dec 31 18:00 index.html
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1677 Dec 31 18:00 test1.html
-rw-r--r--   1 reaster  users        1598 Dec 31 18:00 test2.html
bash$

   Con il file ldp.dsl, il risultato sar migliore:

     * Le informazioni sull'articolo sono contenute in un file "index"
       appositamente creato.
     *  stato generato automaticamente un indice.
     * Ogni sezione <sect1>  contenuta in un proprio file.
     * I nomi dei file sono derivati dagli attributi ID degli elementi
       <sect1>.
     * L'estensione dei file  cambiata in html.
     * Gli elementi <screen> sono ombreggiati.

   Si noti come il file ldp.dsl  stato scritto nella linea di comando:
   vi sono aggiunti i caratteri "#html". ldp.dsl contiene due elementi
   <STYLE-SPECIFICATION>, uno con l'attributo ID="html" e l'altro con
   ID="print". Questo seleziona lo stile html all'interno del file
   ldp.dsl. Il DSSSL DocBook contiene il supporto per convertire i file
   DocBook nei formati html e per la stampa. Nella sezione 3.3, si 
   copiato il file ldp.dsl all'interno di entrambe le directory print e
   html. Quando si genera un output html, si dovrebbe selezionare lo
   stile html come fatto sopra. Quando si generano altri tipi di file,
   quali rtf e tex, questi rientrano nello stile di stampa e quindi si
   dovrebbe selezionare tale stile dal ldp.dsl. L'alternativa  di
   commentare o cancellare lo stile di stampa o lo stile html nelle copie
   di ldp.dsl nelle relative directory. Se un file dsl contiene pi di
   una specifica di stile e nessuna viene selezionata, come nel
   precedente esempio, allora risulter selezionato il primo stile
   incontrato nel file. Nel file ldp.dsl il primo stile presente  quello
   di stampa, che quindi  quello selezionato per definizione. Di
   conseguenza, nell'esempio precedente, non aggiungendo la
   specificazione di stile "#html" all'indicazione del file ldp.dsl quale
   foglio di stile dsssl, risulter selezionata, ed utilizzata per
   generare html, la specifica di stile "print". Funzioner, ma la resa
   sar diversa, poich  pensata per essere selezionata all'interno del
   contesto print/ldp.dsl.

   Per imparare di pi su come sono realizzate le personalizzazioni dei
   fogli di stile, si legga la documentazione per i Modular DocBook
   Stylesheets. Le personalizzazioni essenzialmente interessano
   impostazioni di parametri booleani per selezionare o deselezionare le
   diverse caratteristiche dello stile. Si pu programmare una logica di
   stile completamente nuova utilizzando il linguaggio DSSSL.

   L'opzione di openjade "-t tipo_di_output" specifica il tipo di output.
   L'opzione "-d dsssl_spec"  il percorso del foglio di stile dsssl da
   utilizzare. Nell'esempio precedente, il tipo di output specificato 
   l'sgml, che  utilizzato per le trasformazioni da SGML a SGML. L'HTML,
   definito attraverso la HTML Document Type Definition (DTD),  un
   documento di tipo SGML, come lo  DocBook, quindi "sgml"  la corretta
   opzione per il tipo di output. Gli altri due tipi di output
   comunemente usati sono "rtf" e "tex". L'opzione tex verr usata in
   seguito come formato intermedio per la generazione di file nel formato
   pdf e ps. L'opzione dsssl_spec deve indicare un file dsl, non una
   directory.
     _________________________________________________________________

4.2. Generazione di rtf e tex

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgm
l
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgm
l
bash$ ls -l
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
     _________________________________________________________________

4.3. Generazione di dvi e ps

   Figura 4. Esecuzione di jadetex per generare un file Device
   Independent (dvi).
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
No file test.aux.
(/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd)

LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238.


LaTeX Warning: Reference `20' on page 1 undefined on input line 262.


LaTeX Warning: Reference `23' on page 1 undefined on input line 285.


LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316.


LaTeX Warning: Reference `30' on page 1 undefined on input line 340.


LaTeX Warning: Reference `33' on page 1 undefined on input line 363.

[1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux)

LaTeX Warning: There were undefined references.

 )
Output written on test.dvi (3 pages, 34984 bytes).
Transcript written on test.log.
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         771 Dec 31 20:55 test.aux
-rw-r--r--   1 reaster  users       34984 Dec 31 20:55 test.dvi
-rw-r--r--   1 reaster  users        5072 Dec 31 20:55 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
Output written on test.dvi (3 pages, 34148 bytes).
Transcript written on test.log.
You have new mail in /var/spool/mail/reaster
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

   La prima volta che viene eseguito jadetex, vengono mostrati degli
   avvisi. Possono essere ignorati. Lanciando il comando una seconda
   volta, questi non appariranno pi.

   Figura 5. Esecuzione di dvips per generare un file PostScript (ps).
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ dvips test.dvi
This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
' TeX output 2000.12.31:2058' -> test.ps
<texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3]
bash$ ls -l
total 116
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

   Figura 6. Esecuzione di htmldoc per generare un file PostScript (ps).
bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htm
ldoc.ps -
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 00:44 test-htmldoc.ps
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$

   Se il file ps non compare come atteso, questo pu essere dovuto a
   bachi in htmldoc. Si guardi all'interno dello script ldp_print se si
   vuole utilizzarlo per creare file ps.
     _________________________________________________________________

4.4. Generazione di pdf

   Figura 7. Esecuzione di pdfjadetex per generare un file Portable
   Document Format (pdf).
bash$ ls -l
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ pdfjadetex test.tex
This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
(test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/context/base/supp-pdf.tex
(/usr/share/texmf/tex/context/base/supp-mis.tex
loading : Context Support Macros / Missing
)
loading : Context Support Macros / PDF
) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
 (test.aux) )<8r.enc>
Output written on test.pdf (3 pages, 9912 bytes).
Transcript written on test.log.
bash$ ls -l
total 128
-rw-r--r--   1 reaster  users         753 Dec 31 21:13 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        5075 Dec 31 21:13 test.log
-rw-r--r--   1 reaster  users        9912 Dec 31 21:13 test.pdf
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]

pdfjadetex deve essere eseguito fino a tre volte per risolvere tutti i
riferimenti interni per cose come i numeri di pagina dell'indice.

   Figura 8. Esecuzione di htmldoc per generare un file Portable Document
   Format (pdf).
bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
bash$ ldp_print test-htmldoc.htm
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 01:17 test-htmldoc.pdf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$

   Se abilitato all'interno dello script ldp_print, questo dovrebbe
   generare anche un file ps.
     _________________________________________________________________

4.5. Utilizzare make

Ripetere i comandi per generare i file in uscita pu essere noioso. Il
comando make funziona perfettamente per automatizzare il procedimento.

   Figura 9. File: Makefile - generazione automatica di documenti.
# Generazione di versioni per la visualizzazione e la stampa da file sorgente S
GML

BASENAME=DocBook-Install

# File sorgente SGML
SGML_FILE=$(BASENAME).sgml

# Fogli di stile
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html

# File prodotti
HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf
DVI_FILE=$(BASENAME).dvi
PS_FILE=$(BASENAME).ps


# Regole di costruzione

html: $(HTML_FILE)

htm: $(HTM_FILE)

tex: $(TEX_FILE)

rtf: $(RTF_FILE)

pdf: $(PDF_FILE)

dvi: $(DVI_FILE)

ps: $(PS_FILE)

all: html htm tex rtf pdf dvi ps

clean:
        rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
        rm -f *.html

distclean: clean
        rm -f $(BASENAME).tgz

package:
        rm -f $(BASENAME).tgz
        tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
        mv /tmp/$(BASENAME).tgz .

dist: clean package

distall: all package


# Regole di compilazione

$(HTML_FILE): $(SGML_FILE)
        openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)

$(HTM_FILE): $(SGML_FILE)
        openjade -t sgml -V nochunks -d $(DSL_HTML) \
        $(SGML_FILE) > $(HTM_FILE)

$(TEX_FILE): $(SGML_FILE)
        openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)

$(RTF_FILE): $(SGML_FILE)
        openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)

# [pdf]jadetex deve essere eseguito 3 volte per risolvere tutti i riferimenti.
#$(PDF_FILE): $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)
#       pdfjadetex $(TEX_FILE)

# Questo *dovrebbe* funzionare, ma htmldoc ha dei bachi...
#$(PDF_FILE): $(SGML_FILE)
#       openjade -t sgml -V nochunks -d $(DSL_HTML) \
#       $(SGML_FILE) | htmldoc -f $(PDF_FILE) -

# Si deve usare ldp_print per aggirare i bachi di htmldoc
# ldp_print pu anche creare il file ps - si veda lo script
$(PDF_FILE): $(HTM_FILE)
        ldp_print $(HTM_FILE)

$(DVI_FILE): $(TEX_FILE)
        jadetex $(TEX_FILE)
        jadetex $(TEX_FILE)
        jadetex $(TEX_FILE)

$(PS_FILE): $(DVI_FILE)
        dvips $(DVI_FILE)

#$(PS_FILE): $(SGML_FILE)
#       openjade -t sgml -V nochunks -d $(DSL_HTML) \
#       $(SGML_FILE) | htmldoc -f $(PS_FILE) -

   L'uso  analogo alla maggior parte dei progetti:

   Figura 10. Lanciare il comando make per eseguire Makefile
                -- generare html (predefinito)
                make
                -- generare solamente pdf
                make pdf
                -- generare tutti i file
                make all
                -- cancellare tutti i file generati
                make clean
                -- creare un pacchetto tgz per la distribuzione
                -- senza generare file
                make dist
                -- creare un pacchetto tgz per la distribuzione
                -- contenente tutti i file generati
                make distall

   Si notino le regole di compilazione commentate per pdf e ps, che
   forniscono una via alternativa per generare questi file.
     _________________________________________________________________

4.6. Generazione di una pagina man

Durante la sezione sull'installazione, si  installato anche il modulo perl
versione 5 SGMLS.pm. Quindi si  installato Docbook2X che fornisce i file
spec.pl per trasformare documenti DocBook <refentry> nel formato nroff
(pagine man) con sgmlspl.

Un esempio di documento Docbook <refentry>, per il comando foo,  dato di
seguito.

   Figura 11. Pagina man per il comando foo, sorgente docbook <refentry>
   (foo-ref.sgml)
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refentryinfo>
        <date>2001-01-01</date>
</refentryinfo>
<refmeta>
        <refentrytitle>
                <application>foo</application>
        </refentrytitle>
        <manvolnum>1</manvolnum>
        <refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>
<refnamediv>
        <refname>
                <application>foo</application>
        </refname>
        <refpurpose>
        Does nothing useful.
        </refpurpose>
</refnamediv>
<refsynopsisdiv>
        <refsynopsisdivinfo>
                <date>2001-01-01</date>
        </refsynopsisdivinfo>
        <cmdsynopsis>
        <command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
        </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
        <refsect1info>
                <date>2001-01-01</date>
        </refsect1info>
        <title>DESCRIPTION</title>
        <para>
        <command>foo</command> does nothing useful.
        </para>
</refsect1>
<refsect1>
        <title>OPTIONS</title>
        <variablelist>
        <varlistentry>
                <term>-f <replaceable class="parameter">bar</replaceable></term
>
                <listitem>
                        <para>
                        Takes <filename>bar</filename> as it's run
                        control file. If this were a real program,
                        there might be more to say here about what
                        bar is and how it will be used.
                        </para>
                </listitem>
        </varlistentry>
        <varlistentry>
                <term>-d<replaceable class="parameter">n</replaceable></term>
                <listitem>
                        <para>
                        Do something, where integer
                        <replaceable class="parameter">n</replaceable>
                        specifies how many times.
                        </para>
                </listitem>
        </varlistentry>
        <varlistentry>
                <term><replaceable class="parameter">file...</replaceable></ter
m>
                <listitem>
                        <para>
                        Processes the files in the order listed,
                        sending all output to stdout.
                        </para>
                </listitem>
        </varlistentry>
        </variablelist>
</refsect1>
<refsect1>
        <title>USAGE</title>
        <para>
        <command>foo</command> -f foo.conf -d2 foodata.foo
        </para>
</refsect1>
<refsect1>
        <title>CAVEATS</title>
        <para>
        Other programs named <command>foo</command> may exist and actually
        do something!
        </para>
</refsect1>
<refsect1>
        <title>BUGS</title>
        <para>
        None.  Program does nothing.
        </para>
</refsect1>
<refsect1>
        <title>AUTHOR</title>
        <para>
        <author>
                <firstname>Foo</firstname>
                <othername role="mi">E</othername>
                <surname>Bar</surname>
                <contrib>Original author</contrib>
        </author>
        </para>
</refsect1>
</refentry>

   Figura 12. Generazione di una pagina man con onsgmls, sgmlspl e
   docbook2man-spec.pl
bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
-rw-r--r--   1 reaster  users        1129 Jan  3 04:03 foo.1
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.links
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.log
-rw-r--r--   1 reaster  users          15 Jan  3 04:03 manpage.refs
bash$ groff -mandoc -Tascii foo.1

FOO(1)                                                     FOO(1)


NAME
       foo - Does nothing useful.

SYNOPSIS
       foo [ -f bar ]  [ -dn ]  [ file... ]

DESCRIPTION
       foo does nothing useful.

OPTIONS
       -f bar Takes  bar as its run control file. If this were a
              real program, there might be more to say here about
              what bar is and how it will be used.

       -dn    Do  something,  where  integer n specifies how many
              times.

       file...
              Processes the files in the  order  listed,  sending
              all output to stdout.

USAGE
       foo -f foo.conf -d2 foodata.foo

CAVEATS
       Other  programs  named foo may exist and actually do some-
       thing!

BUGS
       None. Program does nothing.

AUTHOR
       Foo E Bar (Original author)

[omissis - alcune ulteriori righe bianche che man non mostrerebbe]
foo 1.0                     2001-01-01                          1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1

   La pagina man, foo.1, viene generata come pagina della sezione 1. Il
   comando groff  stato utilizzato per dare un rapido sguardo
   all'aspetto formattato.

   Per installare questa pagina man, essa deve essere sistemata in una
   directory man/man1, con la directory man/ che  stata aggiunta alla
   variabile di ambiente $MANPATH. La collocazione convenzionale 
   /usr/local/man/man1. Le sezioni convenzionali nel sistema delle pagine
   man vanno da 1 a 9. Ognuna di esse  pensata per contenere specifiche
   categorie di documenti.

   Tabella 1. Sezioni delle pagine di manuale
   Sezione                  Scopo
    man1              Programmi utente
    man2             Chiamate di sistema
    man3      Funzioni e subroutine di libreria
    man4                 Dispositivi
    man5              Formati dei file
    man6                   Giochi
    man7                    Varie
    man8         Amministrazione di sistema
    man9   Variabili interne e funzioni del kernel

     Suggerimento: Il file sorgente per una pagina man, come
     foo-ref.sgml, pu essere trasformato in tutti gli altri formati,
     come per ogni altro file DocBook. Quindi, utilizzando gli stessi
     comandi discussi precedentemente per generare output in html e per
     la stampa, una pagina man pu essere trasformata in html e rtf,
     tex, pdf, dvi e ps. Questo pu consentire di risparmiare molto
     lavoro di conversione!

   Buon divertimento!
     _________________________________________________________________

A. Note Legali

A.1. Copyright e Licenze

     Copyright (c) 2001, 2002 Robert B. Easter

     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 included in
     the section entitled "GNU Free Documentation License".

     (NdT di seguito  riportata la traduzione del paragrafo precedente,
     con l'avvertenza che ha valore legale solo il testo originale in
     inglese)

     Copyright (c) 2001, 2002 Robert B. Easter

      concesso il permesso di copiare, distribuire e/o modificare
     questo documento nei termini della licenza GNU sulla libera
     documentazione, Versione 1.1 o qualunque versione successiva
     pubblicata dalla Free Software Foundation; senza le clausole sulle
     Sezioni immodificabili, sulla Prima di copertina e sull'Ultima di
     copertina. Una copia della licenza  inclusa nella sezione "GNU
     Free Documentation License".
     _________________________________________________________________

A.2. Liberatoria

No liability for the contents of this document can be accepted. Use the
concepts, examples and other content at your own risk.

All copyrights are held by their respective owners, unless specifically
noted otherwise. Use of a term in this document should not be regarded as
affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

(NdT di seguito  riportata la traduzione dei paragrafi precedenti, con
l'avvertenza che ha valore legale solo il testo originale in inglese)

Nessuna responsabilit  assunta per il contenuto di questo documento. Chi
utilizza i concetti, gli esempi ed altri contenuti lo fa a proprio rischio.

Tutti i copyright sono dei rispettivi proprietari, a meno che non sia
specificatamente detto altrimenti. L'uso di un termine in questo documento
non deve essere interpretato come volont di modificare la validit di un
qualunque marchio depositato o di servizio.

L'aver nominato particolari prodotti o marchi non deve essere visto come un
sostegno agli stessi.
     _________________________________________________________________

B. GNU Free Documentation License

(NdT traduzione della presente licenza pu essere trovata sul sito
http://it.tldp.org/gpl.it.txt con l'avvertenza che ha valore legale solo il
testo originale in inglese)

Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place,
     Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy
     and distribute verbatim copies of this license document, but
     changing it is not allowed.
     _________________________________________________________________

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written
document "free" in the sense of freedom: to assure everyone the effective
freedom to copy and redistribute it, with or without modifying it, either
commercially or noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not being
considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of
the document must themselves be free in the same sense. It complements the
GNU General Public License, which is a copyleft license designed for free
software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free program
should come with manuals providing the same freedoms that the software does.
But this License is not limited to software manuals; it can be used for any
textual work, regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works whose purpose
is instruction or reference.
     _________________________________________________________________

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice
placed by the copyright holder saying it can be distributed under the terms
of this License. The "Document", below, refers to any such manual or work.
Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document
or a portion of it, either copied verbatim, or with modifications and/or
translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the
Document that deals exclusively with the relationship of the publishers or
authors of the Document to the Document's overall subject (or to related
matters) and contains nothing that could fall directly within that overall
subject. (For example, if the Document is in part a textbook of mathematics,
a Secondary Section may not explain any mathematics.) The relationship could
be a matter of historical connection with the subject or with related
matters, or of legal, commercial, philosophical, ethical or political
position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are
designated, as being those of Invariant Sections, in the notice that says
that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as
Front-Cover Texts or Back-Cover Texts, in the notice that says that the
Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or for
automatic translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format whose markup
has been designed to thwart or discourage subsequent modification by readers
is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII
without markup, Texinfo input format, LaTeX input format, SGML or XML using
a publicly available DTD, and standard-conforming simple HTML designed for
human modification. Opaque formats include PostScript, PDF, proprietary
formats that can be read and edited only by proprietary word processors,
SGML or XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML produced by some word processors
for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such
following pages as are needed to hold, legibly, the material this License
requires to appear in the title page. For works in formats which do not have
any title page as such, "Title Page" means the text near the most prominent
appearance of the work's title, preceding the beginning of the body of the
text.
     _________________________________________________________________

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially
or noncommercially, provided that this License, the copyright notices, and
the license notice saying this License applies to the Document are
reproduced in all copies, and that you add no other conditions whatsoever to
those of this License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or distribute.
However, you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.

You may also lend copies, under the same conditions stated above, and you
may publicly display copies.
     _________________________________________________________________

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and
the Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover Texts:
Front-Cover Texts on the front cover, and Back-Cover Texts on the back
cover. Both covers must also clearly and legibly identify you as the
publisher of these copies. The front cover must present the full title with
all words of the title equally prominent and visible. You may add other
material on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly,
you should put the first ones listed (as many as fit reasonably) on the
actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more
than 100, you must either include a machine-readable Transparent copy along
with each Opaque copy, or state in or with each Opaque copy a
publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the general
network-using public has access to download anonymously at no charge using
public-standard network protocols. If you use the latter option, you must
take reasonably prudent steps, when you begin distribution of Opaque copies
in quantity, to ensure that this Transparent copy will remain thus
accessible at the stated location until at least one year after the last
time you distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give them
a chance to provide you with an updated version of the Document.
     _________________________________________________________________

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the
conditions of sections 2 and 3 above, provided that you release the Modified
Version under precisely this License, with the Modified Version filling the
role of the Document, thus licensing distribution and modification of the
Modified Version to whoever possesses a copy of it. In addition, you must do
these things in the Modified Version:

    A. Use in the Title Page (and on the covers, if any) a title distinct
       from that of the Document, and from those of previous versions
       (which should, if there were any, be listed in the History section
       of the Document). You may use the same title as a previous version
       if the original publisher of that version gives permission.
    B. List on the Title Page, as authors, one or more persons or
       entities responsible for authorship of the modifications in the
       Modified Version, together with at least five of the principal
       authors of the Document (all of its principal authors, if it has
       less than five).
    C. State on the Title page the name of the publisher of the Modified
       Version, as the publisher.
    D. Preserve all the copyright notices of the Document.
    E. Add an appropriate copyright notice for your modifications
       adjacent to the other copyright notices.
    F. Include, immediately after the copyright notices, a license notice
       giving the public permission to use the Modified Version under the
       terms of this License, in the form shown in the Addendum below.
    G. Preserve in that license notice the full lists of Invariant
       Sections and required Cover Texts given in the Document's license
       notice.
    H. Include an unaltered copy of this License.
    I. Preserve the section entitled "History", and its title, and add to
       it an item stating at least the title, year, new authors, and
       publisher of the Modified Version as given on the Title Page. If
       there is no section entitled "History" in the Document, create one
       stating the title, year, authors, and publisher of the Document as
       given on its Title Page, then add an item describing the Modified
       Version as stated in the previous sentence.
    J. Preserve the network location, if any, given in the Document for
       public access to a Transparent copy of the Document, and likewise
       the network locations given in the Document for previous versions
       it was based on. These may be placed in the "History" section. You
       may omit a network location for a work that was published at least
       four years before the Document itself, or if the original
       publisher of the version it refers to gives permission.
    K. In any section entitled "Acknowledgements" or "Dedications",
       preserve the section's title, and preserve in the section all the
       substance and tone of each of the contributor acknowledgements
       and/or dedications given therein.
    L. Preserve all the Invariant Sections of the Document, unaltered in
       their text and in their titles. Section numbers or the equivalent
       are not considered part of the section titles.
    M. Delete any section entitled "Endorsements". Such a section may not
       be included in the Modified Version.
    N. Do not retitle any existing section as "Endorsements" or to
       conflict in title with any Invariant Section.

   If the Modified Version includes new front-matter sections or
   appendices that qualify as Secondary Sections and contain no material
   copied from the Document, you may at your option designate some or all
   of these sections as invariant. To do this, add their titles to the
   list of Invariant Sections in the Modified Version's license notice.
   These titles must be distinct from any other section titles.

   You may add a section entitled "Endorsements", provided it contains
   nothing but endorsements of your Modified Version by various
   parties--for example, statements of peer review or that the text has
   been approved by an organization as the authoritative definition of a
   standard.

   You may add a passage of up to five words as a Front-Cover Text, and a
   passage of up to 25 words as a Back-Cover Text, to the end of the list
   of Cover Texts in the Modified Version. Only one passage of
   Front-Cover Text and one of Back-Cover Text may be added by (or
   through arrangements made by) any one entity. If the Document already
   includes a cover text for the same cover, previously added by you or
   by arrangement made by the same entity you are acting on behalf of,
   you may not add another; but you may replace the old one, on explicit
   permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License
   give permission to use their names for publicity for or to assert or
   imply endorsement of any Modified Version.
     _________________________________________________________________

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified versions,
provided that you include in the combination all of the Invariant Sections
of all of the original documents, unmodified, and list them all as Invariant
Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple
identical Invariant Sections may be replaced with a single copy. If there
are multiple Invariant Sections with the same name but different contents,
make the title of each such section unique by adding at the end of it, in
parentheses, the name of the original author or publisher of that section if
known, or else a unique number. Make the same adjustment to the section
titles in the list of Invariant Sections in the license notice of the
combined work.

In the combination, you must combine any sections entitled "History" in the
various original documents, forming one section entitled "History"; likewise
combine any sections entitled "Acknowledgements", and any sections entitled
"Dedications". You must delete all sections entitled "Endorsements."
     _________________________________________________________________

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in the
collection, provided that you follow the rules of this License for verbatim
copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it
individually under this License, provided you insert a copy of this License
into the extracted document, and follow this License in all other respects
regarding verbatim copying of that document.
     _________________________________________________________________

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and
independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version of the
Document, provided no compilation copyright is claimed for the compilation.
Such a compilation is called an "aggregate", and this License does not apply
to the other self-contained works thus compiled with the Document, on
account of their being thus compiled, if they are not themselves derivative
works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of
the Document, then if the Document is less than one quarter of the entire
aggregate, the Document's Cover Texts may be placed on covers that surround
only the Document within the aggregate. Otherwise they must appear on covers
around the whole aggregate.
     _________________________________________________________________

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute
translations of the Document under the terms of section 4. Replacing
Invariant Sections with translations requires special permission from their
copyright holders, but you may include translations of some or all Invariant
Sections in addition to the original versions of these Invariant Sections.
You may include a translation of this License provided that you also include
the original English version of this License. In case of a disagreement
between the translation and the original English version of this License,
the original English version will prevail.
     _________________________________________________________________

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as
expressly provided for under this License. Any other attempt to copy,
modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However, parties who
have received copies, or rights, from you under this License will not have
their licenses terminated so long as such parties remain in full compliance.
     _________________________________________________________________

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU
Free Documentation License from time to time. Such new versions will be
similar in spirit to the present version, but may differ in detail to
address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the
Document specifies that a particular numbered version of this License "or
any later version" applies to it, you have the option of following the terms
and conditions either of that specified version or of any later version that
has been published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may choose
any version ever published (not as a draft) by the Free Software Foundation.
     _________________________________________________________________

How to use this License for your documents

To use this License in a document you have written, include a copy of the
License in the document and put the following copyright and license notices
just after the title page:

     Copyright (c) YEAR YOUR NAME. 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 the Invariant
     Sections being LIST THEIR TITLES, with the Front-Cover Texts being
     LIST, and with the Back-Cover Texts being LIST. A copy of the
     license is included in the section entitled "GNU Free Documentation
     License".

   If you have no Invariant Sections, write "with no Invariant Sections"
   instead of saying which ones are invariant. If you have no Front-Cover
   Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts
   being LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
   recommend releasing these examples in parallel under your choice of
   free software license, such as the GNU General Public License, to
   permit their use in free software.
