La syntaxe de Guide XML 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 Guide XML.

Si vous avez l'intention d'écrire ou de modifier des documents au format Guide XML, ou si vous voulez tester Guide XML, vous devriez lire la page des trucs et astuces du documentaliste qui explique notamment comment transformer les documents Guide XML en html.

Cela peut aussi vous intéresser de lire la source XML de ce document.

Voyons la syntaxe de guide XML. Nous commençons avec les balises d'initialisation utilisées dans un document guide XML :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/fr/guide.xml" lang="fr">
<title>Gentoo Documentation Guide</title>

<author title="Auteur"><mail link="votre.mail@domaine.com">
  Votre Nom</mail>
</author>

<abstract>
Ce guide vous montre comment écrire de la documentation Web en utilisant la
nouvelle syntaxe Guide XML Gentoo.  Cette syntaxe est le format officiel pour
la documentation de Gentoo, ce document lui-même ayant été créé en
utilisant Guide XML. Ce guide suppose que vous avez un minimum de
connaissances en XML et HTML.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.0</version>
<date>2004-12-25</date>

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>. L'attribut link est obligatoire et doit normalement contenir le chemin absolu du document relativement à la racine du serveur web, bien que le nom du fichier seul fonctionnera. Cet attribut est principalement utilisé pour générer un lien vers une version imprimable de votre document. Si vous mettez une valeur incorrecte, le lien vers la version imprimable ne marchera pas, ou alors il pointera vers un autre document. Les documents traduits doivent le chemin entier car cela sert aussi à vérifier si une version plus récente du document existe. L'attribut lang spécifie le code de la langue utilisée dans votre document. Il est utilisé pour formater la date et insérer des chaînes de caractères telles que « Note », « Contenu », etc. dans la langue spécifiée. La langue par défaut est l'anglais.

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 et peut donc être omise. De plus, il n'est pas nécessaire d'avoir plus d'un élément <author> 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 seront copiées telles quelles dans le document produit.

Nous avons maintenant fait le tour des 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) :

<chapter>
<title>Ceci est mon chapitre</title>
<section>
<title>Ceci est la première section de mon chapitre</title>
<body>
<p>Ceci est le contenu de ma section.</p>
</body>
</section>
</chapter>

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> :

<p>
Ceci est un paragraphe. <path>/etc/passwd</path> est un fichier.
<uri>http://forums.gentoo.org</uri> est mon site Web favori.
Tapez <c>ls</c> si vous en avez envie. J'ai <e>vraiment</e> envie d'aller me coucher maintenant.
</p>

<pre caption="Exemple de code">
Ceci est un résultat de commande ou du code.
# <i>ceci est tapé par l'utilisateur</i>

Rendez le HTML/XML plus simple à lire en utilisant de l'emphase :
<foo><i>bar</i></foo>

<comment>(Voici comment insérer un commentaire dans un bloc de code.)</comment>
</pre>
<note>Ceci est une note.</note>
<warn>Ceci est un avertissement.</warn>
<impo>Ceci est important.</impo>

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.

Ceci est un résultat de commande ou du code.
# ceci est tapé par l'utilisateur

Rendez le HTML/XML plus simple à lire en utilisant de l'emphase :
<foo>bar</foo>

(Voici comment insérer un commentaire dans un bloc de code.)

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 :

<pre caption="Résultat de uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

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.

<p by="Étudiant anonyme">
Les délégués des 13 états originaux ont formé...
</p>

Les élements <path>, <c>, <b>, <e>, <sub> et <sup> peuvent être utilisés dans n'importe quel balise fille de<body>, à l'exception de <pre>. L'élément <i> ne peut être utilisé qu'à l'intérieur d'un <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 permettrez à 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 !

Pour mettre en évidence du texte que l'utilisateur doit entrer au clavier à l'intérieur d'un élément <pre>, utilisez <i> au lieu de <c>.

Comme vous l'avez surement deviné, <b> est utilisé pour mettre en gras le texte.

<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}.

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.com">Mr. Foo Bar</mail>. Si vous voulez afficher l'adresse, vous pouvez utiliser <mail>foo@bar.com</mail>, cela sera affiché comme ceci : foo@bar.com.

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>.

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.

Guide 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, Guide 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, la balise d'en-tête de tableau (<th>) accepte les attributs colspan et rowspan pour regrouper des colonnes et/ou des lignes sous un même titre, comme vu ci-dessous :

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 :

<dl>

Une balise de Liste de Définition contenant

<dt>

Des paires de balises de Terme de Définition

<dd>

et des balises de Données de Définition

La liste suivante recopiée depuis w3.org montre qu'une liste de définition peut contenir des listes ordonnées et désordonnées. Cependant, elle ne peut pas contenir une autre liste de définition.

Les ingrédients :

• 100 g. de farine
• 10 g. de sucre
• 1 tasse d'eau
• 2 œufs
• Du sel et du poivre

La procédure :

1. Mélangez vaguement les ingrédients secs
2. Ajoutez-y les autres
3. Mélangez pendant 10 minutes
4. Mettez-y au four à 300° pendant une heure

Remarque :

Cette recette peut être améliorée en y ajoutant des raisins.

Grâce à guide XML, 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 :

<chapter id="foo">
<title>Le titre de foo !</title>
...
<p>
Veuillez consulter le <uri link="#foo">chapitre sur foo</uri>
</p>

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 :

• articles sert pour les articles reédités
• draft sert à indiquer que le travail sur le document n'est pas terminé et qu'il ne doit pas être considéré comme officiel.
• oldbook est utilisé pour indiquer qu'un manuel est vieux et n'est plus entretenu.
• obsolete est utiliser pour indiquer qu'un document est obsolète.

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 devrait être automatiquement redirigé vers la nouvelle page, mais vous ne devez pas compter uniquement là-dessus.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->
 
<guide link="/doc/fr/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/fr/handbook/handbook-x86.xml">
<title>Guide d'installation Gentoo pour x86</title>

<author title="Auteur">
...

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. C'est une bonne idée de ne pas dépasser les 80 caractères rendus pour les balises <pre> pour faciliter la lecture aux utilisateurs 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 :

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Ceci est un exemple d'indentation</ti>
  <ti>
    Si le texte ne tient pas sur 80 colonnes, il faut alors l'indenter si la
    balise mère l'autorise
  </ti>
</tr>
</table>

<ul>
  <li>Une option</li>
  <li>Une autre option</li>
</ul>

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 :

Mauvais :     <pre caption = "Attribut">
Correct :     <pre caption="Attribut">

À 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.

<ul>
  <li>Pas de point</li>(Le point est utilisé en français.)

  <li>Un point. Plusieurs phrases, vous vous rappelez ?</li>
</ul>

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.

(Remplacez « jean » par votre nom.)
# id jean

Le format actuel ne permettait pas de produire des documents plus volumineux tels que le manuel d'installation. Le format GuideXML a donc été étendu pour permettre la rédaction de documents 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 :

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book link="example.xml">
<title>Exemple d'utilisation du type « book »</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>
<date>...</date>

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> :

<part>
<title>Première partie</title>
<abstract>
  ...
</abstract>

(Les chapitres suivent)
</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.

<chapter>
<title>Chapitre 1</title>
<abstract>
  Ceci est un court résumé du chapitre.
</abstract>

  <include href="chemin/vers/chapter-one.xml"/>

</chapter>

Le contenu de chaque chapitre est structuré comme suit :

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

<version>...</version>
<date>...</date>

(Définir des éléments <section> et <subsection>)

</sections>

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.

Guide 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 Guide), envoyez un message en anglais sur la liste de diffusion gentoo-doc en indiquant ce que vous souhaitez améliorer. Amusez-vous bien !