Sylvain Amrani - pour la traduction fran�aise
Historique des versions | ||
---|---|---|
Version v1.7 | 2001-03-28 | Revu par�: rbe |
DocBook-Install-mini-HOWTO est un guide pratique et d�taill� pour permettre aux novices d'installer rapidement DocBook et de g�n�rer des fichiers SGML en HTML, PS et PDF sur un syst�me GNU/Linux (mais cela peut �tre similaire sur d'autres syst�mes). La mise en place de DocBook, qui n�cessite des fichiers de plusieurs paquetages distribu�s s�par�ment, peut sembler confuse aux d�butants.
La derni�re version de ce mini-howto peut �tre trouv�e sur :
http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/
Reportez-vous � la section Annexe A pour des informations sur les copyright, licence et d�charge de responsabilit� relatifs � ce document.
DocBook est une D�finition de Type de Documents (DTD - Document Type Definition) en Langage Standard de Balisage G�n�ralis� (SGML - Standard Generalized Markup Language), qui d�finit un ensemble de balises pour des documents litt�raux, et qui fonctionne comme le langage HTML utilis� habituellement sur le Web.
DocBook est destin� � la r�daction de livres et
d'articles. Comme tel, il fournit des balises (appel�es
encore marqueurs) pens�es sp�cifiquement pour d�crire des livres
et des articles. Par exemple, les balises DocBook
<book>
et
<article>
sont utilis�es pour cr�er
les livres et les articles. Dans ces documents, des balises
<chapter>
,
<sect1>
, et
<para>
seront utilis�es. Les fichiers
SGML DocBook sont stock�s dans des fichiers texte avec un
suffixe .sgml ou .gml
Lors de son traitement, un unique fichier SGML DocBook peut produire des fichiers HTML, PDF, PS, TXT ou d'autres formats de publication papier ou �lectronique. Le traitement est r�gi par des feuilles de style (stylesheets) qui peuvent g�n�rer automatiquement une table des mati�res, la num�rotation des pages, la num�rotation des chapitres et des sections, et bien d'autres possibilit�s.
DocBook est destin� �galement � l'�criture de pages de manuel
unix, en utilisant la balise
<refentry>
.
Voici une description br�ve des paquetages que nous utiliserons dans les prochaines sections :
OpenJade. OpenJade est un processeur DSSSL (Document Style Semantics and Specification Language - Langage de sp�cification et S�mantique de pr�sentation de document) pour documents SGML (Standard Generalized Markup Language - Langage Standard de Balisage G�n�ralis�). Il transforme des fichiers source SGML DocBook en fichiers HTML, TEX, RTF, TXT et autres formats. OpenJade est l'outil essentiel pour convertir un fichier DocBook dans d'autres formats. Le format de sortie TEX est utilis� surtout comme format interm�diaire pour obtenir des fichiers DVI, PDF et PS par des macros TeX et des convertisseurs DVI.
La DTD SGML DocBook. Les fichiers DTD (D�finition de Type de Document) sont des fichiers SGML qui d�finissent le langage DocBook. L'ensemble des balises valides et leurs r�gles d'utilisation y sont d�finis. OpenJade a besoin d'acc�der aux fichiers DTD des documents qu'il doit traiter.
ISO8879 ENTITY SGML. Les entit�s d�finissent la repr�sentation des caract�res sp�ciaux qui n'ont pas de touche clavier associ�e ou qui ont une signification particuli�re en SGML. Des exemples connus en HTML sont "é" pour "�","&" pour "&" et ">" pour ">".
DSSSL DocBook. Les fichiers DSSSL (Document Style Semantics and Specification Language) pour une DTD particuli�re, en l'occurrence DocBook, sp�cifient comment convertir le document DocBook en fichiers au format HTML, RTF, TEX, etc.
SgmlTools-lite. SgmlTools est une interface pour lancer OpenJade et les macros TeX jadetex et pdfjadetex qui en font partie. La conversion d'un fichier DocBook en format PS ou PDF est un traitement en deux ou trois �tapes. OpenJade cr�e un fichier TEX qu'utilise jadetex pour produire un DVI, et pdfjadetex pour produire un document PDF. Un fichier PS s'obtient en transformant le fichier DVI avec dvips. Les scripts SgmlTools fournissent une commande unique pour ces t�ches.
HTMLdoc. HTMLdoc est un programme libre pour convertir des fichiers HTML en documents PDF ou PS.
SGMLSpm and docbook2X. Ces deux outils sont � utiliser pour g�n�rer des pages de manuel. SGMLSpm est une biblioth�que modulaire Perl5 pour traiter les r�sultats du travail de onsgmls, un programme inclus dans OpenJade. SGMLSpm comprend une application appel�e sgmlspl permettant d'utiliser la biblioth�que SGMLSpm. Sgmlspl n�cessite des fichiers de sp�cification, disponibles sur de nombreux sites internet, pour chaque type de document � transformer. DocBook2X est un paquetage qui fournit des fichiers de sp�cification pour transformer des fichiers DocBook en pages de manuel.
Dans cette section, nous localiserons et t�l�chargerons les logiciels sur Internet.
OpenJade est un logiciel aux sources libres (open-source), activement maintenu, bas� sur le paquetage Jade de James Clark. T�l�chargez la derni�re version stable (1.3�?) sur�:
http://openjade.sourceforge.net/
OpenJade inclut �galement le paquetage OpenSP et les macros TeX jadetex et pdfjadetex pour convertir les fichiers en DVI et en PDF. Les programmes suivants sont install�s par ce paquetage�:
openjade
onsgmls
osgmlnorm
ospam
ospent
osx
Afin de pouvoir utiliser jadetex et pdfjadetex pour cr�er du DVI, PS et PDF, vous devez avoir une installation de TeX qui fonctionne. Si vous n'avez pas TeX, cherchez dans votre distribution Linux le paquetage � installer. Sinon, vous pouvez t�l�charger la distribution TeX teTeX depuis :
Les DTD DocBook SGML et XML sont maintenues par un comit� technique � Oasis-Open.ORG. T�l�chargez la derni�re version (et les versions anciennes dont vous pourriez avoir besoin) de DocBook SGML sur :
Les entit�s d�finissent la repr�sentation de caract�res sp�ciaux ou de symboles qui ne peuvent �tre saisis au clavier, y compris les symboles math�matiques et les entit�s qui peuvent vous �tre famili�res avec le HTML. Ces fichiers d'entit�s doivent �tre install�s pour avoir une configuration correcte.
Ressources � OASIS :
ISOEnts.zip n'a besoin que d'�tre d�compact� dans le r�pertoire de la DTD DocBook et de rien d'autre, mais les fichiers dans isoENT-tar.gz restent n�cessaires. Les fichiers de isoENT-tar.gz doivent donc �galement �tre d�compact�s dans le r�pertoire de la DTD DocBook (cf. Section 3 pour les d�tails). Mais ces fichiers poss�dent un suffixe ".ent" qui doit �tre renomm� en ".gml". Vous pouvez le faire manuellement, ou bien vous pouvez t�l�charger et utiliser le fichier ci-dessous, pr�par� par l'auteur, qui contient les fichiers des deux archives ISOEnts.zip et isoENT-tar.gz :
http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz
Des fichiers DSSSL (Document Style Semantics and Specification Language) pour la DTD DocBook (SGML/XML) sont fournis par Norman Walsh. Ces fichiers, appel�s Modular DocBook Stylesheets (feuilles de style modulaires pour DocBook), disent � OpenJade comment convertir votre fichier SGML DocBook en un autre format. Un fichier dsl d�crit par exemple la correspondance entre une balise d'une DTD et une autre balise d'une autre DTD, ou d'autres conversions programm�es, �crites dans un langage appel� Core Expression Language, qui est d�riv� du Scheme. Le paquetage DSSSL DocBook et sa documentation peuvent �tre t�l�charg�s sur le site de Norman Walsh�:
http://nwalsh.com/docbook/dsssl/
NdT : Norman Walsh a depuis ouvert un projet sur SourceForge, qui doit maintenant �tre consid�r� comme le principal lieu de t�l�chargement�:
Le Projet de Documentation Linux a cr�� un fichier de personnalisation des feuilles de style qui active des options de pr�sentation int�ressantes. Il peut �tre t�l�charg� sur�:
Sgmltools est une interface pour OpenJade, jadetex, pdfjadetex, dvips, et d'autres programmes. Sgmltools offre une commande unique pour g�n�rer tous les formats possibles avec ces outils. La derni�re version, v1.3 � l'heure o� nous �crivons ces lignes, peut �tre t�l�charg�e sur�:
http://sourceforge.net/projects/sgmltools-lite/
Ce paquetage est optionnel, mais rend parfois les choses plus faciles.
HTMLdoc est un programme libre pour convertir des sites Web en documents au format PDF (Portable Document Format) ou PS (Postscript). Concernant le format PDF, il cr�e une arborescence de signets correspondant aux sections, rendant la navigation plus facile. HTMLdoc et pdfjadetex cr�ent tous deux des documents PDF, mais avec des rendus l�g�rement diff�rents. Comparez les deux pour voir lequel produit le meilleur r�sultat pour un fichier DocBook particulier. Reportez-vous � la Section 2.8 pour conna�tre les adresses de t�l�chargement.
DocBook2X n�cessite Perl5 et le module Perl SGMLS.pm, disponible sur le CPAN. SGMLS.pm fournit des biblioth�ques et un programme appel� sgmlspl qui convertissent les fichiers DocBook en d'autres formats en utilisant des fichiers de sp�cification. Ces fichiers de sp�cification sont des scripts Perl qui donnent le m�canisme de traduction dans un format particulier.
Les fichiers ci-dessous sont donn�s dans leur derni�re version au moment de la r�daction de ce document�:
openjade-1.3.tar.gz . OpenJade, version 1.3.
docbk41.zip . DocBook SGML DTD, version 4.1.
iso8879-entities.tar.gz . Entit�s ISO 8879 SGML. Cet unique fichier est plus pratique � utiliser. Vous pouvez sinon t�l�charger les deux autres fichiers et changer les suffixes des fichiers en .gml.
db160.zip & db160d.zip . Feuilles de style Modulaires DSSSL DocBook, version 1.60, et leur documentation.
sgmltools-lite-3.0.2.tar.gz . Sgmltools-lite version 3.0.2. Je rappelle que c'est un paquetage optionnel.
ftp://ftp.easysw.com/pub/htmldoc/1.8.9/ . HTMLdod 1.8.6. Des versions compil�es sont disponibles avec le code source. Choisissez en fonction de votre plate-forme. Les versions compil�es sont recommand�es. Pour obtenir une version compil�e, vous pouvez la t�l�charger directement par FTP sur les liens ci-dessous. Si le choix n'est pas �vident, consultez le site Internet de EasySw�: http://www.easysw.com/software.html
http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz . SGMLS.pm 1.03ii sur CPAN. (sgmlspl)
http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz . DocBook2X 0.6.0 (fournit docbook2man-spec.pl � utiliser avec sgmlspl vu pr�c�demment)
Voici ce qui est n�cessaire de faire, mais pensez � lire les fichiers fournis avec OpenJade pour voir s'il n'y a pas des param�tres que vous pourriez personnaliser pour votre plate-forme�:
cd /usr/local tar -xvzf ~/openjade-1.3.tar.gz cd openjade-1.3 ./configure --prefix=/usr/local/openjade-1.3 make make install # Une fois install�s, les fichiers objets etc. # peuvent �tre supprim�s make clean |
Comme mentionn�, jadetex et pdfjadetex sont des macros TeX fournies avec OpenJade. Elles sont plac�es dans /usr/local/openjade-3.1/dsssl. Un guide pratique sur l'installation de ces macros a �t� �crit par Frank Atanassow Christoph et peut �tre trouv� sur�:
ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf
http://www.comptechnews.com/~reaster/installjadetex.pdf
Les sections suivantes sont adapt�es des instructions trouv�es dans install.pdf�:
Les macros TeX jadetex et pdfjadetex n�cessitent plus de m�moire qu'une utilisation habituelle de TeX. Souvent, la configuration par d�faut des limites d'utilisation m�moire de TeX n'est pas adapt�e. Le fichier de configuration de TeX, texmf.cnf, peut �tre modifi� et les valeurs des variables correspondant � la limite d'utilisation de la m�moire par TeX peuvent �tre augment�es. Cependant, plut�t que de simplement �diter le fichier texmf.cnf pour permettre � TeX d'utiliser plus de m�moire en toutes circonstances, un contexte TeX sp�cifique peut �tre cr��, appel� hugelatex. Si hugelatex est d�j� configur� sur votre syst�me, vous pouvez sauter cette section (which hugelatex vous donne l'emplacement de la macro si elle est configur�e).
V�rifiez qu'une version fonctionnelle de TeX est install�e et trouvez son emplacement�:
bash$ which tex /usr/share/texmf/bin/tex bash$ kpsewhich -expand-var='$TEXMFMAIN' /usr/share/texmf bash$ |
L'utilisation de which devrait trouver l'emplacement du programme TeX. Si TeX n'est pas trouv�, vous aurez peut-�tre � installer teTeX puis � revenir ici. kpsewhich est un utilitaire fourni avec teTeX qui donne, si tout va bien, le r�pertoire TeX principal.
Maintenant que le r�pertoire de texmf est connu, l'installation peut d�buter�:
cd /usr/share/texmf cd tex/latex cp -r config config-temp cd config-temp tex -ini -progname=hugelatex latex.ini mv latex.fmt hugelatex.fmt mv hugelatex.fmt /usr/share/texmf/web2c cd .. rm -r config-temp cd /usr/share/texmf/bin ln -s tex hugelatex cd /usr/share/texmf/web2c |
% hugelatex settings extra_mem_top.hugelatex = 8000000 extra_mem_bot.hugelatex = 8000000 hash_extra.hugelatex = 15000 pool_size.hugelatex = 5000000 string_vacancies.hugelatex = 45000 max_strings.hugelatex = 55000 pool_free.hugelatex = 47500 nest_size.hugelatex = 500 param_size.hugelatex = 1500 save_size.hugelatex = 5000 stack_size.hugelatex = 15000 % jadetex extra_mem_top.jadetex = 8000000 extra_mem_bot.jadetex = 8000000 hash_extra.jadetex = 20000 pool_size.jadetex = 5000000 string_vacancies.jadetex = 45000 max_strings.jadetex = 55000 pool_free.jadetex = 47500 nest_size.jadetex = 500 param_size.jadetex = 1500 save_size.jadetex = 5000 stack_size.jadetex = 15000 % pdfjadetex extra_mem_top.pdfjadetex = 8000000 extra_mem_bot.pdfjadetex = 8000000 hash_extra.pdfjadetex = 20000 pool_size.pdfjadetex = 5000000 string_vacancies.pdfjadetex = 45000 max_strings.pdfjadetex = 55000 pool_free.pdfjadetex = 47500 nest_size.pdfjadetex = 500 param_size.pdfjadetex = 1500 save_size.pdfjadetex = 5000 stack_size.pdfjadetex = 15000 |
Notez que la mise en place de hugelatex n'est prise en compte qu'apr�s avoir lanc� le programme texhash
root# texhash texhash: Updating /usr/share/texmf/ls-R... texhash: Updating /var/cache/fonts/ls-R... texhash: Done. root# |
La configuration de jadetex et de pdfjadetex est similaire � celle de hugelatex.
cd /usr/local/openjade-1.3/dsssl make -f Makefile.jadetex install # make cr�e et installe les fichiers .fmt # dans /usr/share/texmf/web2c # Cr�ation des liens symboliques... cd /usr/share/texmf/bin ln -s tex jadetex ln -s pdftex pdfjadetex # Enfin, lancement de texhash. root# texhash |
Jadetex utilise un fichier tex g�n�r� par OpenJade pour cr�er un DVI. De m�me pdfjadetex utilise le fichier tex g�n�r� par OpenJade et cr�e un PDF. Le programme dvips utilise le fichier DVI et cr�e un fichier postscript (PS).
La DTD DocBook n'est constitu�e que de fichiers texte SGML, aussi il n'y a rien � compiler. D�compressez uniquement ces fichiers dans un endroit choisi.
# DocBook DTD V4.1 plac� dans # /usr/local/share/sgml/docbook/4.1 cd /usr/local/share mkdir sgml; cd sgml mkdir docbook; cd docbook mkdir 4.1; cd 4.1 unzip -a ~/docbk41.zip |
Il y a des diff�rences entre les diverses versions de la DTD DocBook. Les fichiers xxxissues.txt documentent ces questions. Des balises ont �t� ajout�es, retir�es ou renomm�es entre les versions.
Si vous devez utiliser la DTD DocBook dans sa version 3.1, elle est disponible au m�me endroit o� la version 4.1 se t�l�charge. La version 3.1 est beaucoup utilis�e, aussi c'est une bonne id�e de la t�l�charger et de la placer dans un sous-r�pertoire 3.1/.
Allez dans le r�pertoire de chaque version install�e de la DTD DocBook, et d�compressez-y le fichier iso8879-entities.tar.gz�:
cd /usr/local/share/sgml/docbook/4.1 tar -xvzf ~/iso8879-entities.tar.gz |
# Si n�cessaire... cd /usr/local/share/sgml/docbook/4.1 ln -s docbook.cat catalog |
L'installation des feuilles de style DSSSL DocBook, qui sont compatibles avec toutes les versions de DocBook, ne n�cessitent que de les d�compresser dans un r�pertoire appropri�:
cd /usr/local/share/sgml mkdir dsssl; cd dsssl unzip -a ~/db160.zip # Si vous avez t�l�charg� ldp.dsl le fichier de personnalisation # des feuilles de style, copiez-le dans... cd docbook cp ~/ldp.dsl html cp ~/ldp.dsl print # ces deux r�pertoires |
Si vous le voulez, vous pouvez installer sgmltools-lite, bien que ce soit optionnel. Son installation est standard�:
cd /usr/src tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz cd sgmltools-lite-3.0.2 ./configure make install |
Pour que le script sgmltools fonctionne il vous faudra l'�diter pour corriger le chemin d'acc�s � OpenJade : vi `which sgmltools`. Consultez sa documentation pour en savoir plus.
Pr�f�rez le t�l�chargement de la version compil�e de htmldoc pour votre plate-forme. L'installation est on ne peut plus simple�: d�compressez le paquetage et lancez le setup. Lisez la documentation fournie pour plus d'information.
Si vous avez t�l�charg� les sources, vous aurez �galement besoin de la biblioth�que Fast Light Tool Kit, pour r�ussir l'�dition de liens.
L'installation est de la famille autoconf. Lancez simplement le script ./configure, puis make et make install. Si tout va bien, le programme sera install� dans /usr/bin.
Le programme htmldoc a quelques soucis pour traiter les fichiers HTML d'OpenJade. Par exemple, les puces des listes ne sont pas rendues correctement, et les zones ombr�es ne le sont pas toujours.
Pour contourner ce probl�me, un script perl (ldp_print) est disponible sur LinuxDoc.org. Le script traite un fichier HTML unique cr�� par OpenJade et lance htmldoc dessus, pour produire des fichiers aux formats PDF et PS corrects.
![]() | Conseil |
---|---|
Adoptez-le�! |
tar -xvzf ldp_print.tar.gz cd ldp_print # Copiez la biblioth�que dans le chemin # de recherche de Perl. cp fix_print_html.lib /usr/lib/perl5/site_perl cp ldp_print /usr/local/bin |
Pour que les fichiers de sp�cifications de DocBook2X soient utiles, le module SGMLS.pm pour Perl5 doit �tre install�, en supposant que Perl5 est d�j� install�. L'installation de ce module n'est pas autant automatis�e que le sont les installations de la plupart des modules Perl. Il utilise un fichier Makefile qui doit �tre �dit� avant de lancer make.
cd /usr/src tar -xvzf ~/SGMLSpm-1.03ii.tar.gz cd SGMLSpm # Editez Makefile vi Makefile # Adaptez la section du Makefile relative # aux options utilisateurs afin qu'elles # refl�tent votre syst�me. # Exemple : # PERL = /usr/bin/perl # BINDIR = /usr/local/bin # PERL5DIR = /usr/lib/perl5/site_perl # MODULEDIR = ${PERL5DIR}/SGMLS # SPECDIR = ${PERL5DIR} # HTMLDIR= /usr/local/apache/htdocs make install |
DocBook2X ne contient aucun programme � compiler ou installer, mais des scripts que vous voudrez certainement examiner, aussi, tout ce qu'il y a � faire est de d�compresser le paquetage quelque part�:
cd /usr/local/share/sgml tar -xvzf ~/docbook2X-0.6.0.tar.gz cd docbook2X |
patch docbook2man-spec.pl docbook2man-spec.pl.patch |
<refentry>
.
La variable d'environnement SGML_CATALOG_FILES est utilis�e par OpenJade (ainsi que d'autres logiciels SGML) pour localiser les DTD et les feuilles de style DSSSL. Les logiciels SGML ne peuvent pas travailler sans trouver ces fichiers, lesquels ont �t� plac�s dans de nombreux r�pertoires. Au point o� nous en sommes de notre configuration, voici comment SGML_CATALOG_FILES peut �tre positionn�e dans /etc/profile�:
###################################################################################### # SGML DocBook - openjade sgmltools-lite JADE_HOME=/usr/local/openjade-1.3 SGML_SHARE=/usr/local/share/sgml PATH=$PATH:$JADE_HOME/bin # feuilles de style DSSSL # Modular DocBook Stylesheets de Norman Walsh SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog # Feuilles de style OpenJade SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog # Feuilles de style sgmltools-lite SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat # DTD DocBook # D'OASIS-Open.org SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog # Ces anciennes versions ont �t� install�es par # doctools-1.2 d'XFree86.org SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog # Catalogues sgmltools-lite pour LinuxDoc SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES ###################################################################################### |
L'installation est termin�e�! Dans la section suivante, nous testerons notre configuration et convertirons quelques fichiers 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
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.
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.
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 |
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$ |
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$ |
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.
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�!
Copyright (c) 2001 Robert B. Easter
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Permission vous est donn�e de copier, distribuer et/ou modifier ce document selon les termes de la Licence GNU Free Documentation License, Version 1.1 ou ult�rieure publi�e par la Free Software Foundation�; sans section inalt�rable, sans texte inalt�rable de premi�re page de couverture, sans texte inalt�rable de derni�re page de couverture. Une copie de cette licence est incluse dans la Section A.3.
Aucune responsabilit� pour le contenu de ce document ne peut �tre accept�e. Utilisez les concepts, exemples et autre contenu � vos propres risques.
Tous les copyrights sont d�tenus par leurs propri�taires respectifs, sauf mention contraire expresse. L'utilisation d'un terme dans ce document ne doit pas �tre vue comme affectant la valeur d'une marque de fabrique ou de service.
La mention d'un produit particulier ou d'une marque ne doit pas �tre consid�r�e comme un acte d'approbation.
![]() | Avertissement |
---|---|
NdT - Pour des raisons de droit, la seule licence applicable concernant ce document est la licence GNU Free Documentation License, dans sa version originale en langue anglaise, retranscrite ci-apr�s. Le lecteur francophone pourra, � titre d'information, se reporter sur le site de la copyleft de la Free Software Foundation, et en particulier sur la page http://www.gnu.org/copyleft/copyleft.html#translationsGFDL pour trouver des liens sur plusieurs traductions fran�aises de cette licence, tout en sachant que seule la version originale fait foi. |
Version 1.1, March 2000
Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.