<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<article lang="it">

<articleinfo>
	<title>DocBook Install mini-HOWTO</title>

	<author>
		<firstname>Robert</firstname>
		<surname>Easter</surname>
		<othername role="mi">B</othername>
		<affiliation>
			<address>
			<email>reaster@reaster.com</email>
			</address>
		</affiliation>
	</author>

	<revhistory>
		<revision>
		<revnumber>v1.8</revnumber>
		<date>2002-02-04</date>
		<authorinitials>rbe</authorinitials>
		</revision>
	</revhistory>

	<abstract>
	<para>
	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
	<ulink url="http://www.gnu.org/gnu/linux-and-gnu.html">GNU</ulink>/<ulink url="http://www.linux.org">Linux</ulink>;
	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.
	</para>
	<para>
	Traduzione a cura di Giuseppe Briotti <email>g.briotti (at) mclink.it</email> e revisione a cura di Beatrice Torracca <email>beatricet (at) libero.it</email>.
	</para>
	</abstract>

</articleinfo>


<sect1 id="intro">
<title>Introduzione</title>

<sect2 id="versions">
	<title>Informazioni su questo documento</title>

	<para>
	L'ultima versione in inglese di questo mini-HOWTO può essere trovata all'indirizzo:
	</para>

	<para>
	<ulink url="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/</ulink>
	</para>

    <para>
    Si legga la sezione "Note Legali" in appendice per le informazioni sul copyright, le licenze e la liberatoria riguardanti questo documento.
    </para>
</sect2>


	<sect2>
	<title>Cosa è DocBook</title>

	<para>
	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.
	</para>
	<para>
	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 <sgmltag class="StartTag">book</sgmltag>
	e <sgmltag class="StartTag">article</sgmltag>
	sono usati per creare libri ed articoli. All'interno di questi
	documenti, vengono utilizzati i marcatori <sgmltag class="StartTag">chapter</sgmltag>,
	<sgmltag class="StartTag">sect1</sgmltag> e <sgmltag class="StartTag">para</sgmltag>.
	I file DocBook SGML sono archiviati in file di testo con l'estensione <filename>sgml</filename>
	o <filename>gml</filename>.
	</para>
	<para>
	Quando trattato, un singolo file DocBook SGML può produrre
	in uscita file nei formati <filename>html</filename>, <filename>pdf</filename>, <filename>ps</filename>,
	<filename>txt</filename> 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.
	</para>
	<para>
	DocBook è anche progettato per realizzare le pagine <command>man</command> di unix, consentendo
	di creare documenti <sgmltag class="StartTag">refentry</sgmltag>. Se non si conosce cosa sia una
	pagina <command>man</command>, si provi a digitare il comando <command>man man</command> su un terminale.
	</para>
	</sect2>

	<sect2>
	<title>Breve panoramica</title>
	<para>
	Di seguito una breve descrizione dei pacchetti su cui lavoreremo nelle prossime sezioni:
	</para>

			<formalpara>
			<title>OpenJade</title>
			<para>
			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 <filename>html</filename>, <filename>tex</filename>,
			<filename>rtf</filename>, <filename>txt</filename> 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 <filename>dvi</filename>, <filename>pdf</filename>,
			e <filename>ps</filename> attraverso le macro di TeX ed i convertitori dvi.
			</para>
			</formalpara>

			<formalpara>
			<title>DocBook SGML DTD</title>
			<para>
			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.
			</para>
			</formalpara>

			<formalpara>
			<title>Entità ISO8879 per SGML</title>
			<para>
			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;amp;"='&amp;', "&amp;gt;"='&gt;' e "&amp;lt;"='&lt;'.
			</para>
			</formalpara>

			<formalpara>
			<title>DocBook DSSSL (Modular DocBook Stylesheets)</title>
			<para>
			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'<command>openjade</command>, insieme al file DocBook
			sgml da trattare, e dice ad <command>openjade</command>
			come trasformare e rappresentare il documento in un file di altro formato.
			Il file dsl per formati in linea (<filename>html</filename>) è spesso differente
			da quello per la stampa (<filename>dvi</filename>, <filename>pdf</filename>,
			<filename>ps</filename>).
			</para>
			</formalpara>

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

			<formalpara>
			<title>HTMLdoc</title>
			<para>
			HTMLdoc è un programma libero che consente di convertire file html in file
			<filename>pdf</filename> o <filename>ps</filename>.
			</para>
			</formalpara>

			<formalpara>
			<title>SGMLSpm e docbook2X</title>
			<para>
			Insieme, questi due programmi sono utilizzati per generare pagine <command>man</command>.
			SGMLSpm è una libreria di moduli perl5 per convertire l'output analizzato
			da <filename>onsgmls</filename>, un programma incluso nel pacchetto OpenJade.
			SGMLSpm include una applicazione chiamata <filename>sgmlspl</filename>, per usare
			la libreria SGMLSpm. <filename>Sgmlspl</filename> 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 <command>man</command>.
			</para>
			</formalpara>

	</sect2>
</sect1>

<sect1 id="download">
<title>Scaricare i pacchetti</title>
<para>
In questa sezione, verranno individuati e scaricati i programmi da Internet.
</para>
	<sect2>
	<title>OpenJade</title>
	<para>
	OpenJade è un progetto software open-source attivamente mantenuto e basato sul pacchetto
	Jade di <ulink url="http://www.jclark.com/">James Clark</ulink>.
	Scaricare l'ultimo rilascio stabile dall'indirizzo:
	</para>
	<para>
	<ulink url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink>
	</para>
	<para>
	OpenJade include inoltre il pacchetto OpenSP e le macro TeX, <command>jadetex</command>
	e <command>pdfjadetex</command>, per convertire file nei formati <filename>dvi</filename> e
	<filename>pdf</filename>. Con questo pacchetto sono forniti i seguenti programmi:
	</para>
	<itemizedlist>
		<listitem><para>openjade</para></listitem>
		<listitem><para>onsgmls</para></listitem>
		<listitem><para>osgmlnorm</para></listitem>
		<listitem><para>ospam</para></listitem>
		<listitem><para>ospent</para></listitem>
		<listitem><para>osx</para></listitem>
  	</itemizedlist>

	<para>
	Per usare <command>jadetex</command> e <command>pdfjadetex</command> per creare file
	<filename>dvi</filename>, <filename>ps</filename> e <filename>pdf</filename>, è necessario avere
	una installazione funzionante di TeX (<command>tex</command>). 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 <productname>teTeX</productname> del
	TeX dal sito:
	</para>
	<para>
	<ulink url="http://www.tug.org/tetex/">http://www.tug.org/tetex/</ulink>
	</para>
	</sect2>

	<sect2>
	<title>DTD DocBook per SGML</title>

	<para>Le DTD DocBook per SGML e XML sono mantenute da un comitato tecnico al sito
	<ulink url="http://www.oasis-open.org/">Oasis-Open.ORG</ulink>. Scaricare l'ultima versione
	(ed ogni altra versione più vecchia di cui si possa aver bisogno) dell'SGML DocBook dal sito:
	</para>

	<para>
	<ulink url="http://www.oasis-open.org/docbook/sgml/index.shtml">http://www.oasis-open.org/docbook/sgml/index.shtml</ulink>
	</para>
	</sect2>

	<sect2>
	<title>Entità ISO8879 per SGML</title>
	<para>
	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.
	</para>

	<itemizedlist>
	<listitem>
	<para>Risorse disponibili sul sito <ulink url="http://www.oasis-open.org/">OASIS</ulink>:
		<itemizedlist>
		<listitem><para><ulink url="http://www.oasis-open.org/cover/topics.html#entities">http://www.oasis-open.org/cover/topics.html#entities</ulink></para></listitem>
		<listitem><para><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">http://www.oasis-open.org/cover/ISOEnts.zip</ulink></para></listitem>
		<listitem><para><ulink url="http://www.oasis-open.org/cover/isoENT-tar.gz">http://www.oasis-open.org/cover/isoENT-tar.gz</ulink></para></listitem>
		</itemizedlist>
	</para>
	</listitem>
  	</itemizedlist>

	<para>
	Il file <filename>ISOEnts.zip</filename> può essere semplicemente decompresso con <command>unzip</command>
	nella directory dove sono state decompresse le DTD DocBook (sempre con <command>unzip</command>) senza
	richiedere niente altro che i file contenuti in <filename>isoENT-tar.gz</filename>. Ancora una volta,
	i file in <filename>isoENT-tar.gz</filename> 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 "<filename>.ent</filename>". Occorre modificare l'estensione di questi file in
	"<filename>.gml</filename>". Ciò si può fare manualmente o è possibile scaricare ed utilizzare il file
	seguente, realizzato dall'autore, che contiene tutti i file di <filename>ISOEnts.zip</filename> e di
	<filename>isoENT-tar.gz</filename>:
	</para>
	<para>
	<ulink url="http://reaster.com/iso8879-entities.tar.gz">http://reaster.com/iso8879-entities.tar.gz</ulink>
	</para>

	</sect2>

	<sect2>
	<title>DSSSL DocBook </title>
	<para>
	I file del Document Style Semantics and Specification Language (DSSSL) per DTD DocBook (SGML/XML) realizzati da
	<ulink url="http://www.nwalsh.com/">Norman Walsh</ulink> sono mantenuti al
	<ulink url="http://docbook.sourceforge.net/">DocBook Open Repository</ulink>
	al sito <ulink url="http://www.sourceforge.net/">SourceForge</ulink>.
	Questi file, anche conosciuti come <ulink url="http://docbook.sourceforge.net/projects/dsssl/doc/">Modular DocBook
	Stylesheets</ulink> (fogli di stile modulari per DocBook), dicono ad <filename>openjade</filename> 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
	<ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/index.htm">DSSSL</ulink>. Il linguaggio DSSSL
	è strutturato in un gruppo di linguaggi differenti, ma alla base di tutti vi è il
	<ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/h2-15.htm">Core Expression Language</ulink>
	che è basato su <ulink url="http://www.schemers.org/Documents/Standards/R5RS/HTML/">Scheme</ulink>.
	</para>

	<para>
	Il pacchetto e la documentazione del DSSSL DocBook possono essere scaricati dal sito del
	<ulink url="http://docbook.sourceforge.net/projects/dsssl/">DocBook DSSSL Stylesheets Project</ulink>
	</para>

	<para>
	Il <ulink url="http://www.linuxdoc.org/">Linux Documentation Project</ulink> ha un foglio di stile
	personalizzato che mette a disposizione alcune interessanti caratteristiche di stile. può essere scaricato
	dal sito:
	</para>
	<para>
	<ulink url="http://www.linuxdoc.org/authors/tools/ldp.dsl">http://www.linuxdoc.org/authors/tools/ldp.dsl</ulink>
	</para>
	</sect2>

	<sect2>
	<title>SGMLtools-Lite</title>
	<para>
	SGMLtools-Lite è una interfaccia utente per openjade, <filename>jadetex</filename>,
	<filename>pdfjadex</filename>, <filename>dvips</filename> 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:
	</para>
	<para><ulink url="http://sourceforge.net/projects/sgmltools-lite/">http://sourceforge.net/projects/sgmltools-lite/</ulink></para>
	<para>
	Questo pacchetto è opzionale, ma talvolta rende le cose più facili.
	</para>
	</sect2>

	<sect2>
	<title>HTMLdoc</title>
	<para>
	HTMLdoc è un programma gratuito per convertire siti web nei formati Portable Document Format
	(<filename>pdf</filename>) o <productname>PostScript</productname> (<filename>ps</filename>). Per il
	<filename>pdf</filename>, crea anche un albero di segnalibri che rendono facile la navigazione.
	Sia <command>htmldoc</command> che <command>pdfjadetex</command> emettono file <filename>pdf</filename>,
	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.
	</para>

	<para>
	Si può scaricare l'ultima versione di <productname>HTMLdoc</productname>
	dal <ulink url="ftp://ftp.easysw.com/pub/htmldoc/">sito ftp</ulink> della
	<ulink url="http://www.easysw.com/">Easy Software Products</ulink>.
	</para>

	</sect2>

	<sect2>
	<title>DocBook2X</title>
	<para>
	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
	<filename>sgmlspl</filename> 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.
	</para>
	<para><ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink></para>
	<para><ulink url="http://docbook2x.sourceforge.net/">http://docbook2x.sourceforge.net/</ulink></para>
	</sect2>

</sect1>


<sect1 id="install">
<title>Installazione dei pacchetti</title>
	<sect2>
	 <title>Prima dell'installazione</title>
	 <para>
	 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.
	 </para>
	 <para>
	 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 <filename>README</filename>
	 ed <filename>INSTALL</filename> dopo aver decompresso gli archivi.
	 </para>
	 <para>
	 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.
	 </para>
	</sect2>

	<sect2>
	<title>Installazione di OpenJade</title>

	<sect3>
	<title>openjade</title>
	<para>
	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:
	<screen>
		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
	</screen>
	L'installazione mette le librerie nella directory <filename>/usr/local/openjade-1.3/lib</filename>,
	perciò è preferibile aggiungerla al <filename>/etc/ld.so.conf</filename> e lanciare ldconfig.
	Aggiungere <filename>/usr/local/openjade-1.3/bin</filename> alla variabile <envar>$PATH</envar>.
	</para>
	<para>
	Si potrebbe rimanere sorpresi dal fatto che si sono scaricati i sorgenti di openjade direttamente nella directory
	<filename>/usr/local</filename>. L'autore ha sperimentato qualche problema nell'installazione di openjade.
	Comunque, con le nuove versioni di OpenJade, si può provare una collocazione convenzionale
	(<filename>/usr/local/src</filename>) dei sorgenti del pacchetto openjade, modificando l'opzione --prefix che
	identifica la posizione di installazione, e vedere come va.
	</para>
	</sect3>

	<sect3>
	<title>jadetex &amp; pdfjadetex</title>
	<para>
	Come detto, <command>jadetex</command> e <command>pdfjadetex</command> sono macro TeX
	fornite nel pacchetto di OpenJade. Possono essere trovati in
	<filename>/usr/local/openjade-3.1/dsssl</filename>. Una utile guida
	sull'installazione di queste macro è stata realizzata da
	<author>
		<firstname>Frank</firstname>
		<othername role="mi">Atanassow</othername>
		<surname>Christoph</surname>
		<affiliation>
			<orgname>Next Solution Co., Ltd.</orgname>
   		</affiliation>
	</author> e può essere trovata agli indirizzi:
	</para>
	<para><ulink url="ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf">ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf</ulink></para>
	<para><ulink url="http://reaster.com/installjadetex.pdf">http://reaster.com/installjadetex.pdf</ulink></para>
	<para>
	Quanto segue è basato sulle istruzioni contenute in install.pdf:
	</para>
	<sect4>
	<title>Creare il contesto "hugelatex" (se necessario)</title>
	<para>
	Le macro tex <command>jadetex</command> e <command>pdfjadetex</command> richiedono più memoria che una
	regolare esecuzione di <command>tex</command>.
	La configurazione predefinita del limite di memoria di <command>tex</command> è spesso troppo vincolante.
	Il file di configurazione di tex, <filename>texmf.cnf</filename>, può essere modificato e le variabili che
	limitano l'uso della memoria possono essere aumentate. Tuttavia, invece che modificare il file di configurazione
	<filename>texmf.cnf</filename>, che consentirebbe a tex di utilizzare più memoria in tutte le istanze, è
	possibile creare un contesto <command>tex</command> personalizzato, chiamato <command>hugelatex</command>.
	Se sul proprio sistema è già configurato il contesto <command>hugelatex</command>, è possibile saltare questa
	sottosezione (si verifichi con <command>which hugelatex</command>).
	</para>
	<para>
	Verificare se è stato installato un TeX funzionante ed individuarne la directory:
	<screen>
		bash$ which tex
		/usr/share/texmf/bin/tex
		bash$ kpsewhich -expand-var='$TEXMFMAIN'
		/usr/share/texmf
		bash$
	</screen>
	</para>
	<para>
	Con il comando <command>which</command> si dovrebbe trovare la collocazione del programma
	<command>tex</command>. Se non viene trovato, sarà necessario installare teTeX e quindi tornare a questo punto.
	<command>kpsewhich</command> è uno strumento fornito con teTeX che individua la directory principale di
	<command>tex</command> se tutto va bene.
	</para>
	<para>
	Una volta che il percorso della directory <filename>texmf</filename> è noto, si può iniziare l'installazione:

	<screen>
		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
	</screen>

	La directory <filename>web2c</filename> contiene il file di configurazione <filename>texmf.cnf</filename>.
	Fare una copia di riserva di questo file: <command>cp texmf.cnf texmf.cnf.orig</command>. Si modifichi il file
	con un qualunque editor, aggiungendo le seguenti linee alla fine del file:

	<screen>
		% 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
	</screen>

	Nell'esempio, siamo andati avanti aggiungendo anche le voci per <command>jadetex</command> e
	<command>pdfjadetex</command>, che saranno configurati in seguito. Si possono fare delle prove
	modificando queste impostazioni di memoria, se si dovessero verificare problemi con questi valori.
	</para>
	<para>
	Dopo averlo configurato come sopra, <command>hugelatex</command> potrebbe non
	funzionare, finché non sia stato lanciato il programma <command>texhash</command>:
	<screen>
		root# texhash
		texhash: Updating /usr/share/texmf/ls-R...
		texhash: Updating /var/cache/fonts/ls-R...
		texhash: Done.
		root#
	</screen>
	</para>
	</sect4>

	<sect4>
	<title>jadetex &amp; pdfjadetex</title>
	<para>
	La configurazione di <command>jadetex</command> e <command>pdfjadetex</command> è simile
	a quella di <command>hugelatex</command>.
	<screen>
		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
	</screen>
	Questo <filename>Makefile</filename> utilizza il contesto <command>hugelatex</command>,
	quindi <command>hugelatex</command> deve essere stato già configurato. Quando tex è lanciato come
	<command>hugelatex</command>, <command>jadetex</command> o <command>pdfjadetex</command>, riceve il
	suo nome di programma (contesto) dalla variabile <VarName>argv[0]</VarName> nell'ambiente. Quindi, esegue
	una scansione del file <filename>texmf.cnf</filename>, ed utilizza ogni impostazione trovata, specifica
	del contesto scelto. Anche i file di formato (<filename>.fmt</filename>) in
	<filename>/usr/share/texmf/web2c</filename> sono caricati in base al contesto.
	</para>
	<para>
	Il comando <command>jadetex</command> da un file <filename>tex</filename>, generato da
	<command>openjade</command>, crea un file <filename>dvi</filename>.
	<command>pdfjadetex</command> da un file <filename>tex</filename>, generato da
	<command>openjade</command>, crea un file <filename>pdf</filename>.
	Il programma <command>dvips</command> da un file <filename>dvi</filename> crea un file
	<productname>PostScript</productname> <filename>ps</filename> che è possibile inviare
	alla stampante o visualizzare con ghostscript <command>gs</command>.
	</para>
	</sect4>
	</sect3>
	</sect2>

	<sect2>
	<title>Le DTD DocBook per SGML </title>
	<sect3>
	<title>Decomprimere le DTD DocBook per SGML </title>
	<para>
	Le DTD DocBook sono semplicemente dei file di testo <filename>sgml</filename>, quindi non c'è nulla da
	compilare.
	Semplicemente decomprimere gli archivi con <command>unzip</command> da qualche parte:
	<screen>
		# 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
	</screen>
	Se si installa <filename>doctools-1.2</filename> dalla distribuzione XFree86, verranno poste alcune versioni
	più vecchie delle DTD DocBook, quali la <filename>2.4.1/</filename> e la
	<filename>3.0/</filename> in sottodirectory di <filename>docbook</filename>.
	</para>
	<para>
	Vi sono alcune differenze tra le varie versioni delle DTD DocBook. I file <filename>xxissues.txt</filename>
	documentano questi problemi. Sono stati aggiunti, rimossi e rinominati dei marcatori tra una versione e l'altra.
	</para>
	<para>
	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 <filename>3.1/</filename>.
	</para>
	</sect3>

	<sect3>
	<title>Decomprimere le entità ISO8879 </title>
	<para>
	Per ogni versione di DTD DocBook installata, si vada nella relativa directory e vi si decomprima il file
	<filename>iso8879-entities.tar.gz</filename>:
	<screen>
		cd /usr/local/share/sgml/docbook/4.1
		tar -xvzf ~/iso8879-entities.tar.gz
	</screen>
	In ogni directory DocBook, ci dovrebbe essere un file <filename>docbook.cat</filename> od un file
	<filename>catalog</filename>, od entrambi. Se entrambi sono presenti, dovrebbero essere identici. Se è
	presente solo il file <filename>docbook.cat</filename>, si prosegua creando un link simbolico:
	<screen>
		# se necessario...
		cd /usr/local/share/sgml/docbook/4.1
		ln -s docbook.cat catalog
	</screen>
	</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Il DSSSL di DocBook </title>
	<para>
	L'installazione del DSSSL DocBook, che funziona con tutte le versioni di DocBook, consiste solo nella
	decompressione con <command>unzip</command> dell'archivio da qualche parte.
	<screen>
		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.
	</screen>
	Questo è tutto quanto è necessario per installare il DSSSL, eccettuata l'impostazione
	della variabile <envar>$SGML_CATALOG_PATH</envar>, che verrà discussa dopo. Non ci si dimentichi di riordinare
	le modalità ed i proprietari/gruppi dei file decompressi: spesso sono mischiati ed inadatti.
	</para>
	</sect2>

	<sect2>
	<title>SGMLtools-Lite</title>
	<para>
	Se lo si desidera, è possibile installare SGMLtools-Lite, ma questo è opzionale.
	L'installazione è convenzionale:
	<screen>
		cd /usr/src
		tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
		cd sgmltools-lite-3.0.2
		./configure
		make install
	</screen>
	Questi comandi installano lo script <command>sgmltools</command> in <command>python</command> nella
	directory <filename>/usr/local/bin</filename>. Si noti che è necessario <command>python</command>,
	quindi se non lo si ha, questo pacchetto è inutile.
	</para>
	<para>
	Una cosetta da fare per far funzionare lo script <command>sgmltools</command>, è modificarlo ed impostare il
	percorso di <command>openjade</command>: <command>vi `which sgmltools`</command>. Se ne consulti la
	documentazione per saperne di più.
	</para>
	</sect2>

	<sect2>
	<title>htmldoc</title>

	<sect3>
	<title>Dai file binari</title>
	<para>
	&Egrave; preferibile scaricare una distribuzione binaria di <command>htmldoc</command> 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.
	</para>
	</sect3>

	<sect3>
	<title>Dai file sorgenti</title>
	<para>
	Se si scaricano i sorgenti, è necessario anche il <emphasis>Fast Light Tool Kit</emphasis>
	od altrimenti non si riuscirà a fare il link:
	</para>
	<para>
	<ulink url="http://www.fltk.org/">http://www.fltk.org/</ulink>
	</para>

	<para>
	L'installazione è del tipo <command>autoconf</command>.
	Semplicemente si lanci lo script <command>configure</command>, <command>make</command>,
	<command>make install</command>. Se tutto va bene, verrà installato nella directory
	<filename>/usr/bin</filename>.
	</para>
	</sect3>

	<sect3>
	<title>ldp_print</title>
	<para>
	 Il programma <command>htmldoc</command> ha (o aveva) qualche difetto nella elaborazione di file
	 <filename>html</filename> prodotti da <command>openjade</command>. Per esempio, gli elenchi
	 puntati non sono resi adeguatamente e le aree ombreggiate non lo sono sempre.
	</para>
	<para>
	 Per correggere questo problema, è disponibile uno script in <command>perl</command>
	 (<ulink url="http://www.linuxdoc.org/authors/tools/ldp_print.tar.gz">ldp_print</ulink>)
	 sul sito <ulink url="http://www.linuxdoc.org/">LinuxDoc.org</ulink>.
	 Lo script <command>lpd_print</command> analizza un file <filename>html</filename> unico (non spezzetato)
	 prodotto da <command>openjade</command> e quindi esegue <command>htmldoc</command> su di esso per produrre
	 file <filename>pdf</filename> e <filename>ps</filename> correttamente resi.
	 <tip><para>Procuratevelo!</para></tip>
	</para>
	<para>
        <screen>
		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
	</screen>
	Si dia un'occhiata allo script, nel caso ci siano righe di codice da adattare al proprio sistema.
	Forse un giorno i bachi di <command>htmldoc</command> saranno corretti e questo script non sarà più
	necessario.
	</para>
	</sect3>

	</sect2>

	<sect2>
	<title>DocBook2X e SGMLS.pm (sgmlspl)</title>
	<sect3>
	<title>sgmlspl</title>
	<para>
	Prima che i file di specifica di DocBook2X siano utilizzabili, occorre installare il modulo
	<filename>SGMLS.pm</filename> per <command>perl</command> versione 5, ammesso che sia installato
	<command>perl</command> versione 5. L'installazione di questo modulo non è automatica, come per la maggior
	parte dei moduli <command>perl</command>. Utilizza un <filename>Makefile</filename> che deve essere
	modificato prima di lanciare il comando <command>make</command>.
	<screen>
		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
	</screen>
	sgmlspl verrà copiato in /usr/local/bin.
	</para>
	</sect3>

	<sect3>
	<title>docbook2X (docbook2man-spec.pl)</title>
	<para>
	DocBook2X non contiene programmi da compilare od installare con <command>install</command>,
	sebbene abbia alcuni script a cui dare un'occhiata, quindi tutto quello che c'è da fare è decomprimerlo
	da qualche parte.
	<screen>
		cd /usr/local/share/sgml
		tar -xvzf ~/docbook2X-0.6.0.tar.gz
		cd docbook2X
	</screen>
	Nella directory decompressa c'è il file <filename>docbook2man-spec.pl</filename> ed una patch per correggerne
	alcuni errori. Applicare la patch è opzionale ma raccomandabile.
	<screen>
		patch docbook2man-spec.pl docbook2man-spec.pl.patch
	</screen>
	Dopo, nella sezione <emphasis>Usare DocBook</emphasis>, si vedrà come usare
	<command>sgmlspl</command> e <filename>docbook2man-spec.pl</filename> per generare una pagina
	<command>man</command> da un documento DocBook <sgmltag class="StartTag">refentry</sgmltag>.
	</para>
	</sect3>

	</sect2>


	<sect2>
	<title>$SGML_CATALOG_FILES</title>
	<para>
	La variabile d'ambiente <envar>$SGML_CATALOG_FILES</envar> è utilizzata da
	<command>openjade</command> (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 <envar>$SGML_CATALOG_FILES</envar> all'interno del file
	<filename>/etc/profile</filename>:
	<screen>
##########################################################################################
# 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
##########################################################################################
	</screen>
	Salvato il file <filename>profile</filename>, si effettui il <command>logout</command> e quindi il
	login perché le modifiche abbiano effetto.
	</para>
	<para>
	L'installazione è completata! Nella prossima sezione si verificherà l'installazione e si convertiranno
	alcuni file DocBook.
	</para>
	</sect2>

</sect1>

<sect1 id="using">
<title>Usare DocBook</title>
	<para>
	Una volta che tutto è installato, è tempo di verificare quanto fatto e vedere come usare
	<command>openjade</command> e gli altri strumenti.
	</para>

	<para>
	<figure>
	<title>File di esempio DocBook SGML - <filename>test.sgml</filename></title>
	<screen>
&lt;!DOCTYPE article PUBLIC &quot;-//OASIS//DTD DocBook V4.1//EN&quot;&gt;

&lt;article lang=&quot;en&quot;&gt;
&lt;articleinfo&gt;
	&lt;title&gt;This is a Test&lt;/title&gt;

	&lt;author&gt;
		&lt;firstname&gt;John&lt;/firstname&gt;
		&lt;surname&gt;Doe&lt;/surname&gt;
		&lt;othername role=&quot;mi&quot;&gt;L&lt;/othername&gt;
		&lt;affiliation&gt;
			&lt;address&gt;
			&lt;email&gt;j.doe@jdoe dot com&lt;/email&gt;
			&lt;/address&gt;
		&lt;/affiliation&gt;
	&lt;/author&gt;

	&lt;revhistory&gt;
		&lt;revision&gt;
		&lt;revnumber&gt;v1.0&lt;/revnumber&gt;
		&lt;date&gt;2000-12-30&lt;/date&gt;
		&lt;authorinitials&gt;jld&lt;/authorinitials&gt;
		&lt;/revision&gt;
	&lt;/revhistory&gt;

	&lt;abstract&gt;
	&lt;para&gt;
	This is a test DocBook document.
	&lt;/para&gt;
	&lt;/abstract&gt;

&lt;/articleinfo&gt;

&lt;sect1 id=&quot;test1&quot;&gt;
&lt;title&gt;Test 1&lt;/title&gt;
&lt;para&gt;
Test section 1.
&lt;/para&gt;
	&lt;sect2&gt;
	&lt;title&gt;Test 1.1&lt;/title&gt;
	&lt;para&gt;
	Test section 1.1
	&lt;/para&gt;
	&lt;/sect2&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 1.2&lt;/title&gt;
	&lt;para&gt;
	&lt;screen&gt;
		-- Test section 1.2
		openjade -t sgml -d $DSLFILE test.sgml
	&lt;/screen&gt;
	&lt;/para&gt;
	&lt;/sect2&gt;

&lt;/sect1&gt;

&lt;sect1 id=&quot;test2&quot;&gt;
&lt;title&gt;Test 2&lt;/title&gt;
&lt;para&gt;
Test section 2.
&lt;/para&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 2.1&lt;/title&gt;
	&lt;para&gt;
	Test section 2.1
	&lt;/para&gt;
	&lt;/sect2&gt;

	&lt;sect2&gt;
	&lt;title&gt;Test 2.2&lt;/title&gt;
	&lt;para&gt;
	Test section 2.2
	&lt;/para&gt;
	&lt;/sect2&gt;

&lt;/sect1&gt;
&lt;/article&gt;
	</screen>
	</figure>
	Per una guida a DocBook ed una spiegazione degli elementi DocBook, si veda:
	</para>

	<formalpara>
	<title>DocBook: The Definitive Guide</title>
	<para>
	<ulink url="http://www.docbook.org/tdg/en/">http://www.docbook.org/tdg/en/</ulink>
	</para>
	</formalpara>

	<sect2>
	<title>Generazione di HTML</title>
	<sect3>
	<title><filename>docbook.dsl</filename></title>
	<para>
	<figure>
	<title>Generazione di HTML utilizzando <filename>docbook.dsl</filename></title>
	<screen>
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$
	</screen>
	</figure>
	Gli avvisi riguardanti <VarName>DTDDECL</VarName> possono essere ignorati. Possono essere un po' noiosi,
	ma questi avvisi sono normali quando si usa <command>openjade</command>. Altri avvisi ed errori devono
	essere controllati e spesso indicano errori di sintassi che devono essere corretti.
	</para>

	<para>
	Vengono creati due file <filename>htm</filename>, uno per ogni <sgmltag class="StartTag">sect1</sgmltag>.
	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 <filename>docbook.dsl</filename>,
	fornito con i <emphasis>Modular DocBook Stylesheets</emphasis>.
	</para>

	<para>
	I fogli di stile possono essere personalizzati per migliorare le impostazioni predefinite. Se si è scaricato
	il file <filename>ldp.dsl</filename> del <ulink url="http://www.linuxdoc.org/">Linux Documentation
	Project</ulink> e lo si è installato come mostrato nella sezione 3.3, si avrà già a disposizione un foglio di stile
	personalizzato.
	</para>
	</sect3>

	<sect3>
	<title><filename>ldp.dsl</filename></title>
	<para>
	<figure>
	<title>Generazione di HTML utilizzando <filename>ldp.dsl</filename></title>
	<screen>
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$
	</screen>
	</figure>
	</para>
	<para>
	Con il file <filename>ldp.dsl</filename>, il risultato sarà migliore:
	<itemizedlist>
	<listitem>
		<para>
		Le informazioni sull'articolo sono contenute in un file "index" appositamente creato.
		</para>
	</listitem>
	<listitem>
		<para>
		&Egrave; stato generato automaticamente un indice.
		</para>
	</listitem>
	<listitem>
		<para>
		Ogni sezione <sgmltag class="StartTag">sect1</sgmltag> è contenuta in un proprio file.
		</para>
	</listitem>
	<listitem>
		<para>
		I nomi dei file sono derivati dagli attributi ID degli elementi
		<sgmltag class="StartTag">sect1</sgmltag>.
		</para>
	</listitem>
	<listitem>
		<para>
		L'estensione dei file è cambiata in <filename>html</filename>.
		</para>
	</listitem>
	<listitem>
		<para>
		Gli elementi <sgmltag class="StartTag">screen</sgmltag> sono ombreggiati.
		</para>
	</listitem>
	</itemizedlist>
	</para>

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

	<para>
	Per imparare di più su come sono realizzate le personalizzazioni dei fogli di stile, si legga la
	<ulink url="http://nwalsh.com/docbook/dsssl/doc/">documentazione per i Modular DocBook Stylesheets</ulink>.
	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
	<ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/index.htm">DSSSL</ulink>.
	</para>

	<para>
	L'opzione di <command>openjade</command> "-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
	<ulink url="http://www.w3.org/TR/html4/sgml/dtd.html">HTML Document Type Definition (DTD)</ulink>,
	è 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 <filename>pdf</filename> e
	<filename>ps</filename>. L'opzione dsssl_spec deve indicare un file <filename>dsl</filename>, non
	una directory.
	</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Generazione di rtf e tex</title>
	<para>
	<screen>
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
	</screen>
	</para>
	</sect2>

	<sect2>
	<title>Generazione di dvi e ps</title>
	<para>
	<figure>
	<title>Esecuzione di <command>jadetex</command> per generare un file Device Independent (dvi).</title>
	<screen>
-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$
	</screen>
	</figure>
	</para>
	<para>
	La prima volta che viene eseguito <command>jadetex</command>, vengono mostrati degli avvisi.
	Possono essere ignorati. Lanciando il comando una seconda volta, questi non appariranno più.
	</para>
	<para>
	<figure>
	<title>Esecuzione di <command>dvips</command> per generare un file
	<productname>PostScript</productname> (ps).</title>
	<screen>
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' -&gt; test.ps
&lt;texc.pro&gt;&lt;8r.enc&gt;&lt;texps.pro&gt;&lt;special.pro&gt;&lt;color.pro&gt;. [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$
	</screen>
	</figure>
	</para>

	<para>
	<figure>
	<title>Esecuzione di <command>htmldoc</command> per generare un file
	<productname>PostScript</productname> (<filename>ps</filename>).</title>
	<screen>
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$
	</screen>
	</figure>
	</para>
	<para>
	Se il file <filename>ps</filename> non compare come atteso, questo può essere dovuto a bachi
	in <command>htmldoc</command>. Si guardi all'interno dello script <command>ldp_print</command>
	se si vuole utilizzarlo per creare file <filename>ps</filename>.
	</para>
	</sect2>

	<sect2>
	<title>Generazione di pdf</title>
	<para>
	<figure>
	<title>Esecuzione di <command>pdfjadetex</command> per generare un file
	Portable Document Format (<filename>pdf</filename>).</title>
	<screen>
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) )&lt;8r.enc&gt;
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]
	</screen>
	</figure>
	<command>pdfjadetex</command> deve essere eseguito fino a tre volte per risolvere tutti i
	riferimenti interni per cose come i numeri di pagina dell'indice.
	</para>

	<para>
	<figure>
	<title>Esecuzione di <command>htmldoc</command> per generare un file Portable Document Format
	(<filename>pdf</filename>).</title>
	<screen>
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$
	</screen>
	</figure>
	Se abilitato all'interno dello script <command>ldp_print</command>, questo dovrebbe generare anche
	un file <filename>ps</filename>.
	</para>
	</sect2>

	<sect2>
	<title>Utilizzare <command>make</command></title>

	<para>
	Ripetere i comandi per generare i file in uscita può essere noioso.
	Il comando <command>make</command> funziona perfettamente per automatizzare il procedimento.
	</para>

	<para>
	<figure>
		<title>File: <filename>Makefile</filename> - generazione automatica di documenti.</title>

	<programlisting>
# 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) -
	</programlisting>

	</figure>
	</para>
	<para>
	L'uso è analogo alla maggior parte dei progetti:
	<figure>
	<title>Lanciare il comando <command>make</command> per eseguire <filename>Makefile</filename></title>
	<screen>
		-- 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
	</screen>
	</figure>
	</para>
	<para>
	Si notino le regole di compilazione commentate per <filename>pdf</filename> e <filename>ps</filename>,
	che forniscono una via alternativa per generare questi file.
	</para>
	</sect2>

	<sect2>
	<title>Generazione di una pagina <command>man</command></title>
	<para>
	Durante la sezione sull'installazione, si è installato anche il modulo <command>perl</command> versione 5
	<filename>SGMLS.pm</filename>.
	Quindi si è installato Docbook2X che fornisce i file <filename>spec.pl</filename> per trasformare documenti
	DocBook <sgmltag class="StartTag">refentry</sgmltag> nel formato
	<command>nroff</command> (pagine <command>man</command>)
	con <command>sgmlspl</command>.
	</para>
	<para>
	Un esempio di documento Docbook <sgmltag class="StartTag">refentry</sgmltag>, per il comando
	<command>foo</command>, è dato di seguito.
	</para>
	<para>
	<figure>
	<title>Pagina <command>man</command> per il comando <command>foo</command>, sorgente docbook
	<sgmltag class="StartTag">refentry</sgmltag> (<filename>foo-ref.sgml</filename>)</title>
	<screen>
&lt;!DOCTYPE refentry PUBLIC &quot;-//OASIS//DTD DocBook V4.1//EN&quot;&gt;
&lt;refentry&gt;
&lt;refentryinfo&gt;
	&lt;date&gt;2001-01-01&lt;/date&gt;
&lt;/refentryinfo&gt;
&lt;refmeta&gt;
	&lt;refentrytitle&gt;
		&lt;application&gt;foo&lt;/application&gt;
	&lt;/refentrytitle&gt;
	&lt;manvolnum&gt;1&lt;/manvolnum&gt;
	&lt;refmiscinfo&gt;foo 1.0&lt;/refmiscinfo&gt;
&lt;/refmeta&gt;
&lt;refnamediv&gt;
	&lt;refname&gt;
		&lt;application&gt;foo&lt;/application&gt;
	&lt;/refname&gt;
	&lt;refpurpose&gt;
	Does nothing useful.
	&lt;/refpurpose&gt;
&lt;/refnamediv&gt;
&lt;refsynopsisdiv&gt;
	&lt;refsynopsisdivinfo&gt;
		&lt;date&gt;2001-01-01&lt;/date&gt;
	&lt;/refsynopsisdivinfo&gt;
	&lt;cmdsynopsis&gt;
	&lt;command&gt;foo&lt;/command&gt;
&lt;arg&gt;&lt;option&gt;-f &lt;/option&gt;&lt;replaceable class=&quot;parameter&quot;&gt;bar&lt;/replaceable&gt;&lt;/arg&gt;
&lt;arg&gt;&lt;option&gt;-d&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;&lt;/option&gt;&lt;/arg&gt;
&lt;arg rep=&quot;repeat&quot;&gt;&lt;replaceable class=&quot;parameter&quot;&gt;file&lt;/replaceable&gt;&lt;/arg&gt;
	&lt;/cmdsynopsis&gt;
&lt;/refsynopsisdiv&gt;
&lt;refsect1&gt;
	&lt;refsect1info&gt;
		&lt;date&gt;2001-01-01&lt;/date&gt;
	&lt;/refsect1info&gt;
	&lt;title&gt;DESCRIPTION&lt;/title&gt;
	&lt;para&gt;
	&lt;command&gt;foo&lt;/command&gt; does nothing useful.
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;OPTIONS&lt;/title&gt;
	&lt;variablelist&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;-f &lt;replaceable class=&quot;parameter&quot;&gt;bar&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Takes &lt;filename&gt;bar&lt;/filename&gt; 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.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;-d&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Do something, where integer
			&lt;replaceable class=&quot;parameter&quot;&gt;n&lt;/replaceable&gt;
			specifies how many times.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;varlistentry&gt;
		&lt;term&gt;&lt;replaceable class=&quot;parameter&quot;&gt;file...&lt;/replaceable&gt;&lt;/term&gt;
		&lt;listitem&gt;
			&lt;para&gt;
			Processes the files in the order listed,
			sending all output to stdout.
			&lt;/para&gt;
		&lt;/listitem&gt;
	&lt;/varlistentry&gt;
	&lt;/variablelist&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;USAGE&lt;/title&gt;
	&lt;para&gt;
	&lt;command&gt;foo&lt;/command&gt; -f foo.conf -d2 foodata.foo
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;CAVEATS&lt;/title&gt;
	&lt;para&gt;
	Other programs named &lt;command&gt;foo&lt;/command&gt; may exist and actually
	do something!
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;BUGS&lt;/title&gt;
	&lt;para&gt;
	None.  Program does nothing.
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;refsect1&gt;
	&lt;title&gt;AUTHOR&lt;/title&gt;
	&lt;para&gt;
	&lt;author&gt;
		&lt;firstname&gt;Foo&lt;/firstname&gt;
		&lt;othername role=&quot;mi&quot;&gt;E&lt;/othername&gt;
		&lt;surname&gt;Bar&lt;/surname&gt;
		&lt;contrib&gt;Original author&lt;/contrib&gt;
	&lt;/author&gt;
	&lt;/para&gt;
&lt;/refsect1&gt;
&lt;/refentry&gt;
	</screen>
	</figure>
	</para>

	<para>
	<figure>
	<title>Generazione di una pagina <command>man</command> con <command>onsgmls</command>, <command>sgmlspl</command> e <filename>docbook2man-spec.pl</filename></title>
	<screen>
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
	</screen>
	</figure>
	</para>

	<para>
	La pagina <command>man</command>, <filename>foo.1</filename>, viene generata come pagina della sezione 1.
	Il comando <command>groff</command> è stato utilizzato per dare un rapido sguardo all'aspetto formattato.
	</para>
	<para>
	Per installare questa pagina <command>man</command>, essa deve essere sistemata in una directory
	<filename>man/man1</filename>, con la directory <filename>man/</filename> che è stata aggiunta
	alla variabile di ambiente <envar>$MANPATH</envar>. La collocazione convenzionale è
	<filename>/usr/local/man/man1</filename>.
	Le sezioni convenzionali nel sistema delle pagine <command>man</command> vanno da 1 a 9.
	Ognuna di esse è pensata per contenere specifiche categorie di documenti.
	</para>

	<table>
	<title>Sezioni delle pagine di manuale</title>
	<tgroup cols="2" align="center">
	<thead>
	<row>
		<entry>Sezione</entry>
		<entry>Scopo</entry>
	</row>
	</thead>
	<tbody>
	<row>
		<entry>man1</entry>
		<entry>Programmi utente</entry>
	</row>
	<row>
		<entry>man2</entry>
		<entry>Chiamate di sistema</entry>
	</row>
	<row>
		<entry>man3</entry>
		<entry>Funzioni e subroutine di libreria</entry>
	</row>
	<row>
		<entry>man4</entry>
		<entry>Dispositivi</entry>
	</row>
	<row>
		<entry>man5</entry>
		<entry>Formati dei file</entry>
	</row>
	<row>
		<entry>man6</entry>
		<entry>Giochi</entry>
	</row>
	<row>
		<entry>man7</entry>
		<entry>Varie</entry>
	</row>
	<row>
		<entry>man8</entry>
		<entry>Amministrazione di sistema</entry>
	</row>
	<row>
		<entry>man9</entry>
		<entry>Variabili interne e funzioni del kernel</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<tip>
	<para>
	Il file sorgente per una pagina <command>man</command>, come <filename>foo-ref.sgml</filename>,
	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
	<filename>html</filename> e per la stampa, una pagina <command>man</command> può essere trasformata in
	<filename>html</filename> e <filename>rtf</filename>, <filename>tex</filename>,
	<filename>pdf</filename>, <filename>dvi</filename> e <filename>ps</filename>.
	Questo può consentire di risparmiare molto lavoro di conversione!
	</para>
	</tip>

	<para>
	Buon divertimento<emphasis>!</emphasis>
	</para>
	</sect2>
</sect1>

<appendix id="legal">
<title>Note Legali</title>
<sect1 id="copyright">
	<title>Copyright e Licenze</title>

    <blockquote>
     <para>
      Copyright (c)  2001, 2002  Robert B. Easter
     </para>
     <para>
      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".
     </para>
     <para>(NdT di seguito è riportata la traduzione del paragrafo precedente, con
     l'avvertenza che ha valore legale solo il testo originale in inglese)
     </para>
     <para>
      Copyright (c)  2001, 2002  Robert B. Easter
     </para>
     <para>
      &Egrave; 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".
     </para>
    </blockquote>
</sect1>

<sect1 id="disclaimer">
   <title>Liberatoria</title>

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

   <para>
    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.
   </para>

   <para>
    Naming of particular products or brands should not be seen
    as endorsements.
   </para>
     <para>(NdT di seguito è riportata la traduzione dei paragrafi precedenti, con
     l'avvertenza che ha valore legale solo il testo originale in inglese)
     </para>
   <para>
    Nessuna responsabilità è assunta per il contenuto di questo documento.
    Chi utilizza i concetti, gli esempi ed altri contenuti lo fa a proprio rischio.
   </para>

   <para>
    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.
   </para>

   <para>
    L'aver nominato particolari prodotti o marchi non deve essere visto
    come un sostegno agli stessi.
   </para>
</sect1>
</appendix>


<appendix id="gfdl">
<title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->


  <!-- sect1>
    <title>GNU Free Documentation License</title -->
     <para>(NdT traduzione della presente licenza può essere trovata sul sito
     <ulink url="http://it.tldp.org/gpl.it.txt">http://it.tldp.org/gpl.it.txt</ulink>
     con l'avvertenza che ha valore legale solo il testo originale in inglese)
     </para>

    <para>Version 1.1, March 2000</para>

    <blockquote>
      <para>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.</para>
    </blockquote>

  <sect1 label="0">
    <title>PREAMBLE</title>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="1">
    <title>APPLICABILITY AND DEFINITIONS</title>

    <para>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".</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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".</para>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="2">
    <title>VERBATIM COPYING</title>

    <para>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.</para>

    <para>You may also lend copies, under the same conditions stated
    above, and you may publicly display copies.</para>
  </sect1>

  <sect1 label="3">
    <title>COPYING IN QUANTITY</title>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="4">
    <title>MODIFICATIONS</title>

    <para>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:</para>

    <orderedlist numeration="upperalpha">
      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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).</para>
      </listitem>

      <listitem><para>State on the Title page
      the name of the publisher of the Modified Version, as the
      publisher.</para>
      </listitem>

      <listitem><para>Preserve all the
      copyright notices of the Document.</para>
      </listitem>

      <listitem><para>Add an appropriate
      copyright notice for your modifications adjacent to the other
      copyright notices.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>Preserve in that license
      notice the full lists of Invariant Sections and required Cover
      Texts given in the Document's license notice.</para>
      </listitem>

      <listitem><para>Include an unaltered
      copy of this License.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>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.</para>
      </listitem>

      <listitem><para>Delete any section
      entitled "Endorsements".  Such a section may not be included in
      the Modified Version.</para>
      </listitem>

      <listitem><para>Do not retitle any
      existing section as "Endorsements" or to conflict in title with
      any Invariant Section.</para>
      </listitem>
    </orderedlist>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="5">
    <title>COMBINING DOCUMENTS</title>

    <para>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.</para>

    <para>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.</para>

    <para>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."</para>
  </sect1>

  <sect1 label="6">
    <title>COLLECTIONS OF DOCUMENTS</title>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="7">
    <title>AGGREGATION WITH INDEPENDENT WORKS</title>

    <para>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.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="8">
    <title>TRANSLATION</title>

    <para>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.</para>
  </sect1>

  <sect1 label="9">
    <title>TERMINATION</title>

    <para>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.</para>
  </sect1>

  <sect1 label="10">
    <title>FUTURE REVISIONS OF THIS LICENSE</title>

    <para>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 <ulink
    url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>

    <para>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.</para>
  </sect1>

  <sect1 label="">
    <title>How to use this License for your documents</title>

    <para>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:</para>

<blockquote><para>
      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".
</para></blockquote>

    <para>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.</para>

    <para>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.</para>
  </sect1>

</appendix>

</article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-parent-document: ("referenz.sgml" "appendix")
sgml-exposed-tags:nil
sgml-local-ecat-files:nil
sgml-local-catalogs: CATALOG
sgml-validate-command: "nsgmls -s referenz.sgml"
ispell-skip-sgml: t
End:
-->
