Gentoo Logo

Trucs et astuces pour le développement de la documentation

Table des matières :

1.  Vérification des fichiers du site web

Utilisation du CVS anonyme

Les contributeurs devront utiliser notre serveur CVS anonyme. Il contient les mêmes fichiers que le serveur officiel de Gentoo que les développeurs utilisent. Le dépôt CVS anonyme est mis à jour toutes les heures.

Créez un répertoire dédié au développement de la documentation, puis récupérez les fichiers du serveur.

Exemple de code 1.1 : Récupération des fichiers du serveur

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

Pour mettre à jour votre copie du dépôt CVS, exécutez cvs update -dP dans le répertoire gentoo/xml.

Dépôt pour les développeurs Gentoo

Si vous n'avez pas encore récupéré le module gentoo, faites-le ainsi :

Exemple de code 1.2 : Récupération du module gentoo

$ export CVSROOT=<votre pseudo>@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo/xml

Pour mettre à jour votre copie du dépôt CVS, exécutez cvs update -dP dans le répertoire gentoo/xml.

Dépôt CVS en ligne

Vous pouvez utiliser notre dépôt CVS en ligne pour déterminer les différences entre des versions d'un même document. Le dépôt principal pour les documents en anglais est intégralement disponible. Notez que le dépôt CVS en ligne est mis à jour toutes les heures.

2.  Paramétrage de votre environnement local

Installation de gorg

Notre GuideXML est transformée en HTML par le paquet www-servers/gorg. Vous avez besoin de l'installer.

Note : Vous avez besoin au minimum de la version gorg-0.6.3. Vous devrez l'ajouter dans votre fichier /etc/portage/package.keywords pour votre architecture.

Suivez les instructions de la page de gorg pour le configurer. Vous devez définir le répertoire web racine où vous avez récupéré notre dépôt CVS (.../gentoo/xml/htdocs). Les autres paramètres ne sont utiles que si vous voulez fournir une copie locale de www.gentoo.org.

Paramétrage de votre environnement XML

Votre système a besoin de savoir où trouver l'emplacement des DTD que notre documentation utilise. Éditez le fichier /etc/xml/catalog en tant que super utilisateur et ajoutez la ligne suivante :

Exemple de code 2.1 : Addenda à /etc/xml/catalog

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Note : Vous pouvez également réécrire vers le chemin où les DTD ont été récupérées du CVS.

Si votre fichier /etc/xml/catalog est vide ou ne contient aucune entrée, vous devez insérer l'élément <rewriteURI> à l'intérieur de l'élément <catalog> :

Exemple de code 2.2 : Exemple de /etc/xml/catalog

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

De plus, certains fichiers utilisent parfois une URL vers la DTD du site Gentoo, par exemple http://www.gentoo.org/dtd/guide.dtd. Vous pouvez aussi récrire de telles URL vers des fichiers locaux pour éviter les accès au net qui sont évidemment plus lents au moment de la validation :

Exemple de code 2.3 : Ajouter une redirection à /etc/xml/catalog

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Test d'un guide Gentoo

Pour tester un guide Gentoo, utilisez xmllint (qui se trouve dans dev-libs/libxml2) pour vérifier si sa syntaxe XML est valide :

Exemple de code 2.4 : Utiliser xmllint pour vérifier GuideXML

$ xmllint --valid --noout alsa-guide.xml

Si xmllint se termine sans afficher quoi que ce soit, cela indique que la structure du fichier est valide. La prochaine étape est la conversion du fichier en HTML :

Exemple de code 2.5 : Conversion en HTML

$ gorg < alsa-guide.xml > alsa-guide.html

Si aucune erreur n'est affichée, vous devriez pouvoir pointer votre navigateur vers alsa-guide.html pour consulter le document résultant de la conversion. Dans tous les autres cas, vous devrez corriger votre guide jusqu'à ce qu'il fonctionne convenablement.

Note : Dans les chapitres du Manuel Gentoo, les liens vers les autres chapitres ne seront pas générés parce que les versions en ligne accèdent à des chapitres du Manuel par l'intermédiaire du fichier principal et des paramètres chap et part.

Parcours de votre copie locale du site web de Gentoo

Puisque vous avez récupéré une copie du site web de Gentoo de notre CVS, vous pouvez également utiliser gorg pour parcourir votre copie locale. Assurez-vous d'avoir téléchargé les nouveaux index comme expliqué sur la page de gorg si vous voulez avoir la même page d'accueil.

3.  Foire Aux Questions

Comment puis-je convertir un fichier en UTF-8 ?

De nombreux outils sont disponibles pour cette tâche. Les plus populaires sont app-text/recode ou iconv qui fait partie de sys-libs/glibc.

Recode est vraiment facile d'utilisation. Vous n'avez qu'à lui dire quel codage de caractère est actuellement utilisé par le document et en quel codage vous voulez obtenir le résultat.

Par exemple, pour convertir un document codé en ISO-8859-15 (aussi connu sous le nom « Latin-9 ») en UTF-8, vous pouvez faire :

Exemple de code 3.1 : Réencoder un fichier

      
(l9 = ISO-8859-15, u8 = UTF-8)        
$ recode l9..u8 fichier.xml       

4.  Astuces lors de la soumission d'un document

Vérification de l'élément <guide>

Faites bien attention à ce que l'attribut link="" de l'élément <guide> indique le bon chemin du document. Si votre guide est basé sur les DTD guide ou book, vous pouvez indiquer soit son chemin absolu (exemple : /doc/${LANG}/fichier.xml, recommandé par le GDP, obligatoire pour les traductions), soit son chemin relatif (exemple : chemin.xml).

Vérification des liens

Vous devez vérifier que tous les liens hypertextes de votre document fonctionnent correctement. Pour une traduction, faites pointer les liens vers la version traduite des documents si elle existe (vers l'originale sinon) et assurez-vous que cette version traduite existe bien !

Vérification des tabulations

Les tabulations sont complètement interdites dans les documents GuideXML, sauf cas particulier (par exemple si le document indique à l'utilisateur de taper une tabulation). Pour chercher les tabulations dans un document, tapez : grep "<Ctrl-V><TAB>" fichier.xml. Corrigez toutes les lignes que grep renvoie.

Bugzilla

Lorsque votre document est terminé, il faut le soumettre à validation par l'équipe de documentation GDP sur le Bugzilla. Les informations demandées systématiquement par Bugzilla, telles que votre plate-forme, le résultat du emerge info, les étapes pour reproduire le problème, etc. n'ont aucun intérêt ici. Si vous soumettez une traduction, choisissez plutôt le composant Doc Translations pour votre bogue.

Pour le titre du bogue, vous pouvez utiliser ce format simple : « [fr] New translation: /doc/fr/gnupg-user.xml » en remplaçant « fr » par le code à deux lettres de la langue concernée, « translation » par « document » si ce n'est pas une traduction et le nom du fichier.

Écrivez tout en anglais.

Par défaut, le bogue sera assigné à docs-team@gentoo.org. Ce n'est pas la peine de modifier cette valeur.

Ajoutez vos fichiers au bogue en choisissant le type « plain text (text/plain) », même si c'est un fichier XML. Cochez la case « Patch » lorsque c'est un correctif. Ne mettez jamais une archive tar ou zip contenant tous les fichiers mais ajoutez chaque fichier individuellement en spécifiant juste leur nom dans la case description.

5.  Erreurs fréquentes et dangereuses

Oubli de l'aspect multi-architecture du manuel Gentoo

Les fichiers contenus dans [gentoo]/xml/htdocs/doc/en/handbook qui ne se terminent pas par un suffixe en "-<arch>.xml" sont lus par toutes les versions du manuel, c'est-à-dire que tout ce qui est contenu dans ces fichiers concerne toutes les architectures.

Si vous devez faire des modifications qui concernent votre architecture et si vous avez peur de devoir les placer dans un tel fichier, vous pourriez d'abord demander sur gentoo-doc@gentoo.org comment résoudre ce problème. Parfois, il peut exister une solution qui ne compliquera pas la vie des utilisateurs des autres architectures.

Oubli de la mise à jour de la version et de la date

Conformément aux consignes, vous devez incrémenter la version et mettre à jour la date des documents lorsque vous faites certaines modifications (en fait, pratiquement toutes). Bien que la version soit moins importante (SwifT vous tuera quand même si vous l'oubliez), la date indique à nos utilisateurs quand le document a été mis à jour pour la dernière fois.

Si vous modifiez le contenu d'un document, vous devez alors incrémenter sa version. Les modifications qui n'altèrent pas le contenu (fautes de frappe, ménage dans le XML...) n'ont pas à provoquer un changement de version.

Lorsque vous mettez à jour le Manuel, ne mettez à jour que les dates et versions des fichiers que vous modifiez. Ne mettez pas à jour les fichiers handbook-ARCH.xml à moins que vous n'ayez modifié son contenu.

Une autre erreur fréquente est d'augmenter le numéro de version comme si c'était un nombre décimal. Ce n'est pas le cas. En cas de mise à jour, vous devez remplacer 3.9 par 3.10 et non pas par 4.0 ni par 3.91.



Imprimer

Dernière mise à jour le 8 mars 2007

Une version originale plus récente datée du 6 décembre 2010 existe.

Résumé : Quelques trucs et astuces qui faciliteront le travail des auteurs de documentation Gentoo.

Xavier Neys
Correcteur

Sven Vermeulen
Auteur

Olivier Fisette
Traducteur

Camille Huot
Traducteur

Marion Agé
Traducteur

Donate to support our development efforts.

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