DocBook Install mini-HOWTO Robert Easter B
reaster@reaster.com
v1.8 2002-02-04 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. Introduzione 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. 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. 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. Scaricare i pacchetti In questa sezione, verranno individuati e scaricati i programmi da Internet. 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/ 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 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 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 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. 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. 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/ Installazione dei pacchetti 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. Installazione di OpenJade 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 cancellati. 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. 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 Next Solution Co., Ltd. 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: 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# 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. Le DTD DocBook per SGML 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/. 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 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. 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ù. htmldoc 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. 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. 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. 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. DocBook2X e SGMLS.pm (sgmlspl) 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. 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. $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/sgmltools.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. Usare DocBook Una volta che tutto è installato, è tempo di verificare quanto fatto e vedere come usare openjade e gli altri strumenti.
File di esempio DocBook SGML - <filename>test.sgml</filename> <!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/ Generazione di HTML <filename>docbook.dsl</filename>
Generazione di HTML utilizzando <filename>docbook.dsl</filename> 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. <filename>ldp.dsl</filename>
Generazione di HTML utilizzando <filename>ldp.dsl</filename> 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. 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.sgml bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml 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 Generazione di dvi e ps
Esecuzione di <command>jadetex</command> 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ù.
Esecuzione di <command>dvips</command> per generare un file <productname>PostScript</productname> (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$
Esecuzione di <command>htmldoc</command> per generare un file <productname>PostScript</productname> (<filename>ps</filename>). 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-htmldoc.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. Generazione di pdf
Esecuzione di <command>pdfjadetex</command> per generare un file Portable Document Format (<filename>pdf</filename>). 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.
Esecuzione di <command>htmldoc</command> per generare un file Portable Document Format (<filename>pdf</filename>). 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. Utilizzare <command>make</command> Ripetere i comandi per generare i file in uscita può essere noioso. Il comando make funziona perfettamente per automatizzare il procedimento.
File: <filename>Makefile</filename> - generazione automatica di documenti. # Generazione di versioni per la visualizzazione e la stampa da file sorgente SGML 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:
Lanciare il comando <command>make</command> per eseguire <filename>Makefile</filename> -- 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. Generazione di una pagina <command>man</command> 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.
Pagina <command>man</command> per il comando <command>foo</command>, sorgente docbook <sgmltag class="StartTag">refentry</sgmltag> (<filename>foo-ref.sgml</filename>) <!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></term> <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>
Generazione di una pagina <command>man</command> con <command>onsgmls</command>, <command>sgmlspl</command> e <filename>docbook2man-spec.pl</filename> 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. 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
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! Note Legali 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".
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. 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.
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. 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. 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. 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. 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: 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. 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). State on the Title page the name of the publisher of the Modified Version, as the publisher. Preserve all the copyright notices of the Document. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. 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. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. 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. 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. 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. 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. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. 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. 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." 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. 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. 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. 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. 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.