= Format DocBook = == Qu'est ce que c'est? == Doc''''''Book est une redéfinition du XML. Le XML est un langage à balises qui permet le stockage et le transfert d'information Unicode. Doc''''''Book précise le but du langage XML, il part du principe que les données sont de type plutôt documentation technique. C'est le but originel de Doc''''''Book, mais il se prête potentiellement à un usage plus diversifié. Cette citation du [[http://www.traduc.org/Guides_pratiques/Suivi/DocBook-Demystification-HOWTO/Document|Guide pratique: comprendre DocBook]] résume bien les deux principales qualités de Doc''''''Book: '''Doc''''''Book offre deux possibilités qui le rendent vraiment intéressant. La première est la production multi-formats et la seconde la réalisation de bases de documents interrogeables.''' Cela signifie que Doc''''''Book n'est pas un langage de présentation comme le HTML. C'est un langage de sens et de structure des documents. Il permet une très grande liberté dans le choix d'une présentation, choix qui peut être amélioré, redéfini au fil du temps. Il permet aussi de rendre le texte plus intelligible par un moteur de recherche. Si l'on prend par exemple la phrase «Cube est une œuvre révolutionnaire», un balisage possible sera: {{{ Cube est une œuvre révolutionnaire }}} Que permet ce balisage? 1. la balise permet la première qualité de Doc''''''Book: choisir une apparence pour un texte balisé (on choisira pour cette balise en général de le mettre en italique) 1. Un engin de recherche «comprendra» que Cube est un titre (de film en l'occurrence), et non un cube mathématique ou de glace. Il est vrai qu'aujourd'hui nous utilisons plus la première qualité de Doc''''''Book que la seconde, mais la seconde qualité reste présente et donnera peut être plus tard lieu à des usages intéressants. == Apprendre DocBook == Avant de commencer la traduction d'un article, il faut avoir un savoir fonctionnel de Doc''''''Book. Concrètement, un article Doc''''''Book se compose d'un certain nombre de balises qui définissent ses composantes immuables (en-tête, biographie de l'auteur...) et d'autres balises qui changent selon le contenu. Il est préférable d'avoir à l'esprit les balises les plus importantes afin de produire un code Doc''''''Book correct. Nous vous recommandons de vous former quelques heures avec les documents suivants: * [[http://opensource.bureau-cornavin.com/crash-course/index.html|Crash-course to DocBook]], un guide rapide mais qui donne un bon aperçu général. * [[http://www.docbook.org/tdg5/en/html/docbook.html|DocBook 5: The Definitive Guide]] ce guide est exhaustif et il est inutile de tout lire, cependant il est utile comme référence des balises, en liaison avec notre [[http://ftp.traduc.org/projets/gazette-linux/DocBook%20gazette.html|tableau DocBook]]. * [[Guides_pratiques/Petit-guide-du-traducteur.html#docbook|Le petit guide du traducteur]] de Traduc explique très bien les concepts du Doc''''''Book. * Nous vous proposons certains articles de la Gazette préformatés en Doc''''''Book: http://ftp.traduc.org/projets/gazette-linux/a-traduire/ par un acteur de la Gazette, Frédéric Marchal <>. Si vous souhaitez traduire l'un de ces articles, le code Doc''''''Book est déjà préparé pour vous. Il est intéressant de regarder le code, car il est fait selon les règles de la Gazette. '''Enfin''', nous avons à la Gazette notre propre ligne directrice concernant le Doc''''''Book. Notre emploi du Doc''''''Book ne devrait pas dans les faits dépasser l'usage d'une centaine de balises recommandées. Ces balises sont décrites dans [[http://ftp.traduc.org/projets/gazette-linux/DocBook%20gazette.html|ce tableau]]. Nous vous demandons de bien le lire et de vous y référer lors de l'élaboration de votre article. == Outils DocBook == Un document Doc''''''Book n'est pas lisible tel quel mais il peut être converti dans de nombreux formats. Cependant, seul le format HTML nous intéresse pour le moment. Voyons comment produire des fichiers HTML. === Installation des outils === La conversion du Doc''''''Book en HTML nécessite quelques outils qui doivent être présents sur votre ordinateur: 1. Un ensemble de règles pour traduire le Doc''''''Book en HTML. Nous utilisons les feuilles de style Doc''''''Book XSL de Norman Walsh. Ces règles sont disponibles dans le paquet {{{docbook-xsl}}} sous Debian ou {{{docbook-xsl-stylesheets}}} sous Gentoo. 2. Un moteur capable d'appliquer ces règles. Nous recommandons {{{xsltproc}}} disponible dans un paquet du même nom sous Debian et dans {{{libxslt}}} sous Gentoo. 3. Un outil pour vérifier la validité du document Doc''''''Book que vous avez préparé. Utilisez {{{xmllint}}} qui se trouve dans le paquet {{{docbook-xsl-stylesheets}}} sous Debian et dans {{{libxml2}}} sous Gentoo. 4. Une couche supplémentaire pour étoffer la présentation minimaliste par défaut des feuilles de style XSL. Installez les outils 1 à 3 sur votre ordinateur en utilisant la procédure habituelle pour votre distribution. Téléchargez les fichiers qui se trouvent dans le répertoire http://ftp.traduc.org/projets/gazette-linux/outils-docbook/ et copiez les dans le répertoire où vous comptez stocker les articles que vous traduirez. Il y a trois fichiers: {{{gazette.xsl}}}, {{{gazette.css}}} et {{{Makefile}}}. === Utilisation des outils === Supposons que vous avez préparé l'article {{{lg000-A.xml}}} et que vous voulez contempler l'apparence de votre œuvre en HTML. Pour cela, confirmez d'abord que le document Doc''''''Book est correctement formaté avec la commande {{{ xmllint --nonet --valid --noout lg000-A.xml }}} Si des erreurs sont rapportées, corrigez les avant de passer à l'étape suivante. Si le document est correct, convertissez le avec la commande {{{ xsltproc --path /chemin/vers/docbook/xhtml/ gazette.xsl lg000-A.xml > lg000-A.html }}} Remplacez le {{{/chemin/vers/docbook/xhtml/}}} par le chemin où la feuille de style XSL {{{xhtml/docbook.xsl}}} a été installée. Sous Debian, il s'agit de {{{/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/xhtml/}}}. Sous Gentoo, il faut utiliser {{{/usr/share/sgml/docbook/xsl-stylesheets/xhtml}}}. Le fichier {{{lg000-A.html}}} ainsi produit peut être ouvert dans n'importe quel navigateur. Pour en savoir plus sur le fonctionnement de cet outil et sur l'utilisation du {{{Makefile}}}, consultez la page [[Gazette_Linux/Explication_Outil_DocBook|décrivant un peu plus en détail l'outil DocBook]]. Comme alternative au Doc''''''Book existe le [[../Format_HTML|HTML]] et le [[../Format_wiki|wiki]]. [[../Procédure|Revenir au tutorial Gazette]].