Gebruiken van DocBook

Nu alles is geïnstalleerd, is de tijd aangebroken om het uit te gaan testen en te bekijken hoe openjade en de andere tools kunnen worden toegepast.

Figure 1. Voorbeeld DocBook SGML bestand - test.sgml

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

<article lang="en">
<articleinfo>
<title>Dit is een 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>30-12-2000</date>
<authorinitials>jld</authorinitials>
</revision>
</revhistory>

<abstract>
<para>
Dit is een DocBook testdocument.
</para>
</abstract>

</articleinfo>

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

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

</sect1>

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

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

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

</sect1>
</article>
Zie voor een handleiding over DocBook en een referentie van DocBook elementen:

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

HTML genereren

docbook.dsl

Figure 2. HTML-uitvoer genereren met behulp van 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
[snip - DTDDECL catalog entries are not supported, repeats]
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$
De waarschuwingen over DTDDECL kunnen worden genegeerd. Ze zijn wellicht wat ergerlijk, maar deze waarschuwingen zijn normaal wanneer openjade wordt gebruikt. Andere waarschuwingen en foutmeldingen zouden moeten worden onderzocht en deze geven vaak syntaxfouten aan die moeten worden gecorrigeerd.

Er worden twee htm bestanden gegenereerd, één voor elke <sect1>. De bestandsnamen zijn niet erg beschrijvend. Sectie één verschijnt op dezelfde pagina als de informatie over het artikel. Dit is het resultaat van het gebruik van de standaard stylesheet die wordt meegeleverd met de Modulaire DocBook Stylesheets, docbook.dsl.

Stylesheets kunnen worden aangepast om deze standaards te verbeteren. Als je het bestand ldp.dsl van het Linux Documentatie Project downloadde en het installeerde zoals weergegeven in sectie 3.3, dan heb je reeds een aangepaste stijl beschikbaar.

ldp.dsl

Figure 3. Genereren van HTML-uitvoer met 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$

Met gebruik van ldp.dsl ziet de uitvoer er veel beter uit:

  • Er wordt een indexbestand aangemaakt met de informatie over het artikel.

  • Er wordt automatisch een inhoudsopgave gegenereerd.

  • Elke <sect1> komt in een eigen bestand.

  • Bestandsnamen worden afgeleid van ID-attributen van de <sect1> elementen.

  • De bestandsextensie wordt gewijzigd in html.

  • De <screen> elementen zijn geschaduwd.

Let op hoe het bestand ldp.dsl op de opdrachtregel wordt geschreven, "#html" is toegevoegd. ldp.dsl bevat twee <STYLE-SPECIFICATION> elementen, één met ID="html" en een ander met ID="print". Hiermee wordt de html stijl uit de ldp.dsl geselecteerd. De DocBook DSSSL bevat ondersteuning voor het converteren van DocBook bestanden naar html en print formaten. In sectie 3.3 kopieerde we ldp.dsl naar zowel de print als de html directory's. Bij het genereren van html uitvoer, zou de html style als hierboven moeten worden geselecteerd. Bij het genereren van andere type bestanden, zoals rtf en tex, vallen die onder de print stijl en dus zou de print stijl moeten worden geselecteerd uit ldp.dsl. Het alternatief is een commentaarteken te plaatsen voor de print of html stijl of deze te verwijderen uit de kopie van het bestand ldp.dsl in de respectieve directory. Als zich in een dsl bestand meer style-spec bevinden, en er geen wordt geselecteerd zoals in bovenstaand voorbeeld, dan zal de eerst aangetroffen stijl in het bestand worden geselecteerd. In het bestand ldp.dsl is de print style-spec het eerstvoorkomende in het bestand, dus wordt het standaard geselecteerd. Dus in bovenstaand voorbeeld zonder het toevoegen van "#html" bij het specificeren van ldp.dsl als de dsssl stylesheet, zou de "print" style-spec worden geselecteerd en gebruikt voor het genereren van de html uitvoer. Het zal wel werken, maar het is bedoeld voor wanneer de print/ldp.dsl wordt geselecteerd en de opmaak zal anders zijn.

Lees de documentatie voor de Modulaire DocBook Stylesheets om meer te leren over hoe de aanpassingen op de stylesheet bestanden kunnen worden gemaakt De aanpasssingen beslaan hoofdzakelijk het instellen van boolean optie parameters om de style features aan of uit te zetten. Een compleet nieuwe logicastijl kan worden geprogrammeerd in de DSSSL taal.

De openjade optie "-t output_type" specificeert het uitvoertype. De "-d dsssl_spec" optie is het pad naar de te gebruiken dsssl stylesheet. In bovenstaand voorbeeld, is het gespecificeerde uitvoertype sgml, wat bedoeld is voor SGML naar SGML transformaties. HTML, gedefineerd door de HTML Document Type Definition (DTD), is een SGML documenttype net als DocBook is, dus "sgml" is de correcte output_type optie. De andere twee uitvoertypes die gewoonlijk worden gebruikt zijn "rtf" en "tex". Het output_type tex zal later worden gebruikt om een tussenliggend formaat te creëren voor de aanmaak van pdf en ps formaten. De dsssl_spec moet een dsl bestand aangeven, geen directory.

Genereren van rtf en 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

Genereren van dvi en ps

Figure 4. jadetex uitvoeren om een Device Independent (dvi) bestand te genereren

-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$

De eerste keer dat jadetex wordt uitgevoerd, worden waarschuwingen afgedrukt. Deze waarschuwingen kunnen worden genegeerd. Ze verschijnen niet meer als jadetex een tweede keer wordt uitgevoerd.

Figure 5. dvips uitvoeren om een PostScript (ps) bestand te genereren.

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$

Figure 6. htmldoc uitvoeren om een PostScript (ps) bestand te genereren

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$
Als het ps bestand niet naar verwachting wordt weergegeven, dan kan dit te wijten zijn aan programmeerfouten in htmldoc. Kijk in het script ldp_print als je het wilt gebruiken om ps te genereren.

PDF genereren

Figure 7. pdfjadetex uitvoeren om een Portable Document Format (pdf) bestand te genereren.

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 moet tot drie keer worden uitgevoerd om alle interne referenties op te lossen voor dingen zoals paginanummers voor in de TOC (Inhoudsopgave).

Figure 8. htmldoc uitvoeren om een Portable Document Format (pdf) bestand te genereren

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$
Als dit zou zijn geactiveerd in het script ldp_print, zou dit ook een ps bestand gegeneren.

Gebruik van make

Het is saai om de opdrachten voor het genereren van de uitvoerbestanden te herhalen. De opdracht make werkt perfect om het proces te automatiseren.

Figure 9. Filename: Makefile - automates document generation.

# Genereert online en printversies van SGML bronbestand.

BASENAME=DocBook-Install

# SGML bronbestand.
SGML_FILE=$(BASENAME).sgml

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

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


# Build rules.

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


# Compileerregels

$(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 is run 3 times to resolve references.
#$(PDF_FILE): $(TEX_FILE)
#pdfjadetex $(TEX_FILE)
#pdfjadetex $(TEX_FILE)
#pdfjadetex $(TEX_FILE)

# This *should* work, but htmldoc has bugs ...
#$(PDF_FILE): $(SGML_FILE)
#openjade -t sgml -V nochunks -d $(DSL_HTML) \
#$(SGML_FILE) | htmldoc -f $(PDF_FILE) -

# Have to use ldp_print to work around htmldoc bugs
# ldp_print can also do the ps file - see 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) -

Het gebruik gaat net als bij de meeste andere projecten:

Figure 10. make aanroepen om Makefile uit te voeren

-- generate html (default)
make
-- generate just pdf
make pdf
-- generate all files
make all
-- delete all generated files
make clean
-- create tgz distribution
-- with no generated files
make dist
-- create tgz distribution
-- containing all generated files
make distall

Let op de becommentarieerde compileregels voor pdf en ps die voorzien in alternatieve middelen voor het genereren van die bestanden.

Genereren van een man page

Tijdens de sectie over de installatie van alle packages, installeerden we de perl versie 5 module SGMLS.pm. Toen installeerden we Docbook2X wat voorziet in de spec.pl bestanden voor het transformeren van DocBook <refentry> documenten naar nroff (man page) formaat met sgmlspl.

Een voorbeeld van een DocBook <refentry> document, voor de opdracht foo wordt hieronder gegeven.

Figure 11. foo command man page, docbook <refentry> source (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>
Doet niets nuttigs.
</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> doet niets nuttigs.
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>-f <replaceable class="parameter">bar</replaceable></term>
<listitem>
<para>
Accepteert <filename>bar</filename> als zijn besturingsbestand
Als dit een echt programma was, zou er wellicht 
hier meer te zeggen zijn wat bar is en hoe het zal worden gebruikt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-d<replaceable class="parameter">n</replaceable></term>
<listitem>
<para>
Doe iets, waar de integer
<replaceable class="parameter">n</replaceable>
aangeeft hoevaak.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">file...</replaceable></term>
<listitem>
<para>
Verwerkt de bestanden in de aangegeven volgorde, waarbij het
alle uitvoer naar stdout zendt.
</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>
Andere programma's met de naam <command>foo</command> kunnen bestaan in werkelijkheid wel iets doen!
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
Geen. Programma doets niets.
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
<author>
<firstname>Foo</firstname>
<othername role="mi">E</othername>
<surname>Bar</surname>
<contrib>Oorspronkelijke auteur</contrib>
</author>
</para>
</refsect1>
</refentry>

Figure 12. Genereren van een man page met onsgmls, sgmlspl, en 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 - Doet niets nuttigs.

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

DESCRIPTION
       foo doet niets nuttigs.

OPTIONS
       -f bar Accepteert bar als zijn besturingsbestand. Als dit een
              echt programma was, dan zou er wellicht meer te zeggen zijn
              over wat bar is en hoe het zal worden gebruikt.

       -dn    Doe iets,  waar de integer n aangeeft hoevaak.

       file...
              Verwerkt de bestanden in de aangegeven volgorde, waarbij het
	      alle uitvoer naar stdout zendt.

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

CAVEATS
       Anders programma's  met de naam foo kunnen bestaan en in
       werkelijkheid wel iets doen!

BUGS
       Geen. Programma doet niets.

AUTHOR
       Foo E Bar (Oorspronkelijke auteur)

[snip - verscheidene extra witregels die man niet zou moeten tonen]
foo 1.0                     2001-01-01                          1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1

De man page, foo.1, wordt gegeneerd als een Sectie 1 pagina. De opdracht groff wordt gebruikt om de opgemaakte verschijning te bekijken.

Deze man hoort thuis in een man/man1 directory. De directory man/ moet zijn toegevoegd aan de omgevingsvariabele $MANPATH. De standaardlokatie is /usr/local/man/man1. De standaardsecties in het systeem met man pages bestaan uit de secties 1 tot en met 9. Elk is bedoeld voor het bijhouden van specifieke catagoriën documentatie.

Table 1. Manual Pages Secties

SectieDoel
man1Gebruikersprogramma's
man2Systeemaanroepen
man3Library functies en subroutines
man4Devices
man5Bestandsformaten
man6Games
man7Diversen
man8Systeembeheer
man9Kernel interne variabelen en functies

Tip

Het bronbestand voor een man page, zoals foo-ref.sgml, kan net als elk ander DocBook bestand worden omgezet in alle andere formaten. Een manpage kan met dezelfde eerder besproken opdrachten worden omgezet in html, rtf, tex, pdf, dvi, en ps formaten. Dit kan je echt heel veel conversiewerk besparen!

Veel plezier !