Trucs et astuces pour le développement de la documentation1. Vérification des fichiers du site web 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.
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 :
Pour mettre à jour votre copie du dépôt CVS, exécutez cvs update -dP dans le répertoire gentoo/xml. 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 Notre GuideXML est transformée en HTML par le paquet www-servers/gorg. Vous avez besoin de l'installer.
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 :
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> :
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 :
Pour tester un guide Gentoo, utilisez xmllint (qui se trouve dans dev-libs/libxml2) pour vérifier si sa syntaxe XML est valide :
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 :
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.
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. 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 :
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). 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 ! 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. 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. Ce document est protégé par la licence Creative Commons : Paternité - Partage des Conditions Initiales à l'Identique 2.5. |
|
