Écrire de la documentation en utilisant DocBook

Please download to get full document.

View again

of 35
33 views
PDF
All materials on our website are shared by users. If you have any questions about copyright issues, please report us to resolve them. We are always happy to assist you.
Document Description
Écrire de la documentation en utilisant DocBook Un cours accéléré David Rugge Mark Galassi Éric Bischoff Marc Blanc
Document Share
Documents Related
Document Transcript
Écrire de la documentation en utilisant DocBook Un cours accéléré David Rugge Mark Galassi Éric Bischoff Marc Blanc Écrire de la documentation en utilisant DocBook: Un cours accéléré par David Rugge, Mark Galassi, Éric Bischoff, et Marc Blanc Copyright David Rugge, Mark Galassi, Éric Bischoff Ce document est un premier didacticiel sur la façon d écrire de la documentation en DocBook. 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 . Table des matières 1. Introduction À propos de ce document Pourquoi DocBook? Votre vision du monde Balisage fondé sur le contenu Les premiers pas Présentation des outils L ancienne méthode : les DocBook-Tools La nouvelle méthode : XSLTProc et FOP Mon premier fichier DocBook Introduction aux feuilles de style Notions de base Anatomie d une balise DocBook Structure d un fichier DocBook La déclaration de type de document (DTD) Utiliser des entités pour du texte partagé Utiliser les entités pour inclure d autres fichiers Identification des fichiers avec les ID publics formels Utiliser des sections marquées pour manipuler du contenu conditionnel Méta-informations Listes La simplelist La itemizedlist La orderedlist La variablelist La segmentedlist qandaset Procédures Les tableaux Les graphiques Les liens Description de l interface d une application Exemples Éléments d interface GUI Éléments de ligne de commande Description d une API Diverses balises utiles Balises de désignation Balises de mise en forme Avertissements, conseils et notes Où aller ensuite? Ressources sur DocBook...41 A. Licence...42 A.1. Free Documentation Licence...42 B. Mode PSGML de Emacs...50 Glossaire...52 iii Liste des tableaux 7-1. Kilométrage de la souris...28 iv Chapitre 1. Introduction 1.1. À propos de ce document Ce document se présente comme une introduction sur la façon d utiliser toute la puissance et l efficacité de DocBook. Il essaie de vous introduire en cette matière dans les délais les plus courts, c est pourquoi il se nomme Cours éclair de DocBook . Même si vous n avez jamais utilisé DocBook ou un autre langage de balisage (comme LinuxDoc) auparavant, vous devriez être capable de devenir compétant simplement en lisant ce guide et en utilisant la version en ligne (http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html) ou papier (http://www.oreilly.com/catalog/docbook/index.html) du [DocBook - Le Guide Définitif] publiée par O Reilly & Associates. Note : Notez que ce didacticiel est destiné à être utilisé avec, et pas à la place de, la Référence DocBook. Il existe un certain nombre de cas où il est plus facile de se reporter à la Référence plutôt que d essayer de refaire ce qui à déja été présenté. Utilisez ce guide pour comprendre ce qu est DocBook et comment utiliser les balises. Ce didacticiel vous présente suffisamment de DocBook pour écrire une documentation de base. Vous apprendrez : Ce qu est DocBook Comment obtenir les outils DocBook et les faire fonctionner Le format des balises DocBook Comment structurer vos documents proprement Comment utiliser les listes et les tables pour organiser vos données Comment décrire les éléments GUI et les commandes Unix Comment intégrer des graphiques à votre documentation Comment insérer des URL et créer des références croisées En annexe, vous pouvez trouver une courte description du mode psgml de Emacs. Ce didacticiel provient de la fusion de trois documents : le Introduction to DocBook de Mark Galassi le KDE crash-course to DocBook de David Rugge des parties du didacticiel de Eric Bischoff sur DocBook 1 Chapitre 1. Introduction Certaines parties de ce document sont empruntées au DocBook 3.0 Reference de Eve Maler de ArborText, Inc et Terry Allen de Fujitsu Software Corporation. Les parties de ce document empruntées sont Copyright 1992, 1993, 1994, 1995, 1996, 1997 par HaL Computer Systems, Inc., O Reilly & Associates, Inc., Fujitsu Software Corporation et ArborText, Inc Pourquoi DocBook? Le format DocBook a été développé par le consortium OASIS spécifiquement pour la documentation technique. Il fournit un riche ensemble de balises pour décrire le contenu de votre document. Ici, voyons certains points-clé pour vous aider à comprendre ce qu est DocBook : Docbook est un langage de balises Il est très similaire au HTML. Les balises permettent la structuration de votre document et s entremêle avec le texte. Ce point particulier en fait une révolution avec respect de la traduction de la documentation, car la phase DTP (rendant le texte agréable) est faite une fois pour toute indirectement en balisant le texte original. Les traducteurs ont seulement à traduire entre les balises et en pressant une simple touche la sortie traduite est générée. Il est conçu pour la documentation technique DocBook est parfaitement adapté pour la documentation des pièces détachées de moteurs de voitures. Cependant, il est fortement prédisposé pour la documentation des programmes informatiques. Il est maintenu par un consortium indépendant Le consortium OASIS (http://www.oasis-open.org) est en charge de la maintenance du standard développé par le Comité Technique DocBook. C est une garantie d indépendance vis-à-vis des logiciels propriétaires. Des acteurs majeurs de l industrie comme Boeing ou IBM sont membres de OASIS. Voyez la liste des membres (http://www.oasis-open.org/html/members.htm) pour plus d information. Techniquement, DocBook est une DTD SGML ou XML Ceci veut dire que l on peut tirer profit de nombreux outils SGML et XML. Alors que DocBook comme implémentation XML est assez récent, il a une longue histoire en tant qu implémentation SGML. DocBook n est pas un langage de présentation DocBook n indique pas spécifiquement à quoi le document final ressemblera. Ceci permet à l auteur de se concentrer sur l organisation du document. La présentation est gérée par les feuilles de style. 2 Chapitre 1. Introduction Ceci assure à vos documents une apparence logique. DocBook est personnalisable Il est facile de personnaliser la DTD en fonction de vos besoins. Mais ceci doit être fait dans le respect des conventions SGML/XML. Si DocBook est utilisé concurremment avec les feuilles de style de Norman Walsh, il est également possible de personnaliser un fichier DocBook pour l impression ou la mise en ligne. DocBook est intelligible Le grand nombre de balises défini dans DocBook garantit qu il peut s accommoder de situations très variées. Ceci fait qu il est un peu difficile à apprendre, mais dans la plupart des cas vous n aurez à utiliser qu un nombre limité de balises. DocBook utilise des balises longues et compréhensibles Un exemple des ces balises est itemizedlist ou literallayout . Ceci rend un texte DocBook plus facile à lire qu une source HTML. Désavantage, il peut aussi devenir un peu fastidieux de taper ces longues balises, mais certains modes spécialisés (comme le mode psgml de Emacs) peuvent vous y aider. DocBook n assure pas la compatibilité ascendante entre les révisions majeures Alors que ceci pourrait sembler être un inconvénient, en fait ce ne l est pas, car ça assure une présentation propre même si de mauvais choix ont été faits précédemment par le Comité DocBook de OASIS et parce que les documents écrits avec différentes DTD peuvent coexister sur un même ordinateur. Certains de ces points-clé seront vus plus en détail dans les prochaines sections Votre vision du monde La plupart des personnes qui font de la composition de texte utilisent des systèmes WYSIWYG dans lesquels ils tapent des balises d instruction indiquant au processeur la position du texte dans la page (comme TeX et troff). Ces approches souffrent de quelques sérieux problèmes. Le plus important est la longévité du document : l information (ce que vous tapez) et qui doit perdurer s entremêle avec l information qui sera dépassée (l information processeur). Un autre gros problème avec cette approche ancienne est l absence de structure: le balisage n affecte pas le contenu, mais plutôt la mise en page. Si vous êtes intéressé pour l indexation de documents écrits en TeX. Il est facile d indexer toutes les occurences d un texte en gras, mais ça n intéresse pas tout le monde! À l inverse, il sera plus facile d indexer tous les noms de fonction dans une API. 3 Chapitre 1. Introduction Avec l ancienne approche de mise en forme vous auriez besoin d un logiciel d intelligence artificielle qui comprenne le texte et vous dise aha! ceci doit être la définition d une fonction dans l API Balisage fondé sur le contenu Comment baliser vos documents de façon optimale pour que l information puisse en être extraite et indexée? L approche de DocBook est de fournir un ensemble très riche de balises de délimitation qui toutes sont en relation avec la structure et la nature du contenu du document. Pour vous donner des exemples de balises qui peuvent vous aider à générer des index automatiques : attribution et command . Si vous avez un grosse documentation (par exemple, tout les logiciels et matériels Sun sont documentés avec DocBook) vous pouvez faire une recherche facilement dans les documents qui traitent d une commande appelée mount ou une citation attribuée à Ken Thompson. Avec une recherche structurée vous pourriez seulement trouver les occurrences de mount quand c est un nom de commande et de Thompson quand il est l auteur de la citation. Maintenant imaginez ce qui se passerait si le Web tout entier utilisait un langage de balisage basé sur le contenu au lieu du HTML : un moteur de recherche vous donnerait l information dont vous avez besoin sans toutes les références supplémentaires nécessaires pour utiliser ces termes. Une recherche sur mount sur le Web ne trouvera pas dans la plupart des cas les références à la commande UNIX mount. Un riche langage de balises comme DocBook est une excellente idée à divers points de vue, mais il peut aussi être difficile à utiliser. DocBook possède des centaines de balises (à l opposé de quelques unes pour le HTML), ainsi l apprentissage est plus dur. C est vrai et le seul moyen pour y remédier est d écrire une documentation sur l utilisation de DocBook! D un autre côté, si vous êtes familier avec DocBook ça ne vous prendra pas trop de temps de taper les balises. Gardez à l esprit que la plupart du temps une personne n écrit pas mais se concentre sur la mise en forme de son document. Si vous utilisez DocBook vous passerez plus de temps à l écriture et moins à la mise en forme. 4 Chapitre 2. Les premiers pas 2.1. Présentation des outils Cette section décrit comment travailler avec DocBook sur les systèmes Unix-like comme Linux. Si malheureusement vous travaillez sur d autres systèmes, vous devrez assembler et configurer les outils nécessaires ou acheter une solution commerciale. La technologie concernant DocBook évolue. Dans le passé : DocBook a démarré comme une application SGML comme le HTML Les documents DocBook étaient convertis à l aide des feuilles de style DSSSL. La mise en page PDF était réalisée par le moteur de composition TeX. Maintenant, au contraire : DocBook suit la syntaxe XML, comme le fait le HTML. Il est converti dans d autres formats par les feuilles de style XSLT. La mise en page PDF étant réalisée par le moteur XSL-FO. Les outils utilisés pour générer des fichiers DocBook doivent suivre cette évolution. Nous présenterons successivement les outils DocBook (technologie SGML/DSSSL) et XSLTProc/FOP (technologie XML/XSL). Note : Il existe une autre variante des SGML/DSSSL Tools appelée SGML-Tools (Lite) . Pour plus d information voir L ancienne méthode : les DocBook-Tools Les DocBook-tools consistent en plusieurs paquetages qui fonctionnent ensemble pour convertir des fichiers SGML DocBook dans d autres formats, et accomplir d autres opérations. Ces formats comprennent : HTML TeX et DVI PostScript RTF PDF Man pages TexInfo 5 Chapitre 2. Les premiers pas Note : Nous avons dit que les DocBook-Tools étaient destinés au SGML DocBook. C est vrai, mais ils peuvent aussi s utiliser pour des fichiers XML DocBook. La page du projet DocBook-Tools est sur et les paquetages eux-mêmes peuvent être obtenus depuis ftp://sources.redhat.com/pub/docbook-tools/new-trials/ ou un des mirroirs. Certaines distributions commerciales ont adopté les DocBook-Tools et fournissent leur propres CD. Les DocBook-Tools comprennent les paquetages suivants : sgml-common déclarations SGML de base et outils jade moteur de feuilles de style SGML et DSSSL jadetex ensemble de macros TeX utilisées par les fichiers générés par Jade docbook-dtdxx-sgml DTD SGML DocBook (un paquetage par version de la DTD) docbook-style-dsssl Feuilles de style DSSSL de Norman Walsh pour DocBook perl-sgmlspm Interface entre Perl et SGML docbook-utils Scripts Shell et utilitaires perl psgml Mode majeur pour Emacs pour éditer des fichiers SGML Nous décrirons seulement la version RPM de ces paquetages. Pour les autres formats vous devrez adapter. 1. Télécharger les paquetages 2. Les installer comme dans l exemple suivant : $ ncftp ftp://sources.redhat.com ncftp cd pub/docbook-tools/new-trials/rpms ncftp mget i386/*.rpm 6 Chapitre 2. Les premiers pas ncftp mget noarch/*.rpm ncftp quit $ su Password: ultra-sucure # rpm -ih sgml-common*.rpm # rpm -ih jade*.rpm # rpm -ih jadetex*.rpm # rpm -ih docbook-dtd44-sgml*.rpm # rpm -ih docbook-style-dsssl*.rpm # rpm -ih perl-sgmlspm*.rpm # rpm -ih docbook-utils*.rpm # exit Note : L ordre d installation des paquetages est important. Note : Quand vous faites une mise à jour, au lieu d installer pour la première fois, l étape rpm -ih sera remplacée par rpm -Uh. Vous êtes maintenant prêt pour éditer des documents SGML/DocBook et ensuite les convertir en d autres formats. Pour ceci vous utiliserez une des commandes suivantes : docbook2html = HTML docbook2ps = PostScript docbook2pdf = PDF docbook2rtf = Rich Text Format etc La nouvelle méthode : XSLTProc et FOP Les outils basés sur XML sont plus faciles à utiliser que ceux fondés sur SGML. Les utilitaires de base peuvent être utilisés directement. Les formats de sortie sont : HTML PDF MIF PCL PS SVG 7 Chapitre 2. Les premiers pas RTF est plannifié par les versions expérimentales de FOP. Sur les systèmes basés sur RPM, vous aurez besoin des paquetages suivants : docbook-dtdxx-xml DTD DocBook XML (un paquetage par version de la DTD docbook-style-xsl Feuilles de style XSL de Norman Walsh pour DocBook libxml2 Bibliothèque XML de Daniel Veillard nécessaire pour libxslt libxslt Moteur de transformation XSLT de Daniel Veillard java-1_4_2-sun... ou un autre environnement Java, nécessaire pour fop fop Processeur XSL-FO La plupart de ces paquetages sont habituellement pré installés dans votre distribution Linux. Pour certaines, utilisez la commande rpm -ih nom du paquetage. Vous êtes maintenant prêts à éditer vos documents XML/DocBook et les convertir dans d autres formats. Pour faire ceci, vous exécuterez les commandes suivantes : xsltproc: DocBook vers HTML ou XSL-FO fop: XSL-FO vers PDF, PS, etc Mon premier fichier DocBook Premièrement, vous avez besoin d un fichier DocBook pour convertir. Prenez un simple éditeur de texte et tapez (ou copiez-collez) les lignes suivantes : Exemple 2-1. Fichier DocBook minimal ?xml version= 1.0 encoding= utf-8 ? !DOCTYPE book PUBLIC -//OASIS//DTD DocBook XML V4.4//EN /usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd book bookinfo 8 Chapitre 2. Les premiers pas title hello, world /title /bookinfo chapter title hello, world /title para c est mon premier fichier DocBook. /para /chapter /book Ensuite, pour l enregistrer, faites, myfile.docbook. Si vous utilisez les SGML Tools, le chemin entre parenthèses sur la troisième ligne n est pas nécessaire. Pour convertir ce fichier du DocBook au format HTML, utilisez la commande : $ docbook2html myfile.docbook ou $ xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/current/html/docbook.xsl myfile.docbook -o myfil selon votre boîte à outils (DocBook-tools ou XSLTProc). Jade ou xsltproc vont s exécuter et si votre document ne contient pas d erreurs vous obtiendrez un ensemble de fichiers HTML. Utilisez un navigateur Web pour ouvrir le fichier principal, book1.htm. Si vous obtenez des erreurs, lisez le journal d erreur et corrigez les en commençant par le début. Souvent, il s agit d une balise non refermée qui cause des erreurs en cascade Introduction aux feuilles de style Note : Cette section est un peu périmée. Elle devrait décrire les feuilles de style XSLT. Les feuilles de style peuvent optimiser la conversion de façon à ce que les fichiers résultants aient des noms plus intelligibles. Changez les balises book et chapter de l exemple ci-dessus comme suit : Exemple 2-2. Fichier DocBook minimal, avec certains attributs ?xml version= 1.0 encoding= utf-8 ? !DOCTYPE book PUBLIC -//OASIS//DTD DocBook XML V4.4//EN book lang= en !-- Please remark the lang attribute here -- 9 Chapitre 2. Les premiers pas bookinfo title hello, world /title /bookinfo chapter id= introduction title hello, world /title para c est mon premier fichier DocBook. /para /chapter /book Le texte entre !-- et -- est un commentaire; utilisez les pour attirer l attention du lecteur du code source DocBook. Ils ne seront jamais interprétés. Maintenant, utilisons la feuille de style fournie avec le docbook-utils : $ cp /usr/share/sgml/docbook/utils*/docbook-utils.dsl. $ docbook2html -d docbook-utils.dsl#html myfile.docbook Les fichiers iront vers un répertoire HTML et seront nommés index.html et introduction.html, à la place de noms comme book1.html. Le fichier principal sera toujours nommé index.html et les chapitres comme chapter id= introduction iront vers les fichiers nommés après l attribut id. Ces modifications ont été faites par les feuilles de style. Note : Utilisez #print à la place de #html pour spécifier la partie de la feuille de style à utiliser si vous vous servez de certaines commandes comme docbook2pdf au lieu de docbook2html. En fait les feuilles de style sont des outils très puissants. Elles permettent d éliminer les problèmes du style Je veux que ça ressemble à ça . Si vous vous posez des questions pendant l écriture d un fichier DocBook, ça indique que quelque chose est erroné dans votre approche. Si vous jetez un oeil dans le fichier nommé docbook-utils.dsl, vous verrez qu il est écrit dans un langage crypté nommé DSSSL, qui ressemble à du LISP. Ceci malheureusement indique qu une bonne connaissance de la programmation est nécessaire pour accorder les feuilles de style. Plus d information sur la façon de personnaliser les feuilles de style peut être trouvée sur Et également sur DSSSL sur (http://www.jclark.com/dsssl). 10 Chapitre 3. Notions de base 3.1. Anatomie d une balise DocBook Une balise DocBook consiste en un élément et des attributs. Par exemple chapter id= introduction contient l élément chapter et l attribut id. L élément modifie le texte balisé et les attributs modifient l élément. Par exemple, l élément chapter indique que tout texte compris entre les balises d ouverture et de fermeture sera traité comme un chapitre, tandis que l attribut id désigne le chapter et ainsi il peut être lié ou utilisé comme un nom de fichier quand DocBook le convertit dans un autre format. La plupart des balises DocBook possèdent un ensemble commun d attributs
Similar documents
View more...
Search Related
We Need Your Support
Thank you for visiting our website and your interest in our free products and services. We are nonprofit website to share and download documents. To the running of this website, we need your help to support us.

Thanks to everyone for your continued support.

No, Thanks
SAVE OUR EARTH

We need your sign to support Project to invent "SMART AND CONTROLLABLE REFLECTIVE BALLOONS" to cover the Sun and Save Our Earth.

More details...

Sign Now!

We are very appreciated for your Prompt Action!

x