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�!