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.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.3. Le DTD DocBook per SGML

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