4. Utiliser DocBook

Maintenant que tout est installé, il est temps de tester notre configuration, et de voir comment utiliser OpenJade et les autres outils.

Figure 1. Exemple de fichier SGML DocBook - test.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article lang="fr">
<articleinfo>
 <title>Ceci est un 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>
 Ceci est un document DocBook de test.
 </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>
Pour un guide sur DocBook et une référence sur les balises DocBook, voyez :

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

4.1. Générer du HTML

4.1.1. docbook.dsl

Figure 2. Création de documents HTML avec 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
[Coupé - "DTDDECL catalog entries are not supported" - Message répété]
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$
Les messages d'avertissement concernant DTDDECL peuvent être ignorés. Ils peuvent être légèrement gênants, mais ils sont normaux lorsqu'on utilise Jade. Les autres messages d'avertissement et d'erreur doivent être surveillés, et indiquent souvent des erreurs de syntaxe qui doivent être corrigées.

Deux fichiers htm sont créés. Un pour chaque <SECT1>. Les noms des fichiers ne sont pas très informatifs. La première section apparaît sur la même page que les informations sur l'article. C'est le résultat de l'utilisation de la feuille de style de base qui est donnée avec les Modular DocBook Stylesheets, docbook.dsl.

Les feuilles de style peuvent être personnalisées pour améliorer ces comportements. Si vous avez téléchargé le fichier ldp.dsl du Projet de Documentation Linux, et l'avez installé comme indiqué à la Section 3.3, alors vous avez déjà un style personnalisé disponible.

4.1.2. ldp.dsl

Figure 3. Création de documents HTML avec 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$

En utilisant ldp.dsl, le résultat est plus satisfaisant :

  • Un fichier d'index contenant les informations sur l'article a été créé.

  • Une table des matières a été créée automatiquement.

  • A chaque <SECT1> correspond son propre fichier.

  • Les noms de fichier correspondent à l'attribut ID des balises <SECT1>

  • Les suffixes des noms de fichier sont maintenant .html.

  • Le contenu des balises <SCREEN> est grisé.

Remarquez comment le fichier ldp.dsl a été saisi sur la ligne de commande : "#html" lui a été accolé. ldp.dsl contient deux balises <STYLE-SPECIFICATION>, une avec un attribut ID="html" et l'autre avec un ID="print". Notre commande permet ainsi de sélectionner le style html dans ldp.dsl. Les DSSSL DocBook permettent de convertir les fichiers DocBook en html ou en format papier. Dans la Section 3.3, nous avons copié ldp.dsl dans les deux répertoires html et print. Quand nous générons du html, le style html doit être sélectionné comme précédemment. La génération d'autres formats comme RTF ou TEX est du ressort de la documentation papier et aussi le style print doit être sélectionné dans ldp.dsl. Une alternative est de mettre en commentaire ou de supprimer le style print ou html suivant le cas, dans les répertoires respectifs. Si un fichier dsl comporte plus d'une spécification de style, mais qu'aucune n'est sélectionnée comme l'exemple précédent, alors c'est le premier style rencontré dans le fichier qui sera sélectionné. Concernant ldp.dsl, les premières spécifications sont pour le style print, aussi il est sélectionné par défaut. Ainsi, en reprenant l'exemple précédent, et en omettant le "#html" lorsqu'on spécifie ldp.dsl comme feuille de style DSSSL, les spécifications de style "print" seront sélectionnées et utilisées lors de la génération de HTML. Ces feuilles fonctionneront, mais sont normalement prévues pour être appelées par print/ldp.dsl, et le formatage sera différent.

Pour en savoir plus sur la façon dont les fichiers de personnalisation des feuilles de style sont conçus, lisez la documentation des Modular DocBook Stylesheets. La personnalisation consiste principalement au positionnement de paramètres booléens pour activer ou non des options de style. Une nouvelle logique de style peut également être programmée en utilisant le langage DSSSL Core Programming Language, comme mentionné dans la Section 2.4.

L'option OpenJade -t type_sortie spécifie le type sortie. L'option -d dsssl_spec est le chemin d'accès à la feuille de style à utiliser. Dans l'exemple précédent, le type de sortie spécifié est sgml, qui est destiné aux transformations SGML vers SGML. Le HTML, comme défini par la Définition de Type de Document (DTD) HTML, est un type de document SGML, tout comme DocBook, aussi, sgml est le type de sortie approprié. Les deux autres types de sortie communément utilisés sont "rtf" et "tex". Le type tex sera utilisé plus tard comme format intermédiaire pour la génération de formats PDF et PS. L'option -d dsssl_spec doit spécifier un fichier et non un répertoire.

4.2. Générer du RTF et du 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. Générer du DVI et du PS

Figure 4. Utiliser jadetex pour générer un fichier DVI (DeVice Independant)

-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 première fois que jadetex est lancé sur un fichier, des avertissements sont imprimés. Ils peuvent être ignorés. Lancez-le une seconde fois sur le même fichier et ils n'apparaissent plus.

Figure 5. Utiliser dvips pour générer un fichier 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$

Figure 6. Utiliser htmldoc pour générer un fichier 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$
Si le fichier PS n'offre pas le résultat attendu, cela est dû à des bugs dans htmldoc. Examinez le script ldp_print si vous voulez l'utiliser pour faire du poscript.

4.4. Générer du PDF

Figure 7. Utiliser pdfjadetex pour générer un fichier PDF (Portable Document Format)

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
[coupé]
bash$ pdfjadetex test.tex
[coupé]
Pdfjadetex doit être lancé jusqu'à trois fois pour résoudre toutes les références internes comme les numéros de pages dans les tables des matières.

Figure 8. Utiliser htmldoc pour générer un fichier PDF (Portable Document Format)

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$
Si l'option est activée dans le script ldp_print, un fichier PS sera également généré.

4.5. Utiliser make

La répétition des commandes pour générer les différents formats est vite fastidieuse. La commande make fonctionne parfaitement pour automatiser le processus.

Figure 9. Makefile - automatiser la génération des documents

# Génère des versions en-ligne et papier depuis un fichier source SGML
BASENAME=DocBook-Install
# fichier source SGML.
SGML_FILE=$(BASENAME).sgml
# Feuilles de style
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html
# Fichiers générés
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
# Règles de création
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
# Règles de compilation
$(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 est lancé trois fois pour résoudre les références
#$(PDF_FILE): $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
# Cela *devrait* fonctionner, mais htmldoc a des bugs...
#$(PDF_FILE): $(SGML_FILE)
#	openjade -t sgml -V nochunks -d $(DSL_HTML) \
#	$(SGML_FILE) | htmldoc -f $(PDF_FILE) -
# Utiliser ldp_print pour pallier les bugs de htmldoc
# ldp_print peut aussi générer un fichier PS - voir le 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) -

On l'utilise comme pour la plupart des projets :

Figure 10. Appeler make pour lancer le Makefile

# générer du html (par défaut)
make
# générer du PDF uniquement
make pdf
# générer tous les formats
make all
# supprimer tous les fichiers générés
make clean
# créer un paquetage tgz
# sans génération de fichiers
make dist
# créer un paquetage tgz
# comprenant tous les formats générés
make distall

Notez la présence de règles de compilation de PDF et de PS mises en commentaire, qui offrent des alternatives sur les moyens de générer ces fichiers.

4.6. Créer une page de manuel

Lors de l'installation des paquetages, nous avons installé le module Perl5 SGMLSpm. Ensuite nous avons installé docbook2X qui fournit les fichiers spec.pl nécessaires à la transformation des documents DocBook RefEntry en fichiers au format nroff (page de manuel) à l'aide de sgmlspl.

Un exemple de document DocBook RefEntry pour la commande foo est donné ci-dessous :

Figure 11. page de manuel foo - source 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>
 Ne fait rien d'utile.
 </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">fichier</replaceable></arg>
 </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
 <refsect1info>
 <date>2001-01-01</date>
 </refsect1info>
 <title>DESCRIPTION</title>
 <para>
 <command>foo</command> ne fait rien d'utile.
 </para>
</refsect1>
<refsect1>
 <title>OPTIONS</title>
 <variablelist>
 <varlistentry>
 <term>-f <replaceable class="parameter">bar</replaceable></term>
 <listitem>
 <para>
 Prend <filename>bar</filename> comme
 fichier de contrôle à l'exécution. S'il s'agissait
 d'un véritable programme, il y aurait plus à dire ici
 sur ce qu'est le fichier bar et comment il serait utilisé.
 </para>
 </listitem>
 </varlistentry>
 <varlistentry>
 <term>-d<replaceable class="parameter">n</replaceable></term>
 <listitem>
 <para>
 Fait quelque chose, où le nombre entier
 <replaceable class="parameter">n</replaceable>
 spécifie combien de fois.
 </para>
 </listitem>
 </varlistentry>
 <varlistentry>
 <term><replaceable class="parameter">fichier...</replaceable></term>
 <listitem>
 <para>
 Traite les fichiers dans l'ordre de leur apparition
 et envoie le résultat sur stdout.
 </para>
 </listitem>
 </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
 <title>UTILISATION</title>
 <para>
 <command>foo</command> -f foo.conf -d2 foodata.foo
 </para>
</refsect1>
<refsect1>
 <title>MISE EN GARDE</title>
 <para>
 D'autres programmes appelés <command>foo</command> peuvent exister
 et faire réellement quelque chose !
 </para>
</refsect1>
<refsect1>
 <title>BUGS</title>
 <para>
 Aucun. Le programme ne fait rien.
 </para>
</refsect1>
<refsect1>
 <title>AUTEUR</title>
 <para>
 <author>
 <firstname>Foo</firstname>
 <othername role="mi">E</othername>
 <surname>Bar</surname>
 <contrib>Auteur original</contrib>
 </author>
 </para>
</refsect1>
</refentry>

Figure 12. Créer une page de manuel avec onsgmls, sgmlspl et 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 - Ne fait rien d'utile.
SYNOPSIS
 foo [ -f bar ]  [ -dn ]  [ fichier... ]
DESCRIPTION
 foo ne fait rien d'utile.
OPTIONS
 -f bar Prend bar comme fichier de contrôle à l'exécution.
 S'il s'agissait d'un véritable programme, il y
 aurait plus à dire ici sur ce qu'est le fichier
 bar et comment il serait utilisé.
 -dn    Fait quelque chose, où le nombre entier n spécifie
 combien de fois.
 fichier...
 Traite les fichiers dans l'ordre de leur apparition
 et envoie le résultat sur stdout.
UTILISATION
 foo -f foo.conf -d2 foodata.foo
MISE EN GARDE
 D'autres programmes appelés foo peuvent exister et faire
 réellement quelque chose !
BUGS
 Aucun. Le programme ne fait rien.
AUTEUR
 Foo E Bar (Auteur original)
[coupé - plusieurs lignes blanches que man ne montrera pas]
foo 1.0                     2001-01-01                          1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1

La page de manuel foo.1 est générée comme une page de la Section 1. La commande groff est utilisée pour donner un aperçu de son apparence finale.

Pour être installée, cette page de manuel doit être placée dans un répertoire man/man1, où le répertoire man/ est ajouté à la variable d'environnement $MANPATH. L'emplacement standard est /usr/local/man/man1. Les sections standard du système de pages de manuel sont numérotées de 1 à 9. Chacune est destinée à recevoir des documents d'une catégorie spécifique.

Tableau 1. Sections des pages de manuel

SectionCatégorie
man1Programmes et commandes
man2Appels système
man3Fonctions et routines des bibliothèques
man4Périphériques et fichiers spéciaux
man5Formats de fichier et conventions
man6Jeux
man7Divers
man8Administration système
man9Variables et fonctions internes du noyau

AstuceAstuce
 

Le fichier source d'une page de manuel, comme foo-ref.sgml, peut être converti dans tous les autres formats, exactement comme tout autre fichier DocBook. Aussi, l'utilisation des mêmes commandes présentées auparavant pour générer des fichiers au format HTML et papier, permet de sortir des pages de manuel en HTML et RTF, TEX, PDF, DVI et PS. Cela peut vous épargner un long travail de conversion !

Et maintenant, amusez-vous !