Contrariamente a quello che si potrebbe pensare leggendone il titolo, questo capitolo descrive l'installazione e la configurazione degli strumenti necessari per produrre una versione formattata della presente Guida a NetBSD. Anche se SGML/DocBooks e i DSSSL non vengono qui descritti, alla fine del capitolo sono presenti alcuni link a materiale informativo essenziale per chi vuole saperne di più.
L'ambiente SGML/DocBook può essere installato utilizzando il "meta-pacchetto" netbsd-docs; questo è il metodo più semplice ed è quello che consiglio di usare. Questo capitolo, invece, descrive l'installazione e la configurazione dei componenti necessari uno a uno, al fine di eseminarli più in dettaglio e, eventualmente, di verificarne la corretta installazione.
Nota: È possibile che il "meta-pacchetto" netbsd-docs installi qualche pacchetto in più rispetto a quelli qui descritti. Si tratta di pacchetti utili ma non strettamente necessari ai fini della produzione della guida.
I pacchetti necessari per la guida verranno installati usando package precompilati anche se, se si preferisce, è possibile compilarli partendo dai sorgenti. Per ulteriori dettagli si veda Capitolo 8.
Nota: i numeri di versione dei pacchetti installati sono naturalmente soggetti a cambimento, con l'uscita di nuove versioni.
SGML (Standard Generalized Markup Language) è un linguaggio utilizzato per definire la struttura di altri linguaggi basati su "markup". Ciò significa che con SGML si può definire la grammatica dei linguaggi di markup. HTML, per esempio, può essere definito usando SGML. I programmatori possono pensare a SGML come all'equivalente della BNF (Backus-Naur Form) per i linguaggi di programmazione: una notazione per definire grammatiche.
DocBook è uno schema di markup definito usando SGML; DocBook specifica quali tag possono essere utilizzati in un documento e in che modo possono essere combinati tra loro. I programmatori possono pensare a DocBook come a un linguaggio di programmazione, con le sue parole chiave valide e le sue regole. Per esempio, per DocBook i tag
<para> ... </para>
definiscono l'inizio e la fine di un paragrafo. Inoltre DocBook specifica che il tag <para> può trovarsi all'interno di una sezione <sect1> ma che il tag <sect1> non può trovarsi all'interno di un <para>.
Alla luce di quanto appena detto, si può capire che i documenti prodotti con questi strumenti sono documenti DocBook, e non SGML; da questo punto di vista, DocBook è la controparte di HTML (benché i tag siano più numerosi e i concetti alla base dei due linguaggi diversi).
La specifica DocBook (cioè la lista dei tag validi e le regole per combinarli) viene chiamata DTD (Document Type Definition.)
Un DTD definisce quello che è l'aspetto di un documento sorgente valido ma non dà alcuna indicazione sul formato del documento finale generato a partire dai sorgenti. A titolo di esempio, il tag <title> marca l'inizio di un titolo ma non specifica che aspetto avrà il titolo nel documento finale (dimensione e corpo dei caratteri, allineamento, spaziatura, ecc.) Per arrivare alla "presentazione" del documento è necessario un ulteriore passo, effettuato utilizzando il programma Jade, che applica al documento sorgente le trasformazioni DSSSL. DSSSL (Document Style Semantics and Specification Language) è il formato utilizzato per definire gli stylesheets (fogli di stile) necessari per convertire il documento DocBook in altri formati.
La "vita" di un documento DocBook è pertanto la seguente:
scrittura del documento sorgente
il DTD di DocBook viene utilizzato da nsgmls per "validare" il documento
Jade applica i fogli di stile DSSSL al documento sorgente e genera un nuovo documento.
Non è ancora possibile stampare il documento generato, perché contiene le direttive di formattazione indicate sui fogli di stile (si può trattare di un documento HTML, RTF, TeX, ecc.)
un programma di formattazione (un browser per HTML, un word processor per RTF, TeX, ...) crea la versione finale, visualizzabile o stampabile, del documento
In definitiva, ciò che serve per iniziare a lavorare è:
un DTD per DocBook
i fogli di stile DSSSL usati da Jade, per generare HTML/RTF, ecc.
il programma Jade e il parser nsgmls
Jade è un parser SGML/XML che implementa il meccanismo dei DSSSL. Il pacchetto Jade include anche il parser nsgmls, che valida i documenti.
Nota: OpenJade è un'evoluzione di Jade che, al momento, non si compila sotto NetBSD (ma che non è necessaria per la guida).
Per installare il package precompilato di Jade:
# pkg_add jade-1.2.1.tgz
Al termine dell'installazione, la documentazione di Jade si trova in /usr/pkg/share/doc/jade/index.htm. La directory principale dell'installazione è /usr/pkg/share/sgml/jade/: è qui che si trova il file catalog di Jade.
Dopo aver installato Jade si può procedere all'installazione del DocBook DTD.
Questo pacchetto richiede l'installazione delle "entity" per il set di caratteri ISO 8879:1986. Aggiungiamo quindi il relativo package:
# pkg_add iso8879-1986.tgz
Le entity vengono installate nella directory /usr/pkg/share/sgml/iso8879/ e il relativo catalogo è /usr/pkg/share/sgml/iso8879/catalog.
Finalmente si può installare il DTD.
# pkg_add docbook-4.1.tgz
A dispetto del nome questo package installa varie versioni di DTD (2.4.1, 3.0, 3.1, 4.0, 4.1). Ciò consente di elaborare documenti che usano differenti versioni di DocBook.
Nota: la guida di NetBSD al momento usa la versione 4.1 del DTD di DocBook e, pertanto, le altre versioni non sono strettamente necessarie. Tuttavia, in considerazione del fatto che ogni DTD occupa meno di 250 KB può convenire mantenerle sul disco fisso poiché consentono di elaborare altri documenti.
La radice dell'installazione del sistema è /usr/pkg/share/sgml/docbook/4.1/. Ogni versione del DTD si trova in una directory separata e possiede un proprio file catalogo. Per esempio: /usr/pkg/share/sgml/docbook/4.1/catalog.
L'ultimo passo consiste nell'installazione dei fogli di stile DSSSL.
# pkg_add dsssl-docbook-modular-1.57.tgz
Anche i fogli di stile installano un proprio catalogo, che si trova in /usr/pkg/share/sgml/docbook/dsssl/modular/catalog. Inoltre sono corredati da una dettagliata documentazione: /usr/pkg/share/sgml/docbook/dsssl/modular/doc/index.html.
Adesso che è stato installato tutto il necessario, si può incominciare a utilizzare gli strumenti per produrre la versione HTML della guida (per esempio la versione italiana).
Con un cd ci si porta nella directory radice della guida e si dà il comando:
$ cd it
$ make netbsd.html
Un lungo elenco di errori scorrerà sullo schermo; ciò è dovuto al fatto che il parser SGML nsgmls non riesce a trovare i file catalog. Pertanto occorre dare i seguenti comandi (che conviene inserire nel proprio ~/.profile):
SGML_ROOT=/usr/pkg/share/sgml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/3.0/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/3.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.0/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/dsssl/modular/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES Nota: modificare opportunamente i comandi se si usa la shell C o una shell derivata da questa.
Ora che la variabile d'ambiente SGML_CATALOG_FILES è attiva, si può ritentare il comando precedente:
$ make netbsd.html nsgmls -sv netbsd.sgml nsgmls:I: SP version "1.3.3" jade -d ../dsl/myhtml.dsl -t sgml -o netbsd.html netbsd.sgml
Questa volta l'operazione va a buon fine e viene generata la versione HTML della guida. La creazione del formato RTF non presenta maggiori difficoltà:
$ make netbsd.rtf nsgmls -sv netbsd.sgml nsgmls:I: SP version "1.3.3" jade -d ../dsl/myrtf.dsl -t rtf -o netbsd.rtf netbsd.sgml
Con il setup appena descritto si possono generare solo i formati HTML e RTF: per creare i formati PS e PDF occorre installare e configurare TeX e Jadetex (un formato per TeX).
Nelle mie installazioni generalmente creo un file di catalogo master, che contiene i riferimenti a tutti gli altri. Per utilizzare questo metodo, si può creare il file /usr/pkg/share/sgml/catalog con il seguente contenuto:
CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog" CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog" CATALOG "/usr/pkg/share/sgml/docbook/4.0/catalog" CATALOG "/usr/pkg/share/sgml/docbook/4.1/catalog" CATALOG "/usr/pkg/share/sgml/docbook/dsssl/modular/catalog" CATALOG "/usr/pkg/share/sgml/iso8879/catalog" CATALOG "/usr/pkg/share/sgml/jade/catalog"
Fatto ciò, le inizializzazioni nel ~/.profile si possono semplificare così:
SGML_CATALOG_FILES=/usr/pkg/share/sgml/catalog export SGML_CATALOG_FILES
Per creare la versione Postscript della guida sono necessarie alcune operazioni preliminari:
installazione di TeX
abilitazione della silabazione italiana di TeX
creazione del formato hugelatex richiesto da jadetex
installazione di jadetex
Le sezioni seguenti descrivono in dettaglio i punti precedenti.
L'installazione di TeX è resa semplice, come di consueto, dal sistema dei package. Utilizzando i pacchetti precompilati è sufficiente dare i seguenti comandi (i numeri di versione dei pacchetti potrebbero essere differenti):
# pkg_add teTeX-share-1.0.2.tgz
# pkg_add teTeX-bin-1.0.7nb1.tgz
La guida a NetBSD è correntemente disponibile in quattro diverse lingue: francese, inglese, italiano e portoghese. Al termine dell'installazione di TeX, la sillabazione per le lingue italiana portoghese non è abilitata; per attivarla sono necessarie alcune semplici operazioni:
Editare /usr/pkg/share/texmf/tex/generic/config/language.dat rimuovento il carattere di commento (%) all'inizio della riga relativa alle lingue italiana e portoghese. Cioè:
%italian ithyph.tex %portuges pt8hyph.tex
diventa
italian ithyph.tex portuges pt8hyph.tex
Nota: quando saranno disponibili ulteriori traduzioni della guida, sarà probabilmente necessario attivare la sillabazione anche per le nuove lingue.
Ora bisogna ricreare i formati latex e pdflatex:
# cd /usr/pkg/share/texmf/web2c
# fmtutil --byfmt latex
# fmtutil --byfmt pdflatex
A scopo di verifica si può controllare, per esempio, il file latex.log: dovrebbe contenere (tra le altre informazioni) una riga di questo tipo:
Babel <v3.6Z> and hyphenation patterns for american, french, german, ngerman, italian, nohyphenation, loaded.
Nota: vi sono vari modi di eseguire queste operazioni, a seconda del proprio livello di conoscenza di TeX (il mio è piuttosto basso). Per esempio, è possibile usare il programma interattivo texconfig, oppure ricreare i formati usando direttamente tex (fmtutil, infatti, è semplicemente uno script che richiama tex).
Se conoscete un metodo migliore per effettuare le operazioni descritte un questo capitolo, vi prego di segnalarmelo.
Per poter utilizzare jadetex è necessario creare il formato hugelatex, che altro non è se non un formato latex con aumentati limiti di capacità per riuscire a gestire i grossi file creati da jadetex. Prima di effettuare le modifiche conviene fare una copia di backup del file /usr/pkg/share/texmf/web2c/texmf.cnf. Poi aggiungere alla fine del file le seguenti righe (le definizioni per jadetex e pdfjadetex serviranno in seguito ma tanto vale aggiungerle già adesso):
% hugelatex settings main_memory.hugelatex = 1100000 param_size.hugelatex = 1500 stack_size.hugelatex = 1500 hash_extra.hugelatex = 15000 string_vacancies.hugelatex = 45000 pool_free.hugelatex = 47500 nest_size.hugelatex = 500 save_size.hugelatex 5000 pool_size.hugelatex = 500000 max_strings.hugelatex 55000 font_mem_size.hugelatex = 400000 % jadetex & pdfjadetex main_memory.jadetex = 1500000 param_size.jadetex = 1500 stack_size.jadetex = 1500 hash_extra.jadetex = 15000 string_vacancies.jadetex = 45000 pool_free.jadetex = 47500 nest_size.jadetex = 500 save_size.jadetex 5000 pool_size.jadetex = 500000 max_strings.jadetex 55000 main_memory.pdfjadetex = 2500000 param_size.pdfjadetex = 1500 stack_size.pdfjadetex = 1500 hash_extra.pdfjadetex = 50000 string_vacancies.pdfjadetex = 45000 pool_free.pdfjadetex = 47500 nest_size.pdfjadetex = 500 save_size.pdfjadetex 5000 pool_size.pdfjadetex = 500000 max_strings.pdfjadetex 55000
Aggiungere le righe seguenti, che descrivono il formato hugelatex, al file fmtutil.cnf (nella directory /usr/pkg/share/texmf/web2c)
# hugelatex format created for jadetex hugelatex tex language.dat latex.ini
salvare il file e lanciare il comando
fmtutil --byfmt hugelatex.
Il formato hugelatex è ora pronto per l'uso.
Nota: come già segnalato, con TeX vi sono più modi di raggiungere lo stesso risultato (in questo caso la creazione del formato hugelatex).
La guida all'installazione di jadetex riporta le seguenti istruzioni:
# cp -R /usr/pkg/share/texmf/tex/latex/config /tmp # cd /tmp/config # tex -ini -progname=hugelatex latex.ini # mv latex.fmt hugelatex.fmt # mv hugelatex.fmt /usr/pkg/share/texmf/web2c # ln -s /usr/pkg/bin/tex /usr/pkg/bin/hugelatex
Nota: la versione più recente di Jadetex può essere scaricata da http://sourceforge.net/projects/jadetex/
Scaricare il package Jadetex (la versione corrente è jadetex-3.12.zip), scompattarlo e poi dare i seguenti comandi:
# cd jadetex
# make install
# mktexlsr
# cd /usr/pkg/bin
# ln -s tex jadetex
L'installazione copia i file di formato di jadetex e pdfjadetex (nonché alcuni file di supporto) nell'albero delle directory di TeX.
La distribuzione di Jadetex contiene anche due pagine di manuale che non vengono installate in automatico. Se lo si desidera è sufficiente copiarle a mano nella directory opportuna. Per esempio:
# cp jadetex.1 pdfjadetex.1 /usr/local/man/man1
Ora tutto è pronto per creare la versione Postscript della guida a NetBSD (e naturalmente di qualunque altro documento). Per esempio, portarsi nella directory base della guida e dare i seguenti comandi:
$ cd it
# make netbsd.ps
Una semplice e ben scritta introduzione a SGML/DocBook, nonché una descrizione degli strumenti necessari si trova in SGML comme format de fichier universel.
The official DocBook home page è la fonte ufficiale di informazioni su DocBook. Trs le altre informazioni si pò consultare in linea o scaricare il libro DocBook: The Definitive Guide di Norman Walsh and Leonard Muellner, una guida fondamentale per chi vuole approfondire l'argomento.
Per informazioni sulle DSSSL conviene incominciare da nwalsh.com.
I sorgenti di Jade/OpenJade e la relativa documentazione si può trovare sulla OpenJade Home Page.
A chi desidera produrre documenti in formato Postscript o PDF a partire dai sorgenti DocBook conviene dare un'occhiata alla home page di JadeTex.
La home page of Markus Hoenicka spiega tutto ciò che è necessario sapere per lavorare con SGML/DocBook su Windows NT.