Gentoo Logo

Manuel du GuideXML de Gentoo

Table des matières :

1.  Introduction à GuideXML

But de GuideXML

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.

En savoir plus

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.

2.  GuideXML

Structure de base

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

Exemple de code 2.1 : La partie initiale d'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.

Chapitres et sections

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

Exemple de code 2.2 : Un document valide, mais 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.

Note : Un élément <guide> doit contenir au moins un élément <chapter>, un élément <chapter> doit contenir au moins un élément <section> et un élément <section> doit contenir au moins un élément <body>.

Un exemple de <body>

Maintenant, il est temps d'apprendre à baliser le contenu. Voici un exemple de code XML pour un élément <body> :

Exemple de code 2.3 : Exemple de contenu d'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.

Exemple de code 2.4 : Exemple de code

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

Note : Ceci est une note.

Attention : Ceci est un avertissement.

Important : Ceci est important.

Les balises de <body>

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 :

Exemple de code 2.5 : <pre> nommé

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

Epigraphes

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.

—Étudiant anonyme

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.

Exemple de code 2.6 : Petit épigraphe

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

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

Exemples de code en couleurs

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.

Note : N'oubliez pas que tous les espaces, même en début ou en fin de ligne, et les sauts de lignes d'un bloc <pre> apparaissent dans la page HTML générée.

Exemple de code en couleur :

Exemple de code 2.7 : Mon premier ebuild

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

<mail> et <uri>

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

Images

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.

Tableaux

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.

Ce titre regroupe 4 colonnes
Ce titre regroupe 6 lignes Objet A1 Objet A2 Objet A3
Objet B1 Bloc-titre 2x2
Objet C1
Objet D1..D3
Objet E1..F1 Objet E2..E3
Objet F2..F3

Listes

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.

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 :

Exemple de code 2.8 : Utiliser l'attribut id

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

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 :

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

Exemple de code 2.9 : Exemple d'annonce

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

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.

3.  Le format du Manuel

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.

Fichier principal

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 :

Exemple de code 3.1 : Exemple d'utilisation du type « book »

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

Exemple de code 3.2 : Définir une partie

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

Exemple de code 3.3 : Définir un chapitre

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

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

</chapter>

Écriture des chapitres individuels

Le contenu d'un chapitre est structuré de la manière suivante :

Exemple de code 3.4 : Syntaxe d'un chapitre

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

4.  Fonctionnalités avancées du Manuel

Valeurs globales

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 :

Exemple de code 4.1 : Définir des valeurs dans 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.

Exemple de code 4.2 : Utilisation des valeurs définies

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

Éléments conditionnels

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 :

Exemple de code 4.3 : Utilisation des éléments conditionnels

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

5.  Style d'écriture

Introduction

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.

Style d'écriture interne

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 :

Exemple de code 5.1 : 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 :

Exemple de code 5.2 : Attributs

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

Style d'écriture externe

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

Note : N.D.T. : par respect pour la langue française, nous dérogeons souvent à cette règle et terminons nos phrases par des points dans les listes.

Chaque phrase, y compris celles qui figurent dans les tables et les listes, devrait commencer par une majuscule.

Exemple de code 5.3 : Points et majuscules

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

Exemple de code 5.4 : Exemple de commentaire

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

6.  Ressources

Commencez à écrire

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 !



Imprimer

Dernière mise à jour le 27 février 2009

Une version originale plus récente datée du 7 octobre 2012 existe.

Résumé : 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 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.

Xavier Neys
Auteur, Traducteur

Daniel Robbins
Auteur

John P. Davis
Auteur

Jorge Paulo
Correcteur

Sven Vermeulen
Correcteur

Joshua Saddler
Correcteur

Matthieu Montaudouin
Traducteur

Bertrand Coppa
Traducteur

Marion Agé
Traducteur

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.