Une sélection d'éléments docbook

Une sélection d'éléments docbook Freeduc Sup

freeduc-sup@beaupeyrat.com

Texte en italique ou en grasObjectif Mettre en avant des mots ou phrases. éléments docbook<emphasis>mettre en italique<emphasis role="bold">mettre en gras en valorisant l'attribut role à "bold" Exemple ici en italic, ici en gras ]]>Exemple de vue ici en italic, ici en gras ListingObjectif Présenter du code (fonction, module, classe, etc.). élément docbook<programlisting>Permet d'appliquer une police non proportionnelle afin de conserver la mise en page du document. Par commodité, on place parfois le code dans une section DATA (<![CDATA[ du code ]]>), afin d'éviter de redéfinir le symbole < en <ExempleUne fonction en java Nombre de caractères imprimables sur une ligne (format pdf ou postscript) : 0---------1---------2---------3---------4---------5---------6---------7---- 75 caractères maximum pour ne pas avoir les lignes tronquées par les marges /* @param nameFile le nom du fichier initial @param newExt la nouvelle extension @return le nom du fichier initial avec une nouvelle extension. Dans le cas où il n'y a pas d'extension dans le nom initial, l'extension est ajoutée. exemple : changeExtension("toto.txt", "xml") rend "toto.xml" exemple : changeExtension("toto", "xml") rend "toto.xml" exemple : changeExtension("", "xml") rend ".xml" */ public String changeExtension(String nameFile, String newExt) { String res; int posPt = nameFile.lastIndexOf('.'); if (posPt > 0) res = nameFile.substring(0, posPt) + "." + newExt; else res = nameFile + "." + newExt; return res; } ]]>Exemple de vue Une fonction en java Nombre de caractères imprimables sur une ligne (format pdf ou postscript) : 0---------1---------2---------3---------4---------5---------6---------7---- 75 caractères maximum pour ne pas avoir les lignes tronquées par les marges /* @param nameFile le nom du fichier initial @param newExt la nouvelle extension @return le nom du fichier initial avec une nouvelle extension. Dans le cas où il n'y a pas d'extension dans le nom initial, l'extension est ajoutée. exemple : changeExtension("toto.txt", "xml") rend "toto.xml" exemple : changeExtension("toto", "xml") rend "toto.xml" exemple : changeExtension("", "xml") rend ".xml" */ public String changeExtension(String nameFile, String newExt) { String res; int posPt = nameFile.lastIndexOf('.'); if (posPt > 0) res = nameFile.substring(0, posPt) + "." + newExt; else res = nameFile + "." + newExt; return res; } Copie écran consoleObjectif Présenter un état de la console. élément docbook<screen>Présenter le résultat d'un programme sur la sortie standard, ou une séquence de commandes système. Appliquer une police fixe.ExempleExemple de sortie console : $ cat bin/makeHtml.sh java -classpath /home/kpu/xsl/saxon/lib/saxon.jar com.icl.saxon.StyleSheet -o $2 $1 /home/kpu/xsl/stylesheets/docbook-xsl-1.60.1/xhtml/docbook.xsl $ makeHtml.sh selection-elts.docbook selection-elts.html $ ]]>Exemple de vue Exemple de sortie console : $ cat bin/makeHtml.sh java -classpath /home/kpu/xsl/saxon/lib/saxon.jar com.icl.saxon.StyleSheet -o $2 $1 /home/kpu/xsl/stylesheets/docbook-xsl-1.60.1/xhtml/docbook.xsl $ makeHtml.sh selection-elts.docbook selection-elts.html $ Lien vers une ressourceObjectif Proposer un lien vers une ressource. éléments docbook<ulink>nom du lienurlAttribut de ulink, sa valeur localise la ressource.Exemple un lien vers une ressource ici un autre lien ici ]]>Exemple de vue un lien vers une ressource ici un autre lien ici ImageObjectif Insérer une image. éléments docbook<figure>Permet le plus souvent une numérotation des figures dans le document. Pour l'impression papier (pdf ou postscript), il faut faire attention à la taille des images afin qu'elles ne soient pas tronquées sur les marges. Une largeur de 15 cm est généralement correcte. Pour le format, préférer le format "png". <title> Élément de l'élément figure. Le nom de la figure. <graphic>Concerne l'image à insérer.srccredit Attribut de graphic. Information sur la source du document image. fileref Attribut de graphic. Nom du fichier image.ExempleClasse VoyageTibet ]]>Exemple de vue

Classe VoyageTibet RemarquesObjectif Attirer l'attention par une note de quelques lignes. éléments docbook<note>Information en relation avec le texte courant, mais de portée plus générale.<important>Une note importante.ExempleUn exemple de note. Envoi de message L'instruction suivante : hello.exprimeToi(); Se lit de plusieurs façons, en voici deux équivalentes : J'invoque la méthode exprimeToi de l'objet référencé par la variable hello. J'envoie le message exprimeToi à l'objet référencé par la variable hello. Un exemple de remarque importante. Brevet logiciel La créativité en danger. S'informer ici. ]]>Exemple de vue Un exemple de note. Envoi de message L'instruction suivante : hello.exprimeToi(); Se lit de plusieurs façons, en voici deux équivalentes : J'invoque la méthode exprimeToi de l'objet référencé par la variable hello. J'envoie le message exprimeToi à l'objet référencé par la variable hello. Un exemple de remarque importante. Brevet logiciel La créativité en danger. S'informer ici. Jeu de questions-réponsesObjectif Idéal pour la construction de FAQ. éléments docbook<qandaset>Élément racine d'un jeu de Q/R<qandaentry>Structure contenant une question et ses éventuelles reponses (0 à n)<question>Une question. Élément enfant de qandaentry <answer>Une des réponses à la question. Élément enfant de qandaentry Exemple To be, or not to be? That is the question. Comment changer le format de papier par défaut ? Allouer la valeur A4 à 'paper.type' Dans votre fichier de redéfinition des règles : <xsl:param name="paper.type" select="A4" /> ]]>Exemple de vue To be, or not to be? That is the question. Comment changer le format de papier par défaut ? Allouer la valeur A4 à 'paper.type' Dans votre fichier de redéfinition des règles : <xsl:param name="paper.type" select="A4" /> Entête du documentObjectifInformations générales sur le document. L'exemple ci-dessous est celui utilisé comme source docbook de ce document. Voici quelques uns de ces éléments, pour les autres, référez vous à l'exemple ci-après. éléments docbook<article>Élément racine d'un article<groupauthor>Pour rassembler les auteurs (<author>)<author>Un des auteurs du document (voir l'exemple pour connaître les éléments retenus décrivant un auteur)<othercredit>Une personne ou entité, autre qu'un auteur, ayant participé au document.<date>Date de création du document<pubdate>Dernière date de publication<abstract>Un résumé du document, contenant également des infos légales.<keywordset>Un ensemble de mots clés pouvant être utilisé pour un référencement.<keyword>Un mot clé.Exemple Une sélection d'éléments docbook Freeduc Sup

freeduc-sup@beaupeyrat.com

Alix Mascret Olivier Capuozzo Valérie Emin Relecture 01 juin 2003 O9 juin 2003 Présentation d'une liste restreinte d'éléments DocBook utilisés pour des 'polys' de la distribution freeduc-sup. Objectif visé : faciliter une prise en main rapide de ce système de rédaction de documents. Open source DocBook ]]> Annexe : comment transformer ? Il faut, avant toute transformation, valider le document source. Cela est réalisé grâce à un parseur (parser en Anglais). On peut comparer cette opération à la validation grammaticale et syntaxique que réalise un compilateur sur un source. Des exemples d'outils et la façon de les utiliser sont donnés dans la partie tutoriel. Aucune transformation ne sera possible si le document n'est pas "valide", ou au mieux "bien formé". Il existe 2 techniques : une basée sur les sgmltools (outils de transformation basés sur DSSSL et le système jade) et l'autre sur xml et xslt. sgmltools sgmltools : un ensemble d'outils de transformation basés sur jade et disponible sur les principales distributions GNU/Linux. Exemple d'utilisation : $ db2html test.xml output is test Using catalogs: /etc/sgml/xml-docbook-4.1.2-1.0-14.cat Using stylesheet: /usr/share/sgml/docbook/utils-0.6.11/docbook-utils.dsl#html Working on: /home/kpu/docbook/test.xml $ Suite à cette commande, le répertoire ./test est créé et contient les documents HTML. Autre exemple, conversion vers du PDF $ db2pdf test.xml Using catalogs: /etc/sgml/xml-docbook-4.1.2-1.0-14.cat Using stylesheet: /usr/share/sgml/docbook/utils-0.6.11/docbook-utils.dsl#print Working on: /home/kpu/docbook/test.xml $ Le document test.pdf est créé dans le réprertoire courant. xslt Un document DocBook est un document XML valide (qui respecte la DTD DocBook). Pour transformer une document XML, nous utilisons une à plusieurs feuilles de style XSLT et un processeur XSLT. Il nous faut donc : Un processeur XSLT Nous présenterons quelques exemples qui utilisent : saxon : un processeur xslt écrit en java par Michael Kay. xsltproc : un processeur xslt écrit en C (voir ici). Un document source en DocBook Une ou plusieurs feuilles de styles basées sur la DTD DocBook. Vous trouverez une collection de feuilles des styles xslt http://docbook.sourceforge.net/projects/xsl/ (choisir XSL stylesheet distribution) permettant de traiter des documents DocBook en différents formats. Il existe d'autrs processeurs XSLT écrits en C ou en C++ comme xalan, sablotron et bien d'autres encore. Une liste de produits et outils autour d'xml est accessible ici. Exemple de génération d'un document HTML CLASSPATH=saxon.jar:$CLASSPATH export CLASSPATH java com.icl.saxon.StyleSheet filename.xml \ docbook-xsl-1.60.1/html/docbook.xsl > output.html On suppose ici que saxon.jar est situé dans le répertoire courant, et que ce même répertoire contient un répertoire DocBook correspondant au résultat de la décompression du fichier docbook-xsl-1.60.1.tar.gz - voir ici. Avec saxon vous devez préalablement avoir installé un JRE (java runtime engine) ou un JDK (java developement kit) - qui inclut un JRE. Vous avez un document qui décrit la procédure de téléchargement et d'installation de Java sur une machine GNU/Linux ici. Sous GNU/Linux, vous pouvez plus simplement utiliser le processeur xsltproc : xsltproc docbook-xsl-1.60.1/html/docbook.xsl filename.xml > output.html Attention, l'ordre des arguments est inversé par rapport aux outils sous java. Exemple de génération d'un document PDF Pour produire une document PDF, on s'appuie sur FOP, un projet libre en open source de la fondation Apache http://xml.apache.org/fop/ . Pour cela on réalise une opération en 2 passes : une pour générer un fichier FO (formatting object) et une deuxième pour transformer en PDF. CLASSPATH=saxon.jar:fop.jar:$CLASSPATH export CLASSPATH java com.icl.saxon.StyleSheet filename.xml \ docbook-xsl-60.1/fo/docbook.xsl > output.fo java org.apache.fop.apps.CommandLine output.fo output.pdf Prise en main de la DTD DocBook Cette partie doit vous permettre de prendre en main rapidement l'environnement de développement de documentation disponible sur la distribution freeduc-sup. Quelques adaptations mineures seront sûrement nécessaires sur d'autres distributions. Nous allons utiliser Emacs comme éditeur car il est configuré pour supporter le mode psgml qui est un ensemble de macros simplifiant l'édition de documents xml. Voir aussi la documentation des macros. La DTD DocBook est supposée installée sur votre système ici : /usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd. Si ce n'est pas le cas, vous pouvez vous la procurer ici : http://www.oasis-open.org/docbook/xml/, choisir DocBook XML V4.2 en archive ZIP que vous décompresserez. Mettez vous dans un répertoire de travail et copiez l'image "voyageTibet.png" qui fait partie de ce document dans le répertoire. Ouvrez, dans ce répertoire un nouveau document avec emacs : $>emacs index.xml& Création de l'entête Tout document commence par une déclaration. Vous pouvez saisir ou copier l'extrait ci-dessous : <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD docbook XML V4.2//EN" "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> <article lang="fr"> <articleinfo> <title>Titre de l'article</title> <author> <firstname>Votre Nom</firstname> <surname>Votre prénom</surname> <affiliation> <address><email>Votre adresse de mèl</email></address> </affiliation> </author> <date>Ici la date de conception</date> <pubdate>Ici la date de publication ou de dernière modification</pubdate> <abstract> <para>Résumé ou présentation succinte de l'article</para> </abstract> </articleinfo> <sect1><title></title> <para> </para> </sect1> </article> Vous pourrez ensuite l'adapter et le garder comme squelette pour tous les documents que vous aurez à réaliser. A ce stade vous avez déjà un document complet, valide, qui contient déjà une section bien que celle-ci soit vide. Le corps du document Mettez un titre à la section "sect1", entre les éléments "title" et "/title". Saisissez ensuite ou copier le morceau de texte ci-dessous qui permet d'insérer un morceau de texte et une image. <sect1><title>Creation d'un paragraphe</title> <para>Pour insérer un élément a partir d'Emacs avec le mode psgml, il suffit de taper "CTRL c i", puis entrer l'élément a inserer, par exemple "para". </para> <para>Pour fermer un élément qui est ouvert , il faut positionner le curseur à l'endroit où doit venir la balise de fermeture et taper "CTRL /. </para> <para>Pour contrôler la validité du document directement à partir d'Émacs il faut utiliser "CTRL c v".</para> <para>Une autre option consiste à utiliser par exemple un parseur externe comme "xmllint" en ligne de commande. </para> <programlisting> $ xmllint --noout --loaddtd --valid index.xml </programlisting> <para>Ajoutons une image : <figure> <title>Voyage au Tibet</title> <graphic fileref="voyageTibet.png"/> </figure> </para> </sect1> La première partie du document est terminée. Il faut vérifier qu'il est conforme a la dtd DocBook. Pour cela il faut utiliser un "parser". Emacs permet de faire cela assez simplement avec la commande "CTRL c v". Le résultat du contrôle apparaît dans une fenêtre du bas. Si des erreurs apparaissent il faut les corriger. En général ce sont des balises de fermetures qui manquent. Voici un exemple d'erreur : nsgmls:index.xml:35:9:E: end tag for "sect1" omitted, but OMITTAG NO was specified nsgmls:index.xml:21:0: start tag was here Ici il manque une balise "sect1" ligne 35 pour fermer la balise qui ouvre ligne 21. Deux warnings peuvent apparaître que vous pouvez laisser, ils n'influeront en rien sur le document final. nsgmls:/usr/share/sgml/declaration/xml.dcl:1:W: SGML declaration was not implied nsgmls:/usr/share/sgml/declaration/xml.dcl:31:27:W: characters in the document character set with numbers exceeding 65535 not supported Vérifier la bonne structure du document et corrigez les éventuelles erreurs. Modifier le document Nous allons rajouter un deuxième niveau de section contenant une liste. Nous allons le mettre juste avant la balise de fermeture "/sect1". <sect2><title>Compilation du source xml</title> <orderedlist> <listitem><para> db2html index.xml pour générer un document html sur "n" pages </para></listitem> <listitem><para> db2html -u index.xml pour générer un document html sur une seule page </para></listitem> <listitem><para>db2pdf index.xml pour produire une sortie pdf </para></listitem> </orderedlist> <para>Pensez, pour les documents html, à copier l'image dans le répertoire de destination. Dans notre exemple il s'agit du répertoire "index".</para> </sect2> Enfin nous allons compléter le document avec une autre section "sect1" faisant référence à la licence qui couvre ce document : <sect1> <title>Licence</title> <para>Ce document est couvert par la licence <ulink url="http://www.gnu.org/copyleft/gpl.html">GPL</ulink>.</para> <para>Le site officiel est <ulink url="http://ici mettre l'url">ici</ulink>. </para> <para>Vous pouvez utiliser, copier, modifier, distribuer librement ce document. Son utilisation n'engage en aucune façon la responsabilité de son auteur.</para> </sect1> Transformer le document xml Il ne reste plus qu'à transformer ce document xml au format html ou pdf. Pour réaliser la génération, mettez vous dans le répertoire où se trouve le document et utilisez : db2html index.xml pour générer un document html sur "n" pages db2html -u index.xml pour générer un document html sur une seule page db2pdf index.xml pour produire une sortie pdf La génération html se fait par défaut dans le répertoire "index" (nom du document). Si vous utilisez deux fois de suite la commande "db2html", la version qui est dans le répertoire index sera détruite. Si l'image n'apparaît pas dans le document html, vérifier qu'elle existe bien dans le répertoire index. Finaliser tout ça Il ne reste plus qu'à automatiser un peu tout ça. Pour cela il est possible de créer un "Makefile" qui permettra la génération automatique de tous les formats de sortie. Nous allons en faire un tout simple qui va faire l'essentiel pour nous. # Makefile, utilise dsssl # À adapter pour xsl/xslt fo # On considère que le fichier se nomme index.xml FILE=index all: txt html rtf pdf clean: rm -rf index_multi_page index_mono_page *.pdf *.ps *.txt *.rtf parse: nsgmls -sv -wxml /usr/share/sgml/declaration/xml.dcl index.xml # Sortie txt # Pour consulter avec more ou less, pas avec un éditeur # ou alors virer la table des matières. txt: htm html2text index_mono_page/${FILE}.html > ${FILE}.txt # Sortie html sur un seul fichier html htm: db2html -o index_mono_page -u index.xml cp -Rf images index_mono_page # Sortie html sur plusieurs pages html: db2html -o index_multi_page index.xml cp -Rf images index_multi_page # Sortie pdf # On passe par une génération postscript # On édite les document 1 feuille par page et 2 feuilles par page pdf: db2ps ${FILE}.xml psnup -pletter -Pa4 -b.05 -m.01 -2 ${FILE}.ps ${FILE}_2p.ps ps2pdf ${FILE}.ps ps2pdf ${FILE}_2p.ps # Sortie RTF rtf: db2rtf ${FILE}.xml Vous pouvez utiliser tout simplement ce Makefile avec les commandes "make parse", "make clean", "mke rtf", "make all" ... La génération d'un document de plus de 200 pages est réalisée comme ça automatiquement dans tous les formats de sortie en moins de 2 minutes sur ma machine. Conclusion Si vous êtes arrivé jusque là, votre environnement fonctionne correctement. Il ne reste plus qu'à se familiariser un peu plus avec la liste des éléments DocBook, le mode psgml, et tester d'autres processeurs XSLT comme Saxon. Vous découvrirez avec le temps la joie de n'avoir à maintenir qu'un seul source de votre document, indépendant des diffférents formats de sortie. Le guide complet sur xsl DocBook vous donnera toutes les indications détaillées sur l'utilisation de saxon, xalan, xsltproc, fop. DocBook: The Definitive Guide de Norman WALSH, vous donnera tous les autres éléments sur la dtd de DocBook dont vous pourriez avoir besoin. Listing complet du tutoriel <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> <article lang="fr" id="index.html"> <articleinfo> <title>Titre de l'article</title> <author> <firstname>Votre Nom</firstname> <surname>Votre prénom</surname> <affiliation> <address><email>Votre adresse de mèl</email></address> </affiliation> </author> <date>Ici la date de conception</date> <pubdate> Ici la date de publication ou de dernière modification</pubdate> <abstract> <para>Résumé ou présentation succinte de l'article</para> </abstract> </articleinfo> <sect1><title>Création d'un paragraphe</title> <para>Pour insérer un élément a partir d'emacs avec le mode psgml, il suffit de taper "CTRL c i", puis entrer l'élément à insérer, par exemple "para". </para> <para>Pour fermer un élément qui est ouvert , il faut positionner le curseur à l'endroit où doit venir la balise de fermeture et taper "CTRL /. </para> <para>Pour contrôler la validité du document directement à partir d'Émacs il faut utiliser "CTRL c v".</para> <para>Une autre option consiste à utiliser par exemple un parseur externe comme "xmllint" en ligne de commande. </para> <programlisting> $ xmllint --noout --loaddtd --valid index.xml </programlisting> <para>Ajoutons une image : <figure> <title>Voyage au Tibet</title> <graphic srccredit="vt" fileref="voyageTibet.png"/> </figure> </para> <sect2><title>Compilation du source xml</title> <orderedlist> <listitem><para> db2html index.xml pour générer un document html sur "n" pages </para></listitem> <listitem><para> db2html -u index.xml pour générer un document html sur une seule pag </para></listitem> <listitem><para> db2pdf index.xml pour produire une sortie pdf </para></listitem> </orderedlist> <para>Pensez, pour les documents html, à copier l'image dans le répertoire de destination. Dans notre exemple il s'agit du répertoire "index".</para> </sect2> </sect1> <sect1> <title>Licence</title> <para>Ce document est couvert par la licence <ulink url="http://www.gnu.org/copyleft/gpl.html">GPL</ulink>. </para> <para> Le site officiel est <ulink url="http://ici mettre l'url">ici</ulink>. </para> <para> Vous pouvez utiliser, copier, modifier, distribuer librement ce document. Son utilisation n'engage en aucune façon la responsabilité de son auteur. </para> </sect1> </article>