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> |
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$ |
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$ |
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é] |
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$ |
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
| Section | Catégorie |
|---|---|
| man1 | Programmes et commandes |
| man2 | Appels système |
| man3 | Fonctions et routines des bibliothèques |
| man4 | Périphériques et fichiers spéciaux |
| man5 | Formats de fichier et conventions |
| man6 | Jeux |
| man7 | Divers |
| man8 | Administration système |
| man9 | Variables et fonctions internes du noyau |
 | Astuce |
|---|---|
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 !