DocBook Install mini-HOWTO Robert Easter B
reaster@comptechnews.com
SylvainAmrani pour la traduction française
traduc@amrani.com.fr
 v1.7 2001-03-28 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. Introduction A propos de ce document La dernière version de ce mini-howto peut être trouvée sur : Reportez-vous à la section pour des informations sur les copyright, licence et décharge de responsabilité relatifs à ce document. Qu'est-ce que DocBook ? 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>. Aperçu rapide 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 "&eacute;" pour "é","&amp;" pour "&" et "&gt;" 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. Télécharger les paquetages Dans cette section, nous localiserons et téléchargerons les logiciels sur Internet. OpenJade 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 : La DTD SGML DocBook 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 : ISO8879 ENTITY SGML 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. 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 : DSSSL DocBook 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-lite 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 : Ce paquetage est optionnel, mais rend parfois les choses plus faciles. HTMLdoc 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 pour connaître les adresses de téléchargement. DocBook2X 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. Liens pour téléchargement direct Les fichiers ci-dessous sont donnés dans leur dernière version au moment de la rédaction de ce document : <ulink url="http://download.sourceforge.net/openjade/openjade-1.3.tar.gz">openjade-1.3.tar.gz</ulink> OpenJade, version 1.3. <ulink url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">docbk41.zip</ulink> DocBook SGML DTD, version 4.1. <ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz">iso8879-entities.tar.gz</ulink> 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. <ulink url="http://nwalsh.com/docbook/dsssl/db160.zip">db160.zip</ulink> & <ulink url="http://nwalsh.com/docbook/dsssl/db160d.zip">db160d.zip</ulink> Feuilles de style Modulaires DSSSL DocBook, version 1.60, et leur documentation. <ulink url="http://download.sourceforge.net/sgmltools-lite/sgmltools-lite-3.0.2.tar.gz">sgmltools-lite-3.0.2.tar.gz</ulink> Sgmltools-lite version 3.0.2. Je rappelle que c'est un paquetage optionnel. <ulink url="ftp://ftp.easysw.com/pub/htmldoc/1.8.9/">ftp://ftp.easysw.com/pub/htmldoc/1.8.9/</ulink> 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 <ulink url="http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz">http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz</ulink> SGMLS.pm 1.03ii sur CPAN. (sgmlspl) <ulink url="http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz">http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz</ulink> DocBook2X 0.6.0 (fournit docbook2man-spec.pl à utiliser avec sgmlspl vu précédemment) Installer les paquetages Installer OpenJade OpenJade 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 A l'installation, les bibliothèques sont placées dans /usr/local/openjade-1.3/lib, aussi, vous voudrez peut-être l'ajouter dans /etc/ld.so.conf et lancer ldconfig. Ajoutez /usr/local/openjade-1.3/bin à votre $PATH. jadetex & pdfjadetex 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 Next Solution Co., Ltd. et peut être trouvé sur : Les sections suivantes sont adaptées des instructions trouvées dans install.pdf : Créer hugelatex (si nécessaire) 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 Le répertoire web2c contient le fichier de configuration texmf.cnf. Faîtes une copie de sauvegarde de ce fichier : cp texmf.cnf texmf.cnf.orig. Editez le fichier en utilisant votre éditeur préféré, et ajoutez les lignes suivantes à la fin : % 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 Nous avons pris de l'avance en ajoutant des entrées pour jadetex et pdfjadetex, lesquels seront configurés ci-dessous. Vous pouvez jouer avec les paramètres mémoire précédents comme vous le voulez si vous rencontrez des problèmes avec ceux-ci. 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# jadetex & pdfjadetex 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 Le Makefile utilise hugelatex, aussi hugelatex doit avoir été configuré avant. Quand tex est lancé par hugelatex, jadetex ou pdfjadetex, il récupère le nom de la commande (donc le contexte) dans la variable argv[0]. Ensuite, il parcourt texmf.cnf et utilise les configurations contextuelles qu'il y trouve. Les fichiers de format (.fmt) placés dans /usr/share/texmf/web2c sont également chargés suivant le contexte. 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 SGML DocBook Décompresser la DTD SGML DocBook 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 Si vous installez doctools-1.2 de la distribution XFree86, cela installera d'anciennes versions de la DTD DocBook dans des sous-répertoires, comme les versions 2.4.1 et 3.0. 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/. Décompresser les entités ISO8879 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 Il doit y avoir dans le répertoire de chaque version de la DTD DocBook un fichier docbook.cat, ou un fichier catalog, ou bien les deux. Si les deux sont présents, ils sont probablement identiques. Si seul docbook.cat est présent, allez dans le répertoire et créez un lien symbolique : # Si nécessaire... cd /usr/local/share/sgml/docbook/4.1 ln -s docbook.cat catalog Les DSSSL DocBook 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 C'est tout ce qu'il y a à faire pour installer les feuilles de style DSSSL, hormis la configuration de la variable d'environnement SGML_CATALOG_PATH que nous aborderons plus tard. N'oubliez pas de corriger les droits sur les fichiers installés et leurs groupes/propriétaires (qui sont souvent inappropriés). sgmltools-lite 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 Ceci installe le script python dans /usr/local/bin. Notez que sgmltools-lite utilise python, et est donc inutile si vous n'avez pas ce paquetage. 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. htmldoc binaires 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. sources 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. http://www.fltk.org/ 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. ldp_print 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 Jetez un oeil aux scripts au cas où il y aurait des lignes que vous devriez adapter. Peut-être qu'un jour le bogue d'htmldoc sera réparé, et que ce script ne sera plus nécessaire. DocBook2X et SGMLS.pm (sgmlspl) sgmlspl 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 sgmlspl sera copié dans /usr/local/bin. docbook2X (docbook2man-spec.pl) 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 docbook2man-spec.pl se trouvera dans le répertoire de l'archive, avec un fichier patch qui corrige quelques petites choses. Appliquer le patch reste optionnel mais est recommandé. patch docbook2man-spec.pl docbook2man-spec.pl.patch Vous verrez par la suite dans la comment utiliser sgmlspl et docbook2man-spec.pl pour générer des pages de manuel depuis un document DocBook <refentry>. $SGML_CATALOG_FILES 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 ###################################################################################### Sauvegardez votre profil, déconnectez-vous et revenez pour que les changements prennent effet. L'installation est terminée ! Dans la section suivante, nous testerons notre configuration et convertirons quelques fichiers DocBook. Utiliser DocBook Maintenant que tout est installé, il est temps de tester notre configuration, et de voir comment utiliser OpenJade et les autres outils.
Exemple de fichier SGML DocBook - test.sgml <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> <article lang="fr"> <articleinfo> <title>Ceci est un test</title> <author> <firstname>John</firstname> <surname>Doe</surname> <othername role="mi">L</othername> <affiliation> <address> <email>j.doe@jdoe dot com</email> </address> </affiliation> </author> <revhistory> <revision> <revnumber>v1.0</revnumber> <date>2000-12-30</date> <authorinitials>jld</authorinitials> </revision> </revhistory> <abstract> <para> Ceci est un document DocBook de test. </para> </abstract> </articleinfo> <sect1 id="test1"> <title>Test 1</title> <para> Test section 1. </para> <sect2> <title>Test 1.1</title> <para> Test section 1.1 </para> </sect2> <sect2> <title>Test 1.2</title> <para> <screen> -- Test section 1.2 openjade -t sgml -d $DSLFILE test.sgml </screen> </para> </sect2> </sect1> <sect1 id="test2"> <title>Test 2</title> <para> Test section 2. </para> <sect2> <title>Test 2.1</title> <para> Test section 2.1 </para> </sect2> <sect2> <title>Test 2.2</title> <para> Test section 2.2 </para> </sect2> </sect1> </article>
Pour un guide sur DocBook et une référence sur les balises DocBook, voyez : DocBook: The Definitive Guide http://www.docbook.org/tdg/html/docbook.html Générer du HTML docbook.dsl
Création de documents HTML avec docbook.dsl bash$ ls -l total 4 -rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml bash$ echo $SGML_SHARE /usr/local/share/sgml bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml [Coupé - "DTDDECL catalog entries are not supported" - Message répété] bash$ ls -l total 12 -rw-r--r-- 1 reaster users 1885 Dec 31 17:34 t1.htm -rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml -rw-r--r-- 1 reaster users 1544 Dec 31 17:34 x27.htm bash$
Les messages d'avertissement concernant DTDDECL peuvent être ignorés. Ils peuvent être légèrement gênants, mais ils sont normaux lorsqu'on utilise Jade. Les autres messages d'avertissement et d'erreur doivent être surveillés, et indiquent souvent des erreurs de syntaxe qui doivent être corrigées. Deux fichiers htm sont créés. Un pour chaque <SECT1>. Les noms des fichiers ne sont pas très informatifs. La première section apparaît sur la même page que les informations sur l'article. C'est le résultat de l'utilisation de la feuille de style de base qui est donnée avec les Modular DocBook Stylesheets, docbook.dsl. Les feuilles de style peuvent être personnalisées pour améliorer ces comportements. Si vous avez téléchargé le fichier ldp.dsl du Projet de Documentation Linux, et l'avez installé comme indiqué à la , alors vous avez déjà un style personnalisé disponible. ldp.dsl
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 , 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 . L'option OpenJade spécifie le type sortie. L'option est le chemin d'accès à la feuille de style à utiliser. Dans l'exemple précédent, le type de sortie spécifié est , 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, 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 doit spécifier un fichier et non un répertoire. 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 Générer du DVI et du PS
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.
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$
Utiliser htmldoc pour générer un fichier Postscript (PS) bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps - bash$ ls -l -rw-r--r-- 1 reaster users 9050 Jan 1 00:44 test-htmldoc.ps -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$
Si le fichier PS n'offre pas le résultat attendu, cela est dû à des bugs dans htmldoc. Examinez le script ldp_print si vous voulez l'utiliser pour faire du poscript. Générer du PDF
Utiliser pdfjadetex pour générer un fichier PDF (<emphasis>Portable Document Format</emphasis>) bash$ ls -l -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log -rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps -rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex bash$ pdfjadetex test.tex This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1) (test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg] JadeTeX 1999/06/29: 2.7 (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd) (/usr/share/texmf/tex/jadetex/isoents.tex) Elements will be labelled Jade begin document sequence at 19 (test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd) (/usr/share/texmf/tex/latex/base/ts1cmr.fd) (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd) (/usr/share/texmf/tex/context/base/supp-pdf.tex (/usr/share/texmf/tex/context/base/supp-mis.tex loading : Context Support Macros / Missing ) loading : Context Support Macros / PDF ) (/usr/share/texmf/tex/latex/hyperref/nameref.sty) (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )<8r.enc> Output written on test.pdf (3 pages, 9912 bytes). Transcript written on test.log. bash$ ls -l total 128 -rw-r--r-- 1 reaster users 753 Dec 31 21:13 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 5075 Dec 31 21:13 test.log -rw-r--r-- 1 reaster users 9912 Dec 31 21:13 test.pdf -rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps -rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml -rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex bash$ bash$ pdfjadetex test.tex [coupé] bash$ pdfjadetex test.tex [coupé]
Pdfjadetex doit être lancé jusqu'à trois fois pour résoudre toutes les références internes comme les numéros de pages dans les tables des matières.
Utiliser htmldoc pour générer un fichier PDF (<emphasis>Portable Document Format</emphasis>) bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm bash$ ldp_print test-htmldoc.htm bash$ ls -l -rw-r--r-- 1 reaster users 9050 Jan 1 01:17 test-htmldoc.pdf -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$
Si l'option est activée dans le script ldp_print, un fichier PS sera également généré. 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.
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 :
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. 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 :
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>
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. 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 ! Légalité
Décharge de responsabilité 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.
La licence GNU Free Documentation License 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 pour trouver des liens sur plusieurs traductions françaises de cette licence, tout en sachant que seule la version originale fait foi.
GNU Free Documentation License 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.
PREAMBLE 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.
APPLICABILITY AND DEFINITIONS 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.
VERBATIM COPYING 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.
COPYING IN QUANTITY 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.
MODIFICATIONS 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.
COMBINING DOCUMENTS 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."
COLLECTIONS OF DOCUMENTS 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.
AGGREGATION WITH INDEPENDENT WORKS 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 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.
TERMINATION 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.
FUTURE REVISIONS OF THIS LICENSE 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.
How to use this License for your documents 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.