Manuel du GuideXML de GentooLa syntaxe de GuideXML est légère, mais expressive. Elle est donc simple à apprendre, mais fournit toutes les fonctionnalités nécessaires à la création de documentation Web. Le nombre de balises est réduit au minimum, ne contenant que celles qui sont utiles. Cela facilite la transformation des documents dans d'autres formats comme le DocBook, XML/SGML ou du HTML formaté pour le Web. Le but est de faciliter la création et la transformation de documents GuideXML. Si vous avez l'intention d'écrire ou de modifier des documents au format Guide XML, ou si vous voulez tester GuideXML, vous devriez lire la page des trucs et astuces du documentaliste qui explique notamment comment transformer les documents GuideXML en html. Cela peut aussi vous intéresser de lire la source XML de ce document. Voyons la syntaxe de GuideXML. Nous commençons avec les balises d'initialisation utilisées dans un document GuideXML :
Sur la première ligne, nous voyons la balise obligatoire qui permet
d'identifier un document XML. La ligne suivante identife la DTD à laquelle le
document soit se conformer. La ligne <!-- $Header$ -->
sera mise à jour automatiquement par le serveur CVS et permet de suivre les
différentes révisions de chaque document. Juste après, il y a une balise
<guide>, l'intégralité du document étant comprise entre les
balises <guide> et </guide>.
Ensuite, il y a une balise <title> qui définit le titre pour l'intégralité du document. Puis, nous arrivons aux balises <author> qui contiennent des informations sur les divers auteurs du document. Chaque balise <author> autorise un élément optionnel title qui spécifie la fonction de l'auteur par rapport au document (auteur, coauteur, correcteur, etc.) Dans cet exemple particulier, le nom de l'auteur est compris dans une autre balise, une balise <mail> qui spécifie une adresse de courrier pour cette personne. La balise <mail> est optionnelle. De plus, au moins un élément <author> est requis par document. Ensuite, nous arrivons aux balises <abstract>, <version> et <date> qui permettent respectivement de donner le résumé du document, le numéro de version actuel et la date de la version (au format AAAA-MM-JJ). Les dates qui ne respecteraient pas ce format sont copiées telles quelles dans le document produit. Nous avons maintenant récapitulé les balises qui doivent apparaître au début d'un document guide. Hormis <title> et <mail>, ces balises ne devraient pas apparaître ailleurs, excepté immédiatement après la balise <guide> et, pour être cohérent, il est recommandé (mais ce n'est pas obligatoire) de mettre ces balises avant le contenu du document. Enfin, nous avons la balise <license/>, utilisée pour publier le document sous la license Creative Commons - Attribution / Share Alike qui est requise par nos conventions de documentation. Une fois que les balises d'initialisation ont été spécifiées, vous êtes prêt pour ajouter les éléments concernant la structure du document. Les documents guide sont divisés en chapitres, chaque chapitre pouvant contenir une ou plusieurs sections. Chaque chapitre et section ont un titre. Voici un exemple de chapitre avec une seule section qui consiste en un paragraphe. Si vous ajoutez ce XML au XML de l'extrait précédent et ajoutez une balise </guide> à la fin du fichier, vous aurez un document guide valide (mais très court) :
Ci-dessus, j'ai spécifié le titre en ajoutant un élément fils <title> à l'élément <chapter>. J'ai ensuite créé une section en ajoutant un élément <section>. Vous pouvez voir qu'il a deux fils, <title> et <body>. Alors que <title> est déjà connu, <body> ne l'est pas encore. Cet élément renferme le contenu textuel de la section en question. Nous regarderons les balises autorisées dans un élément <body> un peu plus loin.
Maintenant, il est temps d'apprendre à baliser le contenu. Voici un exemple de code XML pour un élément <body> :
Maintenant, voici comment l'élément <body> ci-dessus est affiché : Ceci est un paragraphe. /etc/passwd est un fichier. http://forums.gentoo.org est mon site Web favori. Tapez ls si vous en avez envie. J'ai vraiment envie d'aller me coucher maintenant.
Nous avons présenté beaucoup de nouvelles balises dans la section précédente. Voici ce que vous avez besoin de savoir. Les balises <p> (paragraphe), <pre> (bloc de code), <note>, <warn> (avertissement) et <impo> (important) peuvent toutes contenir une ou plusieurs lignes de texte. Hormis les éléments <table>, <ul>, <ol> et <dl> (dont nous allons parler un peu plus loin), ce sont les seules balises qui peuvent être présentes dans un élément <body>. D'autre part, ces balises ne doivent pas être imbriquées. Autrement dit, ne mettez pas un élément <note> à l'intérieur d'un élément <p>. Comme vous avez pu le remarquer, l'élément <pre> conserve strictement les espaces, ce qui fait qu'il est particulièrement adapté aux exemples de code. Vous devez aussi nommer la balise <pre> avec l'attribut caption :
Les délégués des 13 états originaux ont formé le Congrès. Thomas Jefferson, une
Vierge et Benjamin Franklin chantèrent la Déclaration d'Indépendance. Franklin
a découvert l'électricité en frottant deux chats et a déclaré : « Un
cheval coupé en deux ne peut pas tenir debout. » Franklin est mort en 1790
et l'est toujours.
Les épigraphes sont souvent utilisés au début des chapitres pour illustrer ce qui va suivre. C'est simplement un paragraphe avec l'attribut by qui contient la signature de l'auteur.
<path>, <c>, <b>, <e>, <sub> et <sup> Les élements <path>, <c>, <b>, <e>, <sub> et <sup> peuvent être utilisés dans n'importe quelle balise fille de<body>, à l'exception de <pre>. L'élément <path> est utilisé pour marquer du texte qui se référe à un fichier du disque dur, que ce soit un chemin relatif ou absolu, ou à un simple nom de fichier. Cet élément est généralement rendu avec une police à chasse fixe pour le différencier du type standard de paragraphe. L'élément <c> est utilisé pour représenter une commande ou une du texte entré par l'utilisateur. Pensez à <c> quand vous voulez indiquer au lecteur que c'est quelque chose qu'il peut taper pour exécuter une action particulière. Par exemple, toutes les balises XML affichées dans ce document sont mises dans un élément <c> car elles représentent quelque chose que l'utilisateur peut taper et qui n'est pas un chemin de fichier. En utilisant l'élément <c>, vous permettez à vos lecteurs d'identifier rapidement les commandes qu'ils doivent taper. De plus, étant donné que les éléments <c> se distinguent du texte normal, il est rarement nécessaire de mettre les saisies utilisateur entre guillemets. Par exemple, ne vous référez pas à un élément « <c> » comme je viens de le faire. Eviter l'utilisation de guillemets superfétatoires rend un document plus lisible et joli ! Comme vous l'avez sûrement deviné, <b> est utilisé pour mettre du texte en gras. <e> est utilisé pour mettre en valeur un mot ou une phrase ; par exemple : je devrais vraiment utiliser plus souvent le point-virgule. Comme vous pouvez le voir, ce texte se démarque du type standard de paragraphe. Cela vous permet de donner plus de pêche à vos phrases ! Les éléments <sub> et <sup> servent à écrire sous la ligne et écrire au-dessus. Afin de rendre nos exemples de code plus lisibles, les balises suivantes sont autorisées dans des blocs <pre> :
Exemple de code en couleur :
Nous avons déja parlé de la balise <mail> plus tôt. Elle est utilisée pour lier un texte avec une adresse de courrier et a la forme <mail link="foo.bar@exemple.com">Mr. Foo Bar</mail>. Si vous voulez afficher l'adresse, vous pouvez utiliser <mail>foo.bar@exemple.com</mail>, cela sera affiché comme ceci : foo.bar@exemple.com.
Les formes courtes facilitent l'utilisation des noms et adresses de
développeurs Gentoo. Les formes <mail>neysx</mail> et
<mail link="neysx"/> afficheront Xavier Neys. Si vous
voulez utiliser une adresse d'un développeur Gentoo avec un autre contenu que
son nom complet, utilisez la seconde forme avec le contenu désiré. Par exemple,
pour obtenir le prénom d'un développeur : <mail
link="neysx">Xavier</mail> s'affichera comme Xavier.
La balise <uri> est utilisée pour pointer vers des fichiers/emplacements sur Internet. Elle a deux formes. La première peut être utilisée quand vous voulez que l'URI s'affiche, comme ce lien vers http://forums.gentoo.org/. Pour créer ce lien, j'ai tapé <uri>http://forums.gentoo.org/</uri>. L'autre forme est utile quand vous voulez associer un URI avec un autre texte quelconque ; par exemple le forum de Gentoo. Pour créer ce lien, j'ai tapé <uri link="http://forums.gentoo.org/">le forum de Gentoo</uri>. Ce n'est pas la peine d'écrire http://www.gentoo.org/ lorsque vous faites un lien vers une page du site de Gentoo. Par exemple, pour faire un lien vers l'index de la documentation, vous n'avez qu'à taper <uri link="/doc/fr/index.xml">index de la documentation</uri>. Vous pouvez même ne pas indiquer index.xml si vous faites un lien vers l'index d'un répertoire. Exemple : <uri link="/doc/fr/">index de la documentation</uri>. Le fait de laisser la barre oblique finale permet de gagner une requête HTTP. Vous ne devriez pas utiliser l'élément <uri> avec un attribut link qui commence par mailto:. Dans ce cas, utilisez l'élément <mail>. Veuillez éviter le syndrome du cliquez ici comme le recommande le W3C. Voici comment insérer des images dans un document : <figure link="mygfx.png" short="mon image" caption="mon image préférée"/>. L'attribut link pointe vers l'image, l'attribut short spécifie une description courte (utilisée pour l'attribut d'image HTML alt), et un titre. Pas trop compliqué :) Nous supportons aussi le style de balise standard HTML <img src="foo.gif"/> pour ajouter des images sans titre, bordure, etc. GuideXML contient une syntaxe de tableau simplifiée et similaire à celle du HTML. Pour commencer un tableau, utilisez une balise <table>. Commencez une ligne avec une balise <tr>. Toutefois, pour insérer des données dans le tableau, GuideXML ne supporte pas la balise HTML <td>. À la place, utilisez <th> si vous voulez insérer un en-tête ou <ti> si vous insérez de l'information normale. Vous pouvez utiliser <th> partout où <ti> est utilisable ; il n'est pas obligatoire que les éléments <th> apparaissent seulement dans la première ligne. En plus, les balises d'en-tête (<th>) et de contenu (<ti>) acceptent les attributs colspan et rowspan pour regrouper des colonnes et/ou des lignes. Les cellules de contenu (<ti> et <th>) acceptent également l'attribut align qui permet d'aligner le texte à droite, à gauche, ou de le centrer.
Pour créer des listes, ordonnées ou pas, utilisez simplement des balises similaires à celles de XHTML : <ol>, <ul> et <li>. Les listes peuvent seulement apparaître entre des balises <body> et <li>, ce qui signifique que l'on peut inclure une liste dans une autre. N'oubliez pas que vous écrivez du XML et que, contrairement à l'HTML, il est nécessaire de refermer toutes les balises, même celles des listes. Les listes de définition (<dl>) sont aussi supportées. Veuillez noter que ni la balise de définition (<dt>) ni la balise de donnée de définition (<dd>) n'acceptent d'autres balises de type bloc (paragraphes, etc.) Une liste de définition contient :
La liste suivante recopiée depuis w3.org montre qu'une liste de définition peut contenir des listes ordonnées ou pas. Cependant, elle ne peut pas contenir une autre liste de définition.
Références internes au document Grâce à GuideXML, il est facile de faire référence à d'autres parties du document par l'utilisation de liens hypertextes. Vous pouvez créer un lien pointant vers le chapitre un en tapant <uri link="#doc_chap1">chapitre un</uri>. Pour pointer vers la deuxième section du chapitre un, tapez <uri link="#doc_chap1_sect2">deuxième section du chapitre un</uri>. Pour créer un lien vers la figure 3 du chapitre 1, vous utiliseriez <uri link="#doc_chap1_fig3">figure 1.3</uri> et pour vous référer à l'exemple de code 2 du chapitre 2, vous utiliserez <uri link="#doc_chap2_pre2">exemple de code 2 du chapitre 2</uri>. Cependant, certains guides sont susceptibles de changer régulièrement et de tels liens risquent de devenir incorrects ou inexistants. Pour résoudre ce problème, vous pouvez nommer les éléments <chapter>, <section> et <tr> en leur ajoutant un attribut id et ensuite définir un lien comme ceci :
Annonces et documents obsolètes L'attribut disclaimer peut être utilisé dans les manuels et les guides pour afficher une annonce prédéfinie au début du document. Les types d'annonces disponibles sont :
Lorsque vous marquez un document comme obsolète, il est de bon aloi de mettre un lien vers la nouvelle version. L'attribut redirect fait justement cela. L'utilisateur pourrait être automatiquement redirigé vers la nouvelle page, mais vous ne devez pas considérer que ce comportement est garanti.
Les documents FAQ doivent commencer avec une liste de questions avec un lien vers leur réponse respective. La création d'une telle liste est à la fois longue et source d'erreurs. La liste peut être créée automatiquement si vous utilisez un élément faqindex comme premier chapitre du document. Cet élément a la même structure qu'un élément chapter afin de permettre les textes d'introduction. La structure du document est faite pour être découpée en chapitres (au moins un chapitre) contenant des sections, chaque section contenant une question spécifiée dans son élément title avec la réponse dans son élément body. L'index de la FAQ apparaitra comme une section par chapitre avec un lien par question. Un coup d'œil rapide à une FAQ et à sa source devrait rendre cette explication comme une évidence. Différences entre Guide et Book Afin de pouvoir produire des documentations plus volumineuses, telles que le Manuel d'installation, nous avons créé le format Book, une extension du format Guide, pour nous permettre d'écrire des documentations de manière modulaire et étalée sur plusieurs pages. La première étape est de créer un document « maître » qui ne contient que très peu de texte, mais qui relie les différents documents. Sa syntaxe est très proche de GuideXML :
Jusqu'ici, la seule différence avec un document normal est que l'élément <book> remplace <guide>. Ensuite, au lieu de définir un chapitre avec un élément <chapter>, il faut définir une partie avec un élément <part> :
Chaque partie doit contenir un titre (élément <title>) et un résumé (élément <abstract> qui permet d'introduire brièvement la partie en question. Chaque partie contient des chapitres (éléments <chapter>). Chaque chapitre doit être dans un fichier séparé. Vous ne serez donc pas surpris d'apprendre qu'un élément <include> permet d'indiquer le nom du fichier qui contient le chapitre.
Écriture des chapitres individuels Le contenu d'un chapitre est structuré de la manière suivante :
Chaque chapitre contient des éléments <section> (l'équivalent d'un élément <chapter> de GuideXML) et des éléments <subsection> (l'équivalent d'un élément <section> de GuideXML). Chaque chapitre doit avoir ses propres éléments date et version. La date la plus récente parmi tous les documents principaux et les documents de chapitres sera affichée lorsqu'un utilisateur visite une quelconque partie du manuel. 4. Fonctionnalités avancées du Manuel Quelques fois, les mêmes valeurs sont répétées plusieurs fois dans plusieurs parties d'un manuel. Les opérations de recherche globale et de remplacement ont tendance à oublier quelques itérations ou mènent à des changements involontaires. De plus, il peut être utile de définir des valeurs différentes qui pourront être partagées dans des chapitres différents, selon le manuel qui inclut le chapitre. Les valeurs globales peuvent être définies dans le fichier maître d'un manuel et utilisées dans tous les chapitres inclus. Pour définir des valeurs globales, ajoutez un élément <values> dans le fichier principal du manuel. Chaque valeur est alors définie dans un élément <key> dans lequel l'attribut id identifie la valeur, c-à-d. le nom de la variable. Le contenu de l'élément <key> est sa valeur. L'exemple suivant définit trois valeurs dans le fichier principal d'un manuel :
Les valeurs définies peuvent alors être utilisées tout au long du manuel avec l'élément en ligne <keyval id="key_id"/>. Le fait de spécifier le nom de la clef dans son attribut id, par exemple <keyval id="min-cd-name"/> la remplacera par « install-x86-minimal-2007.0-r1.iso » dans notre exemple.
Pour rendre la vie plus facile à nos traducteurs, n'utilisez seulement que de vraies valeurs, c-à-d. dont le contenu n'a pas besoin d'être traduit. Par exemple, nous avons défini la valeur min-cd-size à 57 et non à 57 MB. Les chapitres qui sont utilisés par plusieurs manuels comme nos Manuels d'installation ont souvent des petites différences en fonction du manuel qui les inclut. Au lieu d'ajouter du contenu sans rapport avec plusieurs manuels, les auteurs peuvent ajouter une condition aux élements suivants : <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> et <li>. La condition doit être une expression XPATH qui sera évaluée lors de la transformation du XML. Si celle-ci est évaluée à vrai, l'élément est traité, sinon, il est ignoré. La condition est spécifiée dans un attribut test. L'exemple suivant utilise la valeur arch qui est définie dans chaque fichier principal de manuel pour conditionner du contenu :
Puisque le projet de documentation de Gentoo est un effort commun, il est probable que plusieurs personnes doivent modifier un même document. Il convient donc de respecter certaines conventions quant au style d'écriture. Nos conventions régissent d'une part le style d'écriture interne des documents au format XML, et d'autre part le contenu pour éviter certaines incompréhensions chez nos lecteurs. Ces deux aspects sont décrits ci-dessous. Un saut de ligne doit suivre chaque balise GuideXML (ouverture et fermeture), sauf les suivantes : <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment> et <mail>. Une ligne vide doit suivre chaque balise <body> (ouverture uniquement) et précéder chaque <chapter>, <p>, <table>, <author> (définition), <pre>, <ul>, <ol>, <warn>, <note> et <impo> (ouverture uniquement). La longueur des lignes doit être limitée à 80 positions sauf à l'intérieur de la balise <pre>. Il n'est permis de déroger à cette règle que quand il n'est pas possible de faire autrement, par exemple pour une URL trop longue. L'auteur doit ensuite aller à la ligne dès que possible. Il est recommandé de ne pas dépasser les 80 caractères dans le document généré dans les balises <pre> pour faciliter la lecture en mode console. L'indentation est proscrite, sauf à l'intérieur des balises <tr> (d'une <table>), <ul>, <ol>, <dl> et <author>. Si l'indentation est utilisée, elle doit être de deux espaces par indentation, c-à-d. pas de tabulation ni plus d'espaces. En outre, les tabulations ne sont pas autorisées dans les documents GuideXML. Si un saut de ligne est nécessaire à l'intérieur des balises <ti>, <th>, <li> ou <dd>, leur contenu doit alors être indenté. Un exemple d'indentation :
Les attributs doivent être définis sans espace entre le nom de l'attribut, le signe « = » et la valeur de l'attribut. Voici un exemple :
À l'intérieur des tables (<table>) et des listes (<ul>, <ol> et <dl>), des points (« . ») ne devraient être utilisés que si plusieurs phrases apparaissent. Dans ce cas, le point ou tout autre signe de ponctuation sont autorisés.
Chaque phrase, y compris celles qui figurent dans les tables et les listes, devrait commencer par une majuscule.
Les exemples de code doivent toujours avoir un titre. Essayez d'utiliser <uri> avec un attribut link autant que possible. Nous préférons écrire le forum Gentoo plutôt que http://forums.gentoo.org. Quand vous placez un commentaire à l'intérieur d'une balise <pre>, utilisez <comment> et placez le texte entre parenthèses ou utilisez le marqueur de commentaires ad hoc en fonction du langage utilisé (# pour les scripts bash et bien d'autres, // pour du C/C++, etc.) De plus, vous devez placez le commentaire avant le sujet auquel il se rapporte.
GuideXML a été spécialement conçu pour être « simple et léger » afin que les développeurs puissent passer plus de temps à écrire de la documentation et moins à apprendre la syntaxe XML. Espérons que cela permette aux développeurs qui ne sont habituellement pas très « bavards » d'écrire de la documentation Gentoo de qualité. N'hésitez pas à consulter nos trucs et astuces du documentaliste. Si vous voulez aider (ou si vous avez des questions sur GuideXML), envoyez un message en anglais sur la liste de diffusion gentoo-doc en indiquant ce que vous souhaitez améliorer. Amusez-vous bien ! Ce document est protégé par la licence Creative Commons : Paternité - Partage des Conditions Initiales à l'Identique 2.5. |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
