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

<?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 GuideXML Gentoo. Cette syntaxe est le format officiel pour
la documentation de Gentoo, ce document lui-même ayant été créé en
utilisant GuideXML. 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 optionnel et doit normalement contenir le chemin absolu du document relativement à la racine du serveur web, bien que le nom du fichier seul fonctionne. Cet attribut est uniquement utilisé pour générer un lien vers une version imprimable de votre document et vérifier que la traduction est à jour. Notre moteur XSL passe le chemin actuel à notre feuille de style XSL. L'attribut link n'est utilisé qu'en solution de repli dans le cas où le XML soit traité par d'autres moyens.
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. 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) :

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

<i>

Permet de différencier ce que doit entrer l'utilisateur par rapport au text affiché.

<comment>

Commentaires relatifs aux actions qui suivent dans l'exemple de code.

<keyword>

Indique un mot-clé.

<ident>

Utilisé pour un identifiant.

<const>

Utilisé pour une constante.

<stmt>

Utilisé pour une instruction.

<var>

Utilisé pour une variable.

Exemple de code en couleur :

# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

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 neysx. 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.
Ceci est particulièrement utile si vous voulez nommer un développeur dont le nom contient quelques caractères exotiques que vous ne pouvez pas écrire.

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 :

<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 ou pas. 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 à 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 :

<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 réé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 pourrait être automatiquement redirigé vers la nouvelle page, mais vous ne devez pas considérer que ce comportement est garanti.

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

<guide disclaimer="obsolete" redirect="/doc/fr/handbook/handbook-x86.xml">
<title>Guide d'installation Gentoo pour x86</title>

<author title="Auteur">
...

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.

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 :

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

<book>
<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 d'un chapitre est structuré de la manière suivante :

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

<abstract>
Ceci est une petite explication du premier chapitre.
</abstract>

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

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 :

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

<book>
<title>Exemple d'utilisation du book</title>

<values>
<key id="arch">x86</key>
<key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
<key id="min-cd-size">57</key>
</values>

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

...

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.

<p>
L'image du CD d'installation Minimal s'appelle <c><keyval
id="min-cd-name"/></c> et ne pèse que <keyval
id="min-cd-size"/> Mo. Une connexion à Internet est nécessaire. Vous
pouvez utiliser ce CD d'installation pour installer Gentoo mais
<e>seulement</e> si vous disposez d'une connexion à Internet.
</p>

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 :

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
Ce paragraphe s'applique aux architectures x86 et AMD64.
</p>

<p test="func:keyval('arch')='x86'">
Ce paragraphe ne s'applique qu'aux architectures x86.
</p>

<p test="func:keyval('arch')='AMD64'">
Ce paragraphe ne s'applique qu'aux architectures AMD64.
</p>

<p test="func:keyval('arch')='PPC'">
Ce paragraphe ne s'affichera jamais !
Le corps complet est zappé à cause de la première condition.
</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
Celui-ci s'applique aux architectures AMD64, PPC64 et PPC à
cause de la chaîne 'AMD64 PPC64' qui contient 'PPC'.
</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
Cette note ne s'applique qu'aux architectures AMD64 et PPC64.
</note>

</body>

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 :

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

<pre caption = "Attribut">  (Incorrect)
<pre caption="Attribut">    (Correct)

À 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

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 !