Travailler sur les pages du site Debian

Informations générales

Ressources nécessaires

Si vous voulez travailler sur notre site web, vous devez vous préparer à accueillir au moins 250 Mo de données sur votre disque dur. Ce chiffre reflète l'état actuel de l'archive. Si vous reconstruisez (accidentellement) toutes les pages, vous aurez au moins besoin du double de place. Et si vous ne récupérez qu'une partie des sources, vous aurez besoin de nettement moins d'espace, par exemple 50 Mo pour le répertoire english/.

Récupération partielle

Beaucoup de personnes n'auront pas besoin de toute l'arborescence CVS sous webwml, ce qui peut occasionner des fichiers manquants et entraîner des erreurs à la compilation, au cas où un fichier important a été ajouté et qu'on n'a pas fait de cvs update dans le répertoire. Veuillez vérifier que vous avez bien tous les fichiers nécessaires (comme les fichiers .wmlrc) avant de vous plaindre à nous.

Que sont ces lignes commençant par « # » ?

Avec wml, les lignes commençant par « # » sont des commentaires. Ils sont utilisés de préférence aux commentaires HTML, car ils n'apparaissent pas dans le code produit.

Veuillez lire la page sur l'utilisation de WML pour plus d'informations sur WML.

Consignes pour les éditeurs

Puis-je modifier la version anglaise ?

Cela dépend. Si vous voyez une petite erreur, comme une faute de frappe, corrigez-la.

Si vous vous rendez compte qu'une information est manquante, vous pouvez aussi la corriger.

Si vous pensez que quelque chose ne va pas et doit être réécrit, dites-le sur debian-www afin que cela soit discuté. Nous serons certainement d'accord avec vous.

Si vous remarquez un problème dans un fichier modèle (c'est-à-dire un fichier dans le répertoire webwml/english/template/debian), réfléchissez à deux fois avant de le corriger, parce que les changements dans ces fichiers entraînent souvent la reconstruction d'une grande partie du site.

Quand vous ajoutez de nouveaux répertoires, ajoutez aussi le Makefile !

Il faut faire attention quand on ajoute un nouveau répertoire au CVS. Si le répertoire courant est indiqué dans ../Makefile, alors il faut créer un Makefile dans ce répertoire ; sinon make affichera un message d'erreur.

Utilisez un anglais simple et clair.

Comme le site Debian est consulté par des personnes dont l'anglais n'est pas la langue maternelle et qu'il est traduit dans d'autres langues, il est préférable d'écrire avec un anglais simple et clair et d'éviter l'argot, les idiomes et le vieil anglais.

Si vous en utilisez néanmoins, ajoutez un commentaire au fichier source expliquant le sens de la phrase.

Cherchez le README dans les répertoires anglais.

Certains répertoires contiennent un fichier README qui peut vous aider à comprendre comment ce répertoire est organisé. Il peut fournir des informations utiles lorsqu'on travaille dans un tel répertoire.

Envoyez séparément les modifications concernant le contenu et celles traitant de la mise en forme.

Réalisez toujours des rustines différentes ou des envois différents pour les changements relatifs au contenu et les changements relevant de la mise en page. Lorsque ces changements sont combinés, il est plus difficile pour les traducteurs d'identifier les différences. En lançant un cvs diff sur des changements qui contiennent les deux types de modifications, vous pourrez vous rendre compte de l'ampleur du problème.

De manière générale, évitez les changements aléatoires de mise en forme. Il ne faut pas modifier des parties existantes des pages pour les rendre compatibles avec XHTML/XML et en même temps, apporter d'autres modifications. Bien évidemment, les ajouts devraient dès le départ être écrits proprement.

Si possible, mettez également à jour les traductions.

Certains changements sont indépendants de la langue utilisée dans le fichier WML, comme des changements dans des URLs ou dans du code Perl inclus. Corriger les erreurs typographique entre également dans la même catégorie car les traducteurs ont pour habitude de les ignorer lors de la traduction. Pour tous ces changements indépendants de la langue, vous pouvez faire le même changement dans tous les fichiers traduits sans connaître réellement les autres langues et incrémenter de manière sécurisée la version dans les en-têtes translation-check.

Il n'est pas très difficile pour les traducteurs de faire le même travail eux-mêmes et il peut être peu pratique pour les éditeurs anglophones d'avoir un export complet sur lequel opérer. Cependant, nous encourageons toujours les personnes à le faire pour éviter de demander à deux douzaines de personnes de faire quelque chose qui pourrait être rapidement fait par une seule personne.

De plus, pour rendre de telles modifications plus faciles à appliquer, vous pouvez utiliser le script smart_change.pl du répertoire de plus haut niveau dans le module CVS webwml.

Utilisation de smart_change.pl

smart_change.pl [options] origfile

Actuellement, seuls les fichiers de /english/ sont autorisés comme origfile. smart_change.pl utilise les arguments suivants :

-s, --substitute=REGEXP
Spécifie une expression rationnelle Perl à appliquer aux fichiers source (peut être utilisée plusieurs fois). Par exemple : 
         $> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
         $> cvs diff -u */devel/index.wml | less
         $> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wml
La première commande effectue le changement, la deuxième vérifie le fichier original anglais et toutes ses traductions. Il est conseillé de faire cela pour vérifier les changements réels avant de les valider. Si tout vous semble correct, validez vos changements avec la troisième commande.
-l, --lang=STRING
Traite la langue (peut être utilisé plusieurs fois). Si aucune langue n'est spécifiée, toutes les langues disponibles sont traitées.
-n, --no-bump
N'incrémente pas les numéros de version dans les en-têtes translation-check. Normalement, le numéro de version de chaque en-tête translation-check est incrémenté d'un dans les fichiers traduits qui sont à jour et n'est pas modifié dans ceux qui ne sont pas à jour. Si cette option est spécifiée, aucun en-tête translation-check n'est modifié. Voir Maintenir les traductions à jour pour une explication sur les en-têtes translation-check.
-p, --previous
Affiche la précédente révision CVS. Ceci est principalement utile quand les fichiers anglais ont déjà été validés et que vous voulez vérifier les en-têtes translation-check par rapport à la version précédente.
-h, --help
Affiche un court message d'information sur l'utilisation.
-v, --verbose
Affiche des messages verbeux lors de l'exécution.

Liens

Ce lien ne semble pas marcher, dois-je le changer ?

À cause de la façon dont les serveurs web sont configurés (utilisant la négociation de contenu), vous ne devriez pas avoir besoin de changer les liens du site. En fait, nous vous suggérons de ne jamais le faire. Écrivez à debian-www si vous pensez qu'un lien est cassé avant de le changer.

Correction des liens

Si vous trouvez un lien vers un site externe qui renvoie une redirection (301, 302, redirection par <meta> ou une page indiquant This page has moved.), merci de le signaler sur debian-www.

Si vous trouvez un lien cassé (404, 403, ou une page qui n'est manifestement pas celle indiquée dans le lien), veuillez le corriger et en informer debian-www afin d'avertir les traducteurs. Ou alors corrigez aussi le lien pour toutes les traductions, en faisant attention de mettre à jour la ligne #use wml::debian::translation-check.

Que sont ces fichiers truc.def et truc.data ?

Afin de faciliter la maintenance des traductions, nous séparons les parties génériques (données) du texte sur certaines pages. Les traducteurs ne doivent copier et traduire que la partie textuelle, les données seront ajoutées automatiquement.

Un exemple peut être utile à mieux comprendre ; plusieurs fichiers sont nécessaires pour générer la liste des vendeurs dans CD/vendors :

index.wml :
Le texte en haut de la page sur les vendeurs est dans ce fichier. Une traduction devrait être placée dans votre répertoire.
vendors.CD.def :
Celui-ci contient tous les morceaux de texte qui sont nécessaires à chaque entrée dans la liste. Les traductions sont mises dans le fichier <langue>/po/vendors.xy.po.
vendors.CD :
Ce fichier contient les données relatives aux vendeurs, qui sont indépendantes de la langue, il ne doit donc pas être traduit.

Lorsqu'une des personnes derrière cdvendors@debian.org ajoute un nouveau vendeur, elle l'ajoute dans debiancd.db, fait la conversion au format WML dans le fichier vendors.CD (avec le programme getvendors.pl), et ensuite laisse WML et les Makefiles faire leur travail. Toutes les traductions seront reconstruites à partir du texte actuellement traduit, mais avec les données pour le nouveau vendeur (une mise à jour gratuite ! :-)

Ajouter de nouvelles pages

Ajouter de nouvelles pages à Debian est assez facile. Tout le travail consistant à mettre le bon en-tête et le bon pied de page est déjà fait en utilisant WML. Tout ce que vous avez besoin de faire est d'inclure une ligne telle que la suivante en haut d'un nouveau fichier :

#use wml::debian::template title="TITRE DE LA PAGE"

suivi du corps de la page. Toutes les pages devraient utiliser le fichier modèle wml::debian::template sauf si elles en utilisent un spécial créé uniquement pour leur section, comme par exemple les pages des nouvelles ou celle sur la sécurité.

Les modèles que nous utilisons vous permettent de définir certaines variables qui affecteront les pages créées. Cela devrait éviter d'avoir à créer des modèles différents pour chaque situation et permettre que les améliorations soient plus faciles à mettre en œuvre. Les variables disponibles actuellement et leurs fonctions sont :

BARETITLE="true"
Supprime la partie « Debian GNU/Linux -- » qui est habituellement ajoutée au début des balises <title>.
NOHEADER="true"
Enlève l'en-tête initial de la page. Un en-tête spécial peut, bien entendu, être inclus dans le corps.
NOMIRRORS="true"
Enlève la liste des miroirs de la page. Il n'est généralement pas recommandé de l'utiliser, à part pour quelques pages.
NOHOMELINK="true"
Enlève le lien en bas de la page qui permet de revenir à la page Debian principale.
NOLANGUAGES="true"
Enlève les liens en bas de la page vers les versions dans d'autres langues.
GEN_TIME="true"
Met dans le fichier résultat la date de génération du fichier au lieu de la date de modification du fichier source.
NOCOPYRIGHT="true"
Enlève la note de copyright en bas de la page.

Notez que vous pouvez utiliser n'importe quelle chaîne de caractères dans ces variables : true, yes, foo, cela ne change rien.

Un exemple d'utilisation de tout cela se trouve dans les pages sur les portages qui ont leurs propres en-têtes ; ports/arm/index.wml utilise :

#use wml::debian::template title="Portage ARM" NOHEADER="yes"

Si vous voulez faire quelque chose qui ne peut être fait en utilisant les modèles existants, envisagez d'abord d'étendre l'un d'entre eux. S'il n'est pas possible d'étendre l'un d'eux d'une manière compatible avec l'existant, essayez de vous arranger pour que le nouveau modèle soit un surensemble d'un modèle existant de façon à ce que les pages puissent être converties à lui lors du passage à la prochaine version majeure (avec un peu de chance jamais plus de tous les 6 mois).

Si vous créez une page qui est générée par un script ou qui contient peu de texte, envisagez d'utiliser les balises <gettext> pour faciliter la maintenance des traductions.

Inclusion d'autres fichiers

Si vous voulez séparer certaines parties de votre page dans un fichier distinct (qui sera alors inclus dans votre fichier principal), utilisez l'extension .src si votre fichier contient un contenu qui doit être traduit ; votre fichier inclus sera alors suivi pour les changements comme un fichier .wml ordinaire. Si vous utilisez une autre extension, comme .inc, les traducteurs ne remarqueront pas vos mises à jour et il se peut que différentes langues fournissent des contenus différents.

Ajouter un nouveau répertoire

Note : ne pas créer de répertoire ayant pour nom install. Cela dérange make et les pages de ce répertoire ne seront pas mises à jour automatiquement.

Ci-dessous se trouve un exemple d'ajout de nouveau répertoire au site web.

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

Éditez le Makefile dans le répertoire parent et ajoutez le répertoire que vous venez de créer à la variable SUBS. Cela ajoutera ce répertoire lors de la prochaine compilation quand make est lancé.

Enfin, enregistrez tous les changements effectués avec

  cvs commit Makefile foo