DocBook Install mini-HOWTO
IndietroAvanti

4. Usare DocBook

Una volta che tutto è installato, è tempo di verificare quanto fatto e vedere come usare openjade e gli altri strumenti.

Figura 1. File di esempio DocBook SGML - test.sgml

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

<article lang="en">
<articleinfo>
	<title>This is a Test</title>

	<author>
		<firstname>John</firstname>
		<surname>Doe</surname>
		<othername role="mi">L</othername>
		<affiliation>
			<address>
			<email>j.doe@jdoe dot com</email>
			</address>
		</affiliation>
	</author>

	<revhistory>
		<revision>
		<revnumber>v1.0</revnumber>
		<date>2000-12-30</date>
		<authorinitials>jld</authorinitials>
		</revision>
	</revhistory>

	<abstract>
	<para>
	This is a test DocBook document.
	</para>
	</abstract>

</articleinfo>

<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
	<sect2>
	<title>Test 1.1</title>
	<para>
	Test section 1.1
	</para>
	</sect2>

	<sect2>
	<title>Test 1.2</title>
	<para>
	<screen>
		-- Test section 1.2
		openjade -t sgml -d $DSLFILE test.sgml
	</screen>
	</para>
	</sect2>

</sect1>

<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>

	<sect2>
	<title>Test 2.1</title>
	<para>
	Test section 2.1
	</para>
	</sect2>

	<sect2>
	<title>Test 2.2</title>
	<para>
	Test section 2.2
	</para>
	</sect2>

</sect1>
</article>
Per una guida a DocBook ed una spiegazione degli elementi DocBook, si veda:

DocBook: The Definitive Guide. http://www.docbook.org/tdg/en/

4.1. Generazione di HTML

4.1.1. docbook.dsl

Figura 2. Generazione di HTML utilizzando docbook.dsl

bash$ ls -l
total 4
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
bash$ echo $SGML_SHARE
/usr/local/share/sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml
[omissis - le voci di catalogo DTDDECL non sono supportate, ripetuto]
bash$ ls -l
total 12
-rw-r--r--   1 reaster  users        1885 Dec 31 17:34 t1.htm
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1544 Dec 31 17:34 x27.htm
bash$
Gli avvisi riguardanti DTDDECL possono essere ignorati. Possono essere un po' noiosi, ma questi avvisi sono normali quando si usa openjade. Altri avvisi ed errori devono essere controllati e spesso indicano errori di sintassi che devono essere corretti.

Vengono creati due file htm, uno per ogni <sect1>. I nomi dei file non sono molto descrittivi. La sezione uno compare sulla medesima pagina delle informazioni sull'articolo. Questi sono i risultati ottenuti con il foglio di stile predefinito docbook.dsl, fornito con i Modular DocBook Stylesheets.

I fogli di stile possono essere personalizzati per migliorare le impostazioni predefinite. Se si è scaricato il file ldp.dsl del Linux Documentation Project e lo si è installato come mostrato nella sezione 3.3, si avrà già a disposizione un foglio di stile personalizzato.

4.1.2. ldp.dsl

Figura 3. Generazione di HTML utilizzando ldp.dsl

bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml
bash$ ls -l
total 16
-rw-r--r--   1 reaster  users        2006 Dec 31 18:00 index.html
-rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
-rw-r--r--   1 reaster  users        1677 Dec 31 18:00 test1.html
-rw-r--r--   1 reaster  users        1598 Dec 31 18:00 test2.html
bash$

Con il file ldp.dsl, il risultato sarà migliore:

  • Le informazioni sull'articolo sono contenute in un file "index" appositamente creato.

  • È stato generato automaticamente un indice.

  • Ogni sezione <sect1> è contenuta in un proprio file.

  • I nomi dei file sono derivati dagli attributi ID degli elementi <sect1>.

  • L'estensione dei file è cambiata in html.

  • Gli elementi <screen> sono ombreggiati.

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

Per imparare di più su come sono realizzate le personalizzazioni dei fogli di stile, si legga la documentazione per i Modular DocBook Stylesheets. Le personalizzazioni essenzialmente interessano impostazioni di parametri booleani per selezionare o deselezionare le diverse caratteristiche dello stile. Si può programmare una logica di stile completamente nuova utilizzando il linguaggio DSSSL.

L'opzione di openjade "-t tipo_di_output" specifica il tipo di output. L'opzione "-d dsssl_spec" è il percorso del foglio di stile dsssl da utilizzare. Nell'esempio precedente, il tipo di output specificato è l'sgml, che è utilizzato per le trasformazioni da SGML a SGML. L'HTML, definito attraverso la HTML Document Type Definition (DTD), è un documento di tipo SGML, come lo è DocBook, quindi "sgml" è la corretta opzione per il tipo di output. Gli altri due tipi di output comunemente usati sono "rtf" e "tex". L'opzione tex verrà usata in seguito come formato intermedio per la generazione di file nel formato pdf e ps. L'opzione dsssl_spec deve indicare un file dsl, non una directory.

4.2. Generazione di rtf e tex

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ ls -l
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex

4.3. Generazione di dvi e ps

Figura 4. Esecuzione di jadetex per generare un file Device Independent (dvi).

-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
No file test.aux.
(/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd)

LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238.


LaTeX Warning: Reference `20' on page 1 undefined on input line 262.


LaTeX Warning: Reference `23' on page 1 undefined on input line 285.


LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316.


LaTeX Warning: Reference `30' on page 1 undefined on input line 340.


LaTeX Warning: Reference `33' on page 1 undefined on input line 363.

[1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux)

LaTeX Warning: There were undefined references.

 )
Output written on test.dvi (3 pages, 34984 bytes).
Transcript written on test.log.
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         771 Dec 31 20:55 test.aux
-rw-r--r--   1 reaster  users       34984 Dec 31 20:55 test.dvi
-rw-r--r--   1 reaster  users        5072 Dec 31 20:55 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
Output written on test.dvi (3 pages, 34148 bytes).
Transcript written on test.log.
You have new mail in /var/spool/mail/reaster
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

La prima volta che viene eseguito jadetex, vengono mostrati degli avvisi. Possono essere ignorati. Lanciando il comando una seconda volta, questi non appariranno più.

Figura 5. Esecuzione di dvips per generare un file PostScript (ps).

bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ dvips test.dvi
This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
' TeX output 2000.12.31:2058' -> test.ps
<texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3]
bash$ ls -l
total 116
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$

Figura 6. Esecuzione di htmldoc per generare un file PostScript (ps).

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps -
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 00:44 test-htmldoc.ps
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$

Se il file ps non compare come atteso, questo può essere dovuto a bachi in htmldoc. Si guardi all'interno dello script ldp_print se si vuole utilizzarlo per creare file ps.

4.4. Generazione di pdf

Figura 7. Esecuzione di pdfjadetex per generare un file Portable Document Format (pdf).

bash$ ls -l
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ pdfjadetex test.tex
This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
(test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/context/base/supp-pdf.tex
(/usr/share/texmf/tex/context/base/supp-mis.tex
loading : Context Support Macros / Missing
)
loading : Context Support Macros / PDF
) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
 (test.aux) )<8r.enc>
Output written on test.pdf (3 pages, 9912 bytes).
Transcript written on test.log.
bash$ ls -l
total 128
-rw-r--r--   1 reaster  users         753 Dec 31 21:13 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        5075 Dec 31 21:13 test.log
-rw-r--r--   1 reaster  users        9912 Dec 31 21:13 test.pdf
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]
pdfjadetex deve essere eseguito fino a tre volte per risolvere tutti i riferimenti interni per cose come i numeri di pagina dell'indice.

Figura 8. Esecuzione di htmldoc per generare un file Portable Document Format (pdf).

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
bash$ ldp_print test-htmldoc.htm
bash$ ls -l
-rw-r--r--   1 reaster  users        9050 Jan  1 01:17 test-htmldoc.pdf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$
Se abilitato all'interno dello script ldp_print, questo dovrebbe generare anche un file ps.

4.5. Utilizzare make

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

Figura 9. File: Makefile - generazione automatica di documenti.

# Generazione di versioni per la visualizzazione e la stampa da file sorgente SGML

BASENAME=DocBook-Install

# File sorgente SGML
SGML_FILE=$(BASENAME).sgml

# Fogli di stile
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html

# File prodotti
HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf
DVI_FILE=$(BASENAME).dvi
PS_FILE=$(BASENAME).ps


# Regole di costruzione

html: $(HTML_FILE)

htm: $(HTM_FILE)

tex: $(TEX_FILE)

rtf: $(RTF_FILE)

pdf: $(PDF_FILE)

dvi: $(DVI_FILE)

ps: $(PS_FILE)

all: html htm tex rtf pdf dvi ps

clean:
	rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
	rm -f *.html

distclean: clean
	rm -f $(BASENAME).tgz

package:
	rm -f $(BASENAME).tgz
	tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
	mv /tmp/$(BASENAME).tgz .

dist: clean package

distall: all package


# Regole di compilazione

$(HTML_FILE): $(SGML_FILE)
	openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)

$(HTM_FILE): $(SGML_FILE)
	openjade -t sgml -V nochunks -d $(DSL_HTML) \
	$(SGML_FILE) > $(HTM_FILE)

$(TEX_FILE): $(SGML_FILE)
	openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)

$(RTF_FILE): $(SGML_FILE)
	openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)

# [pdf]jadetex deve essere eseguito 3 volte per risolvere tutti i riferimenti.
#$(PDF_FILE): $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)

# Questo *dovrebbe* funzionare, ma htmldoc ha dei bachi...
#$(PDF_FILE): $(SGML_FILE)
#	openjade -t sgml -V nochunks -d $(DSL_HTML) \
#	$(SGML_FILE) | htmldoc -f $(PDF_FILE) -

# Si deve usare ldp_print per aggirare i bachi di htmldoc
# ldp_print può anche creare il file ps - si veda lo script
$(PDF_FILE): $(HTM_FILE)
	ldp_print $(HTM_FILE)

$(DVI_FILE): $(TEX_FILE)
	jadetex $(TEX_FILE)
	jadetex $(TEX_FILE)
	jadetex $(TEX_FILE)

$(PS_FILE): $(DVI_FILE)
	dvips $(DVI_FILE)

#$(PS_FILE): $(SGML_FILE)
#	openjade -t sgml -V nochunks -d $(DSL_HTML) \
#	$(SGML_FILE) | htmldoc -f $(PS_FILE) -

L'uso è analogo alla maggior parte dei progetti:

Figura 10. Lanciare il comando make per eseguire Makefile

		-- generare html (predefinito)
		make
		-- generare solamente pdf
		make pdf
		-- generare tutti i file
		make all
		-- cancellare tutti i file generati
		make clean
		-- creare un pacchetto tgz per la distribuzione
		-- senza generare file
		make dist
		-- creare un pacchetto tgz per la distribuzione
		-- contenente tutti i file generati
		make distall

Si notino le regole di compilazione commentate per pdf e ps, che forniscono una via alternativa per generare questi file.

4.6. Generazione di una pagina man

Durante la sezione sull'installazione, si è installato anche il modulo perl versione 5 SGMLS.pm. Quindi si è installato Docbook2X che fornisce i file spec.pl per trasformare documenti DocBook <refentry> nel formato nroff (pagine man) con sgmlspl.

Un esempio di documento Docbook <refentry>, per il comando foo, è dato di seguito.

Figura 11. Pagina man per il comando foo, sorgente docbook <refentry> (foo-ref.sgml)

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refentryinfo>
	<date>2001-01-01</date>
</refentryinfo>
<refmeta>
	<refentrytitle>
		<application>foo</application>
	</refentrytitle>
	<manvolnum>1</manvolnum>
	<refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>
<refnamediv>
	<refname>
		<application>foo</application>
	</refname>
	<refpurpose>
	Does nothing useful.
	</refpurpose>
</refnamediv>
<refsynopsisdiv>
	<refsynopsisdivinfo>
		<date>2001-01-01</date>
	</refsynopsisdivinfo>
	<cmdsynopsis>
	<command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
	</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
	<refsect1info>
		<date>2001-01-01</date>
	</refsect1info>
	<title>DESCRIPTION</title>
	<para>
	<command>foo</command> does nothing useful.
	</para>
</refsect1>
<refsect1>
	<title>OPTIONS</title>
	<variablelist>
	<varlistentry>
		<term>-f <replaceable class="parameter">bar</replaceable></term>
		<listitem>
			<para>
			Takes <filename>bar</filename> as it's run
			control file. If this were a real program,
			there might be more to say here about what
			bar is and how it will be used.
			</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term>-d<replaceable class="parameter">n</replaceable></term>
		<listitem>
			<para>
			Do something, where integer
			<replaceable class="parameter">n</replaceable>
			specifies how many times.
			</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><replaceable class="parameter">file...</replaceable></term>
		<listitem>
			<para>
			Processes the files in the order listed,
			sending all output to stdout.
			</para>
		</listitem>
	</varlistentry>
	</variablelist>
</refsect1>
<refsect1>
	<title>USAGE</title>
	<para>
	<command>foo</command> -f foo.conf -d2 foodata.foo
	</para>
</refsect1>
<refsect1>
	<title>CAVEATS</title>
	<para>
	Other programs named <command>foo</command> may exist and actually
	do something!
	</para>
</refsect1>
<refsect1>
	<title>BUGS</title>
	<para>
	None.  Program does nothing.
	</para>
</refsect1>
<refsect1>
	<title>AUTHOR</title>
	<para>
	<author>
		<firstname>Foo</firstname>
		<othername role="mi">E</othername>
		<surname>Bar</surname>
		<contrib>Original author</contrib>
	</author>
	</para>
</refsect1>
</refentry>

Figura 12. Generazione di una pagina man con onsgmls, sgmlspl e docbook2man-spec.pl

bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
bash$ ls -l
-rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
-rw-r--r--   1 reaster  users        1129 Jan  3 04:03 foo.1
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.links
-rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.log
-rw-r--r--   1 reaster  users          15 Jan  3 04:03 manpage.refs
bash$ groff -mandoc -Tascii foo.1

FOO(1)                                                     FOO(1)


NAME
       foo - Does nothing useful.

SYNOPSIS
       foo [ -f bar ]  [ -dn ]  [ file... ]

DESCRIPTION
       foo does nothing useful.

OPTIONS
       -f bar Takes  bar as its run control file. If this were a
              real program, there might be more to say here about
              what bar is and how it will be used.

       -dn    Do  something,  where  integer n specifies how many
              times.

       file...
              Processes the files in the  order  listed,  sending
              all output to stdout.

USAGE
       foo -f foo.conf -d2 foodata.foo

CAVEATS
       Other  programs  named foo may exist and actually do some-
       thing!

BUGS
       None. Program does nothing.

AUTHOR
       Foo E Bar (Original author)

[omissis - alcune ulteriori righe bianche che man non mostrerebbe]
foo 1.0                     2001-01-01                          1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1

La pagina man, foo.1, viene generata come pagina della sezione 1. Il comando groff è stato utilizzato per dare un rapido sguardo all'aspetto formattato.

Per installare questa pagina man, essa deve essere sistemata in una directory man/man1, con la directory man/ che è stata aggiunta alla variabile di ambiente $MANPATH. La collocazione convenzionale è /usr/local/man/man1. Le sezioni convenzionali nel sistema delle pagine man vanno da 1 a 9. Ognuna di esse è pensata per contenere specifiche categorie di documenti.

Tabella 1. Sezioni delle pagine di manuale

SezioneScopo
man1Programmi utente
man2Chiamate di sistema
man3Funzioni e subroutine di libreria
man4Dispositivi
man5Formati dei file
man6Giochi
man7Varie
man8Amministrazione di sistema
man9Variabili interne e funzioni del kernel

Suggerimento

Il file sorgente per una pagina man, come foo-ref.sgml, può essere trasformato in tutti gli altri formati, come per ogni altro file DocBook. Quindi, utilizzando gli stessi comandi discussi precedentemente per generare output in html e per la stampa, una pagina man può essere trasformata in html e rtf, tex, pdf, dvi e ps. Questo può consentire di risparmiare molto lavoro di conversione!

Buon divertimento!

IndietroPartenzaAvanti
Installazione dei pacchetti Note Legali