Gentoo Logo

Guide du format XML Metadoc pour Gentoo

Table des matières :

1.  Introduction

Pourquoi MetadocXML est-il nécessaire ?

MetadocXML n'est pas nécessaire, c'est une ressource supplémentaire pour que le projet de documentation Gentoo puisse avoir une traçabilité des documents, même s'ils sont situés en dehors de l'arborescence habituelle [gentoo]/xml/htdocs/doc.

Grâce à MetadocXML, nous pouvons désormais :

  • Suivre les documents qui sont situés dans l'espace web dédié aux projets (/proj) au lieu du dépôt habituel consacré à la documentation (/doc) ;
  • Ranger la documentation dans diverses catégories (ou sous-catégories) avec l'avantage supplémentaire qui est que nous pouvons automatiquement générer une table des matières pour la documentation (entre autres) ;
  • Suivre les membres non officiels des membres d'équipes de documentation (comme par exemple les traducteurs) ;
  • Utiliser des parties de gros documents (les manuels d'installation par exemple) comme étant des guides individuels pour certains sujets bien précis ;
  • Assigner des bogues sur des documents particuliers pour avoir un référencement rapide et avec la possibilité de masquer un document dans le cas où le bogue rencontré est critique ;
  • Vérifier simplement si un fichier traduit est synchronisé avec son équivalent anglais ou non.

Remarquez que le dernier avantage est primitif et ne sera probablement pas préservé. Il existe des outils puissants (comme le script trads-doc de Xavier Neys) qui proposent bien plus de fonctionnalités que MetadocXML n'en propose actuellement.

Les équipes de traductions qui n'utilisent pas encore MetadocXML n'ont pas à s'inquiéter. Ils ne perdent aucune fonctionnalité disponibles actuellement dans la mesure où MetadocXML n'est qu'une sur-couche mise par dessus l'infrastructure actuelle. Aucun changement n'est à faire sur le format GuideXML pour avoir le support de MetadocXML.

Comment fonctionne MetadocXML ?

Un fichier central contient l'ensemble des informations additionnelles sur la documentation qu'il maintient. Nous appelons ce fichier metadoc.xml. Il doit être situé dans votre dépôt principal (/doc/${LANGUE}), même si ce n'est pas une nécessité absolue.

Dans ce fichier seront stockées toutes les informations additionnelles :

  • Membres de l'équipe ;
  • Catégories auxquelles les documents appartiennent ;
  • Fichiers concernés ;
  • Documents concernés ;
  • Bogues concernant un des documents.

En plus du fichier metadoc.xml, vous pouvez également avoir un fichier de table des matières généré dynamiquement (appelé en général index.xml), un fichier donnant un aperçu de l'ensemble des documents (appelé en général list.xml) et un fichier listant l'ensemble des membres, des fichiers et des bogues (appelé en général overview.xml).

2.  Le fichier metadoc.xml

La structure XML

Le fichier metadoc.xml commence par le code habituel d'initialisation d'un fichier XML et les informations d'en-tête CVS de Gentoo :

Exemple de code 2.1 : Initialisation du XML

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

Ensuite commence la déclaration MetadocXML.

Exemple de code 2.2 : Déclaration MetadocXML anglaise

<metadoc lang="en">

Les traducteurs doivent référencer le fichier principal /doc/en/metadoc.xml dans l'attribut parent. Cela permet à metadoc d'identifier les fichiers non traduits et de voir si les versions de l'original et de la version traduite correspondent toujours.

Exemple de code 2.3 : Déclaration MetadocXML pour une traduction française

<metadoc lang="fr" parent="/doc/en/metadoc.xml">

À l'intérieur de l'entité metadoc vous devez déclarer dans l'ordre les entités suivantes :

  • version qui permet de suivre l'évolution du fichier ;
  • members qui déclare tous les membres de l'équipe d'une langue donnée ;
  • categories qui déclare les catégories pouvant être utilisées ;
  • files qui contient la liste des fichiers couverts par le fichier Metadoc ;
  • docs qui contient la liste des documents couverts par le fichier Metadoc ;

L'entité « version »

Le numéro de version est incrémenté quand un document ou un fichier est ajouté, quand un chemin change ou lors de tout changement qui peut avoir un impact pour les traducteurs. Ces derniers peuvent comparer les numéros de version de l'original avec leur traduction pour détecter des changements à appliquer.

L'entité « members »

Dans l'entité « members » vous devez déclarer deux 'types' de membres qui sont : lead (chef d'équipe) et member (membre). Un membre de type lead doit être connu de l'équipe des Relations des Développeurs Gentoo (GDR) dans la mesure où il ne contient que l'information du pseudo du développeur en charge et que celui-ci est vérifié dans la liste des membres de Gentoo. Un membre (type member) peut soit être un développeur Gentoo auquel cas on ne donnera que son pseudo, ou un contributeur.

Dans le cas d'un contributeur, on donne à l'élément member deux attributs : mail (pour son adresse électronique) et fullname (pour savoir qui il est).

Exemple de code 2.4 : Exemple d'utilisation de l'entité « members »

<members>
  <lead>swift</lead>
  <lead>neysx</lead>
  <member>dertobi123</member>
  <member mail="contributeur_gentoo@gmail.com" fullname="Daniel Dupont">dupontd</member>
</members>

L'entité « Categories »

Vous devez déclarer dans l'entité categories des entités cat. Chacune d'entre elle couvre une catégorie. Le paramètre obligatoire id est utilisé pour référencer la catégorie. Vous pouvez également définir un paramètre parent auquel cas la catégorie sera une sous-catégorie d'une autre catégorie.

Dans ce cas, l'attribut parent fait référence à l'attribut id de la catégorie parente.

Exemple de code 2.5 : Exemple d'utilisation de l'entité « categories »

<categories>
  <cat id="faq">Foires Aux Questions</cat>
  <cat id="install">Ressources Liées à l'Installation</cat>
  <cat id="install_guides">Guides d'Installation</cat>
</categories>

L'entité « Files »

L'entité files ne contient que des entités file.

Chaque entité file référence un seul fichier XML. Elle dispose d'un attribut obligatoire id qui doit être vu comme étant la clef primaire pour chercher le fichier. Metadoc comparera le nom du fichier avec l'attribut id dans le fichier parent de metadoc (défini dans l'élément racine) pour vérifier si le fichier est traduit ou non. Les noms de fichier doivent être strictement identiques.

Le fichier metadoc.xml lui-même peut être repris dans la liste. Il est alors affiché en tête de la liste des fichiers (cf. plus bas).

Exemple de code 2.6 : Exemple d'entité « files »

<files>
  <file id="ati-faq">/doc/fr/ati-faq.xml</file>
  <file id="metadoc">/doc/fr/metadoc.xml</file>
</files>

L'entité « Docs »

L'entité docs ne doit contenir que des entités doc.

Chaque entité doc dispose d'un attribut obligatoire id qui doit être vu comme étant la clef primaire pour le document.

Dans chaque entité doc vous devez disposer d'au moins une entité : l'entité fileid qui fait référence à l'attribut id d'une entité file correspondante pour le fichier principal de ce document.

Dans le cas d'un chapitre de manuel d'installation, vous devez faire référence à la page principale du manuel (le fichier XML principal du manuel). L'entité fileid contiendra alors deux paramètres supplémentaires nommés vpart et vchap qui font référence à la partie et au chapitre correspondant de ce document dans le manuel.

Dans l'entité doc deux autres entités sont disponibles :

  • Une ou plusieurs entités memberof faisant référence aux catégories dans lesquelles le document est situé (remarquez que le document peut être dans plusieurs catégories en même temps) ;
  • Une entité bugs contenant une ou plusieurs entités bug. Une entité bug fait référence au numéro de bogue concernant un bogue de ce document dans le bugzilla de Gentoo. Dans le cas d'un bogue majeur vous pouvez ajouter l'attribut stopper="yes" à l'entité bug pour que le document n'apparaisse pas dans la table des matières des documentations.

Exemple de code 2.7 : Exemple d'entité « docs »

<docs>
  <doc id="handbook_x86">
    <memberof>install_guides</memberof>
    <fileid>handbook-x86</fileid>
    <bugs>
      <bug>70753</bug>
    </bugs>
  </doc>
  <doc id="portage-intro">
    <memberof>gentoo_portage</memberof>
    <fileid vpart="2" vchap="1">handbook-x86</fileid>
  </doc>
  <doc id="uml">
    <memberof>sysadmin_general</memberof>
    <fileid>uml</fileid>
  </doc>
</docs>

3.  Les fichiers MetadocXML supplémentaires

La table des matières générée automatiquement

Si vous voulez disposer d'une table des matières générée automatiquement vous devez commencer votre document avec le code suivant :

Exemple de code 3.1 : Table des matières générée Dynamiquement

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Remplacer "/doc/fr/metadoc.xml" par le chemin vers votre
fichier metadoc -->
<dynamic metadoc="/doc/fr/metadoc.xml">
<title>Documentation Gentoo</title>
<intro>

(...)

</intro>

<catid>faq</catid>
<catid>install</catid>

</dynamic>

Entre les balises intro vous pouvez écrire un ou plusieurs chapitres qui apparaîtront toujours en haut de votre page. Vous pourrez par exemple écrire une introduction et quelques informations supplémentaires pour que le lecteur sache qui contacter s'il y a un problème dans une traduction ou pour tout autre problème.

Entre les balises intro vous pouvez utiliser du code GuideXML, en commençant le code à partir de la balise section.

Les balises catid font références aux catégories principales utilisées par la table des matières dynamique. Vous devez lister toutes les catégories racine possibles qui sont déclarées dans votre fichier metadoc. Ne listez pas de catégories qui appartiennent à une autre catégorie.

La liste des documents générée dynamiquement

Une liste de documents générée dynamiquement commence de la même manière que le fichier de table des matières :

Exemple de code 3.2 : Liste des documents générée dynamiquement

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Remplacer "/doc/fr/metadoc.xml" par le chemin vers votre
fichier metadoc -->
<dynamic metadoc="/doc/fr/metadoc.xml">
<title>Liste des documents Gentoo</title>

Contrairement au cas précédent il n'y a pas de balise intro. Vous devez ajouter toutes les catégories principales utilisées par la liste. Pour les différencier de la table des matières (qui affichera également des informations de chaque document) vous devez utiliser les balises list, inclues dans des balises listing :

Exemple de code 3.3 : Liste de catégories

<listing>
  <list>faq</list>
  <list>install</list>
</listing>

Le document de vue d'ensemble généré dynamiquement

Le document de vue d'ensemble commence de la même manière que les deux précédents :

Exemple de code 3.4 : Liste des fichiers générée dynamiquement

<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl"   type="text/xsl"?>

<!-- $Header$ -->

<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">

<!-- Remplacer "/doc/fr/metadoc.xml" par le chemin vers votre
fichier metadoc -->
<dynamic metadoc="/doc/fr/metadoc.xml">
<title>Vue d'ensemble de la documentation</title>

Vous pouvez ici aussi écrire une petite introduction en code GuideXML entre les balises XML intro en commençant à partir de la balise section. Une fois cela fini une simple balise <overview/> suffira.

Exemple de code 3.5 : Balises d'introduction et de vue d'ensemble

<intro>
(...)
</intro>

<overview/>


Imprimer

Dernière mise à jour le 4 avril 2005

Une version originale plus récente datée du 4 septembre 2011 existe.

Résumé : Ce guide a pour objectif d'indiquer aux développeurs comment utiliser le format XML Metadoc qui permet au projet de documentation Gentoo de garder une structure hiérarchique dans la documentation et stocker plus d'informations à propos de chaque document.

Sven Vermeulen
Auteur

Xavier Neys
Correcteur

Clément Varaldi
Traducteur

Donate to support our development efforts.

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