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 cancellati. make clean |
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 |
% 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 |
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 |
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 |
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 |
# 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. |
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 |
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:
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.
 | 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 |
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
|
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 |
patch docbook2man-spec.pl docbook2man-spec.pl.patch |
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/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 ########################################################################################## |
L'installazione è completata! Nella prossima sezione si verificherà l'installazione e si convertiranno alcuni file DocBook.