--- xml-guide.xml.old 2006-01-25 18:27:49.000000000 +0100 +++ xml-guide.xml 2006-01-25 21:08:56.609320928 +0100 @@ -3,7 +3,7 @@ <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/fr/xml-guide.xml" lang="fr"> -<title>Manuel du Guide XML de Gentoo Linux</title> +<title>Manuel du Guide XML de Gentoo</title> <author title="Auteur"> <mail link="drobbins@gentoo.org">Daniel Robbins</mail> @@ -21,12 +21,15 @@ <author title="Traducteur"> <mail link="mat@frheaven.com">Matthieu Montaudouin</mail> </author> +<author title="Traducteur"> + <mail link="koppatroopa@yahoo.fr">Bertrand Coppa</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 Gentoo Linux, ce document lui-même ayant été créé en utilisant -Guide XML. Ce guide suppose que vous avez un minimum de connaissances en XML +nouvelle syntaxe Guide XML Gentoo. Cette syntaxe est le format officiel pour +la documentation 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> @@ -34,8 +37,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>2.25</version> -<date>2005-08-23</date> +<version>2.29</version> +<date>2005-10-13</date> <chapter> <title>Introduction à Guide XML</title> @@ -47,8 +50,8 @@ <p> 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 +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. </p> @@ -71,6 +74,11 @@ documentaliste</uri> qui explique notamment comment transformer les documents Guide XML en html. </p> + +<p> +Cela peut aussi vous intéresser de lire <uri link="?passthru=1">la source XML</uri> +de ce document. +</p> </body> </section> @@ -82,7 +90,7 @@ <body> <p> -Voyons la syntaxe de guide XML. Nous commençons avec les balises +Voyons la syntaxe de guide XML. Nous commençons avec les balises d'initialisation utilisées dans un document guide XML : </p> @@ -92,7 +100,7 @@ <!-- $Header$ --> <guide link="<i>/doc/fr/guide.xml</i>" lang="<i>fr</i>"> -<title><i>Gentoo Linux Documentation Guide</i></title> +<title><i>Gentoo Documentation Guide</i></title> <author title="<i>Auteur</i>"><mail link="<i>votre.mail@domaine.com</i>"> <i>Votre Nom</i></mail> @@ -101,8 +109,8 @@ <abstract> <i>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 Linux, ce document lui-même ayant été créé en -utilisant Guide XML. Ce guide suppose que vous avez un minimum de +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.</i> </abstract> @@ -121,14 +129,16 @@ 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 <c><guide></c>, l'intégralité du document étant comprise entre les -balises <c><guide> et </guide></c>. L'attribut <c>link</c> est +balises <c><guide> et </guide></c>. L'attribut <c>link</c> 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 +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. L'attribut <c>lang</c> spécifie le code du -langage utilisé dans votre document. Il est utilisé pour formater la date et +pointera vers un autre document. Les documents traduits <e>doivent</e> le +chemin entier car cela sert aussi à vérifier si une version plus récente du +document existe. L'attribut <c>lang</c> 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. @@ -141,12 +151,12 @@ <p> Puis, nous arrivons aux balises <c><author></c> qui contiennent des -informations sur les divers auteurs du document. Chaque balise -<c><author></c> autorise un élément optionnel <c>title=</c> qui +informations sur les divers auteurs du document. Chaque balise +<c><author></c> autorise un élément optionnel <c>title</c> 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 +coauteur, correcteur, etc.) Dans cet exemple particulier, le nom de l'auteur est compris dans une autre balise, une balise <c><mail></c> qui -spécifie une adresse de courrier pour cette personne. La balise +spécifie une adresse de courrier pour cette personne. La balise <c><mail></c> est optionnelle et peut donc être omise. De plus, il n'est pas nécessaire d'avoir plus d'un élément <c><author></c> par document. </p> @@ -161,7 +171,7 @@ <p> Nous avons maintenant fait le tour des balises -qui doivent apparaître au début d'un document guide. Hormis +qui doivent apparaître au début d'un document guide. Hormis <c><title></c> et <c><mail></c>, ces balises ne devraient pas apparaître ailleurs, excepté immédiatement après la balise <c><guide></c>, et pour être cohérent il est recommandé (mais ce n'est @@ -184,10 +194,10 @@ <body> <p> 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 +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 +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 <uri link="#doc_chap2_pre1">l'extrait précédent</uri> et ajoutez une balise <c></guide></c> à la fin du fichier, vous aurez un document guide valide (mais très court) : @@ -207,11 +217,11 @@ <p> Ci-dessus, j'ai spécifié le titre en ajoutant un élément fils -<c><title></c> à l'élément <c><chapter></c>. J'ai ensuite créé une +<c><title></c> à l'élément <c><chapter></c>. J'ai ensuite créé une section en ajoutant un élément <c><section></c>. Vous pouvez voir qu'il a -deux fils, <c><title></c> et <c><body></c>. Alors que +deux fils, <c><title></c> et <c><body></c>. Alors que <c><title></c> est déjà connu, <c><body></c> ne l'est pas encore. -Cet élément renferme le contenu textuel de la section en question. Nous +Cet élément renferme le contenu textuel de la section en question. Nous regarderons les balises autorisées dans un élément <c><body></c> un peu plus loin. </p> @@ -237,16 +247,16 @@ <pre caption="Exemple de contenu d'un élément « body »"> <p> -Ceci est un paragraphe. <path>/etc/passwd</path> est un fichier. +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. +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: +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> @@ -262,16 +272,16 @@ </p> <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. +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: +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> @@ -290,18 +300,19 @@ <p> Nous avons présenté beaucoup de nouvelles balises dans la section précédente. -Voici ce que vous avez besoin de savoir. Les balises <c><p></c> +Voici ce que vous avez besoin de savoir. Les balises <c><p></c> (paragraphe), <c><pre></c> (bloc de code), <c><note></c>, <c><warn></c> (avertissement) et <c><impo></c> (important) peuvent -toutes contenir une ou plusieurs lignes de texte. Hormis l'élément -<c><table></c> (dont nous allons parler un peu plus loin), ce sont les +toutes contenir une ou plusieurs lignes de texte. Hormis les éléments +<c><table></c>, <c><ul></c>, <c><ol></c> et +<c><dl></c> (dont nous allons parler un peu plus loin), ce sont les seules balises qui peuvent être présentes dans un élément <c><body></c>. -D'autre part, ces balises <e>ne doivent pas être imbriquées</e>, autrement dit, +D'autre part, ces balises <e>ne doivent pas être imbriquées</e>. Autrement dit, ne mettez pas un élément <c><note></c> à l'intérieur d'un élément -<c><p></c>. Comme vous avec pu le remarquer, l'élément -<c><pre></c> conserve les espaces strictement, ce qui fait qu'il est -particulièrement adapté aux exemples de code. Vous pouvez aussi nommer la -balise <c><pre></c> : +<c><p></c>. Comme vous avez pu le remarquer, l'élément +<c><pre></c> conserve strictement les espaces, ce qui fait qu'il est +particulièrement adapté aux exemples de code. Vous devez aussi nommer la +balise <c><pre></c> avec l'attribut <c>caption</c> : </p> <pre caption="<pre> nommé"> @@ -314,14 +325,46 @@ </body> </section> <section> -<title><path>, <c>, <i> et <e></title> +<title>Epigraphes</title> <body> +<p by="Étudiant anonyme"> +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. +</p> + <p> -Les éléments <c><path></c>, <c><c></c> et <c><e></c> peuvent -être utilisés dans n'importe quelle balise fille de <c><body></c>, à -l'exception de <c><pre></c>. L'élément <c><i></c> ne peut être -utilisé qu'à l'intérieur d'un <c><pre></c>. +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> + + +<pre caption="Petit épigraphe"> +<p by="Étudiant anonyme"> +Les délégués des 13 états originaux ont formé... +</p> +</pre> + +</body> +</section> +<section> + + +<title> +<path>, <c>, <i>, <b>, <e>, <sub> and +<sup> +</title> +<body> +<p> +Les élements <c><path></c>, <c><c></c>, <c><b></c>, +<c><e></c>, <c><sub></c> et <c><sup></c> peuvent être +utilisés dans n'importe quel balise fille de<c><body></c>, à l'exception +de <c><pre></c>. L'élément <c><i></c> ne peut être utilisé qu'à +l'intérieur d'un <c><pre></c>. </p> <p> @@ -334,8 +377,8 @@ <p> L'élément <c><c></c> est utilisé pour représenter une <e>commande</e> ou -une <e>du texte entré par l'utilisateur</e>. Pensez à <c><c></c> quand vous -voulez indiquer au lecteur que c'est quelque chose qu'il peut taper pour +une <e>du texte entré par l'utilisateur</e>. Pensez à <c><c></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><c></c> car elles représentent quelque chose que l'utilisateur peut taper et qui n'est pas @@ -356,6 +399,11 @@ </p> <p> +Comme vous l'avez surement deviné, <c><b></c> est utilisé pour <b>mettre +en gras</b> le texte. +</p> + +<p> <c><e></c> est utilisé pour mettre en valeur un mot ou une phrase ; par exemple : je devrais <e>vraiment</e> utiliser plus souvent le point-virgule. @@ -363,6 +411,11 @@ Cela vous permet de donner plus de <e>pêche</e> à vos phrases ! </p> +<p> +Les éléments <c><sub></c> et <c><sup></c> servent à <sub>écrire +sous la ligne</sub> et <sup>écrire au-dessus</sup>. +</p> + </body> </section> @@ -373,19 +426,22 @@ <p> Nous avons déja parlé de la balise <c><mail></c> plus tôt. Elle est utilisée pour lier un texte avec une adresse de courrier, et a la forme -<c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>. +<c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>. Si vous +voulez afficher l'adresse, vous pouvez utiliser +<c><mail>foo@bar.com</mail></c>, cela sera affiché comme +ceci : <mail>foo@bar.com</mail>. </p> <p> La balise <c><uri></c> est utilisée pour pointer vers des -fichiers/emplacements sur Internet. Elle a deux formes. La première peut être +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 -<uri>http://forums.gentoo.org</uri>. Pour créer ce lien, j'ai tapé -<c><uri>http://forums.gentoo.org</uri></c>. L'autre forme est -utile quand vous voulez associer un URI avec un autre texte quelconque; par -exemple <uri link="http://forums.gentoo.org">le forum de Gentoo</uri>. Pour +<uri>http://forums.gentoo.org</uri>. Pour créer ce lien, j'ai tapé +<c><uri>http://forums.gentoo.org</uri></c>. L'autre forme est +utile quand vous voulez associer un URI avec un autre texte quelconque ; +par exemple <uri link="http://forums.gentoo.org">le forum de Gentoo</uri>. Pour créer <e>ce</e> lien, j'ai tapé <c><uri -link="http://forums.gentoo.org">le forum de Gentoo</uri></c>. Ce +link="http://forums.gentoo.org">le forum de Gentoo</uri></c>. Ce n'est pas la peine d'écrire <c>http://www.gentoo.org/</c> lorsque vous faites un lien vers une page du site de Gentoo. Par exemple, pour faire un lien vers l'<uri link="/doc/fr/index.xml">index de la documentation</uri>, vous n'avez @@ -406,9 +462,9 @@ <p> Voici comment insérer des images dans un document : <c><figure link="mygfx.png" short="mon image" caption="mon image préférée"/></c>. -L'attribut <c>link=</c> pointe vers l'image, l'attribut <c>short=</c> spécifie +L'attribut <c>link</c> pointe vers l'image, l'attribut <c>short</c> spécifie une description courte (utilisée pour l'attribut d'image HTML -<c>alt=</c>), et un titre. Pas trop compliqué :) Nous supportons aussi le +<c>alt</c>), 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. </p> @@ -416,31 +472,106 @@ </body> </section> <section> -<title>Tableaux et listes</title> +<title>Tableaux</title> <body> <p> Guide contient une syntaxe de tableau simplifiée et similaire à celle du HTML. -Pour commencer un tableau, utilisez une balise <c><table></c>. Commencez -une ligne avec une balise <c><tr></c>. Toutefois, pour insérer des -données dans le tableau, Guide ne supporte <e>pas</e> la balise HTML <td>. À -la place, utilisez <c><th></c> si vous voulez insérer un en-tête ou -<c><ti></c> si vous insérez de l'information normale. Vous pouvez -utiliser <c><th></c> partout où <c><ti></c> est utilisable; il -n'est pas obligatoire que les éléments <c><th></c> apparaissent seulement -dans la première ligne. Actuellement, ces balises ne supportent aucun attribut, -mais quelques uns (comme l'attribut <c>caption=</c> pour <c><table></c>) -pourraient être ajoutés ultérieurement. +Pour commencer un tableau, utilisez une balise <c><table></c>. Commencez +une ligne avec une balise <c><tr></c>. Toutefois, pour insérer des +données dans le tableau, Guide ne supporte <e>pas</e> la balise HTML <td>. +À la place, utilisez <c><th></c> si vous voulez insérer un en-tête ou +<c><ti></c> si vous insérez de l'information normale. Vous pouvez +utiliser <c><th></c> partout où <c><ti></c> est utilisable ; +il n'est pas obligatoire que les éléments <c><th></c> apparaissent +seulement dans la première ligne. </p> <p> +En plus, la balise d'en-tête de tableau (<c><th></c>) accepte les +attributs <c>colspan</c> et <c>rowspan</c> pour regrouper des colonnes et/ou +des lignes sous un même titre, comme vu ci-dessous : +</p> + +<table> +<tr> +<th colspan="4">Ce titre regroupe 4 colonnes</th> +</tr> +<tr> +<th rowspan="3">Ce titre regroupe 3 lignes</th> +<ti>Objet A1</ti> +<ti>Objet A2</ti> +<ti>Objet A3</ti> +</tr> +<tr> +<ti>Objet B1</ti> +<th colspan="2" rowspan="2">Bloc-titre 2x2</th> +</tr> +<tr> +<ti>Objet C1</ti> +</tr> +</table> + +</body> +</section> +<section> +<title>Listes</title> +<body> + +<p> Pour créer des listes, ordonnées ou pas, utilisez simplement des balises similaires à celles de XHTML : <c><ol></c>, <c><ul></c> et -<c><li></c>. Les balises de liste ne peuvent être insérées que dans des -éléments <c><p></c>, <c><body></c>, <c><ol></c> ou -<c><ul></c>. N'oubliez pas de fermer les balises comme dans tout fichier -XML. -</p> +<c><li></c>. Les listes peuvent seulement apparaître entre des balises +<c><body></c> et <c><li></c>, 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. +</p> +<p> +Les listes de définition (<c><dl></c>) sont aussi supportées. Veuillez +noter que ni la balise de définition (<c><dt></c>) ni la balise de donnée +de définition (<c><dd></c>) n'acceptent d'autres balises de type bloc +(paragraphes, etc.). Une liste de définition contient : +</p> +<dl> +<dt><c><dl></c></dt> +<dd>Une balise de <b>L</b>iste de <b>D</b>éfinition contenant</dd> +<dt><c><dt></c></dt> +<dd>Des paires de balises de <b>T</b>erme de <b>D</b>éfinition</dd> +<dt><c><dd></c></dt> +<dd>et des balises de <b>D</b>onnées de <b>D</b>éfinition</dd> +</dl> + +<p> +La liste suivante recopiée depuis <uri +link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> 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. +</p> + +<dl> +<dt><b>Les ingrédients :</b></dt> +<dd> +<ul> +<li>100 g. de farine</li> +<li>10 g. de sucre</li> +<li>1 tasse d'eau</li> +<li>2 œufs</li> +<li>Du sel et du poivre</li> +</ul> +</dd> +<dt><b>La procédure :</b></dt> +<dd> +<ol> +<li>Mélangez vaguement les ingrédients secs</li> +<li>Ajoutez-y les autres</li> +<li>Mélangez pendant 10 minutes</li> +<li>Mettez-y au four à 300° pendant une heure</li> +</ol> +</dd> +<dt><b>Remarque :</b></dt> +<dd>Cette recette peut être améliorée en y ajoutant des raisins.</dd> +</dl> </body> </section> @@ -451,17 +582,16 @@ <p> 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 +document par l'utilisation de liens hypertextes. Vous pouvez créer un lien pointant vers le <uri link="#doc_chap1">chapitre un</uri> en tapant <c><uri -link="#doc_chap1">chapitre un</uri></c>. Pour pointer vers la <uri +link="#doc_chap1">chapitre un</uri></c>. Pour pointer vers la <uri link="#doc_chap1_sect2">deuxième section du chapitre un</uri>, tapez <c><uri link="#doc_chap1_sect2">deuxième section du chapitre un</uri></c>. Pour créer un lien vers la figure 3 du chapitre 1, vous utiliseriez <c><uri link="#doc_chap1_fig3">figure 1.3</uri></c> et pour vous référer à l'<uri link="#doc_chap2_pre2">exemple de code 2 du chapitre 2</uri>, vous utiliserez <c><uri link="#doc_chap2_pre2">exemple de code 2 du chapitre -2</uri></c>. Nous ajouterons bientôt d'autres fonctionnalités de -liaisons automatiques (comme le support des tableaux). +2</uri></c>. </p> <p> @@ -483,6 +613,54 @@ </body> </section> +<section> +<title>Annonces et documents obsolètes</title> +<body> + +<p> +L'attribut <c>disclaimer</c> 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 : +</p> + +<ul> +<li> +<b>articles</b> sert pour les <uri link="/doc/en/articles/">articles +reédités</uri> +</li> +<li> +<b>draft</b> sert à indiquer que le travail sur le document n'est pas terminé +et qu'il ne doit pas être considéré comme officiel. +</li> +<li> +<b>oldbook</b> est utilisé pour indiquer qu'un manuel est vieux et n'est plus +entretenu. +</li> +<li> +<b>obsolete</b> est utiliser pour indiquer qu'un document est obsolète. +</li> +</ul> + +<p> +Lorsque vous marquez un document comme obsolète, il est de bon aloi de mettre +un lien vers la nouvelle version. L'attribut <c>redirect</c> fait justement cela. +L'utilisateur devrait être automatiquement redirigé vers la nouvelle page, mais +vous ne devez pas compter uniquement là-dessus. +</p> + +<pre caption="Exemple d'annonce"> +<?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"> +... +</pre> +</body> +</section> </chapter> <chapter> @@ -493,7 +671,7 @@ <p> Puisque le projet de documentation de Gentoo est un effort commun, il est -probable que plusieurs personnes doivent modifier un même document. Il +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 @@ -501,7 +679,7 @@ </p> <p> -Ces deux aspects sont décris ci-dessous. +Ces deux aspects sont décrits ci-dessous. </p> </body> @@ -531,20 +709,25 @@ La longueur des lignes <b>doit</b> être limitée à 80 positions sauf à l'intérieur de la balise <c><pre></c>. 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. +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 <c><pre></c> pour faciliter la lecture aux utilisateurs en +mode console. </p> <p> L'<b>indentation</b> est proscrite, sauf à l'intérieur des balises <c><tr></c> (d'une <c><table></c>), <c><ul></c>, -<c><ol></c> et <c><author></c>. Si l'indentation est utilisée, elle -<e>doit</e> être de deux espaces par indentation, c-à-d. <e>pas</e> de -tabulation <e>ni</e> plus d'espaces. +<c><ol></c>, <c><dl></c> et <c><author></c>. Si l'indentation +est utilisée, elle <e>doit</e> être de deux espaces par indentation, c-à-d. +<e>pas</e> de tabulation <e>ni</e> plus d'espaces. En outre, les tabulations ne +sont pas autorisées dans les documents GuideXML. </p> <p> Si un saut de ligne est nécessaire à l'intérieur des balises <c><ti></c>, -<c><th></c> ou <c><li></c>, leur contenu doit alors être indenté. +<c><th></c>, <c><li></c> ou <c><dd></c>, leur contenu doit +alors être indenté. </p> <p> @@ -574,7 +757,7 @@ <p> Les <b>attributs</b> doivent être définis sans espace entre le nom de l'attribut, -le signe "=" et la valeur de l'attribut. Voici un exemple : +le signe « = » et la valeur de l'attribut. Voici un exemple : </p> <pre caption="Attributs"> @@ -589,9 +772,10 @@ <body> <p> -À l'intérieur des tables (<c><table></c>) et des listes (<c><ul></c> et -<c><ol></c>), 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. +À l'intérieur des tables (<c><table></c>) et des listes (<c><ul></c>, +<c><ol></c> et <c><dl></c>), 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. </p> <note> @@ -606,7 +790,8 @@ <pre caption="Points et majuscules"> <ul> - <li>Pas de point</li><comment>(Le point est utilisé en français.)</comment> + <li>Pas de point</li><comment>(Le point est utilisé en français.) +</comment> <li>Un point. Plusieurs phrases, vous vous rappelez ?</li> </ul> </pre> @@ -647,7 +832,7 @@ <p> Le format actuel ne permettait pas de produire des documents plus volumineux tels que le <uri link="/doc/fr/handbook/handbook-x86.xml?part=1">manuel -d'installation</uri>. Le format GuideXML a donc été étendu pour permettre la +d'installation</uri>. Le format GuideXML a donc été étendu pour permettre la rédaction de documents sur plusieurs pages. </p> @@ -786,7 +971,7 @@ é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 Linux de qualité. N'hésitez pas à consulter nos <uri +Gentoo de qualité. N'hésitez pas à consulter nos <uri link="/proj/fr/gdp/doc/doc-tipsntricks.xml">trucs et astuces du documentaliste</uri>. Si vous voulez aider (ou si vous avez des questions sur Guide), envoyez un message en anglais sur la <mail