Usage pour le HTML des pages du site de Debian

Cette page est actuellement une version de travail.

Préface

Cette page est là pour aider les auteurs et les traducteurs à créer des pages correctement formatées. Elle contient des conseils sur l'utilisation des balises et sur la manière de créer de nouvelles pages et de les rendre plus faciles à traduire.

Quelques conseils généraux

Voici une liste de conseils généraux pour les nouvelles pages ou les traductions.

Ne pas utiliser de longues lignes
Les lignes des fichiers wml et des autres fichiers ne devraient pas dépasser la taille d'un terminal standard. C'est plus facile à éditer sous vi, il est plus simple d'y faire des recherches et plus aisé à traduire. C'est également important car CVS est orienté lignes et qu'il est plus difficile de résoudre des conflits dans de longues lignes.
Placer les balises sur des lignes séparées si possible
La plupart des balises HTML peuvent être placées sur des lignes séparées comme par exemple <div>, <p>, <table> et <ul>. Pour faciliter les choses aux traducteurs, vous devriez placer toutes les balises qui peuvent être utilisées de cette façon sur des lignes séparées. Sinon les traducteurs pourraient effacer accidentellement ces balises et oublier de les remettre dans leur traduction.
Ne pas utiliser d'espaces ou de sauts de lignes dans les balises situées dans le texte
Certaines balises produisent un espace si elles sont placées sur des lignes séparées. Par exemple la balise <q> utilisée pour de courtes citations et de courts extraits. Vous ne pouvez les séparer sur une ligne que comme un tout avec leur contenu, sinon il pourrait y avoir un espace entre le contenu et la balise dans la page HTML. À l'intérieur de ces balises vous pouvez avoir autant de sauts de lignes ou d'espaces que vous le souhaitez entre les mots.

Abréviations et acronymes

Pour les abréviations et les acronymes, la balise HTML <acronym> devrait être utilisée. Il y a deux raisons pour ne pas recommander l'utilisation de la balise <abbr> : d'abord tous les navigateurs ne la gèrent pas et ensuite les définitions d'un acronyme et d'une abréviation sont incohérentes (N. d. T. : en anglais peut-être, mais pas en français).

Un acronyme devrait être ajouté à la page avec la syntaxe suivante : <acronym lang="code de langue" title="Définition complète de l'acronyme">ACRONYME</acronym>. Le titre devrait contenir la totalité des mots prononcés. Les lettres des mots devraient être capitalisées selon l'usage français. L'attribut « lang » n'est requis que si l'acronyme ou l'abréviation est en langue étrangère.

Il y a déjà un ensemble d'acronymes usuels dans les modèles wml à utiliser dans vos pages, vous devriez ajouter une ligne pour utiliser les acronyms dans le fichier wml. Par exemple, la balise wml pour DD est <acronym_DD />.

Citations et extraits

Il existe plusieurs règles différentes sur ce qu'est une citation ou un extrait pour différentes langues. Si vous avez une courte citation dans le texte, vous devriez utiliser la balise <q>. L'affichage du contenu est géré par la feuille de style de la langue. Les balises <q> ne devraient pas avoir d'espace ou de saut de ligne entre la balise ouvrante ou fermante et le contenu.

Pour des citations plus longues, la balise <blockquote> devrait être utilisée. Une balise <blockquote> délimite un ou plusieurs paragraphes de texte qui sont marqués par <p>. Veuillez ne pas utiliser les balises <blockquote> pour centrer un bloc de texte qui n'est pas une citation. Les blockquotes sont exclusivement réservés aux citations et seront affichés par une feuille de style spécifique à la langue à l'avenir.

Il existe également une balise <cite> en HTML. Cette balise <cite> n'est pas utilisée pour le texte de la citation lui-même. Elle est utilisée pour la source de la citation. Ce peut être le nom de la personne citée ou une URL si elle est ajouté comme attribut dans une balise <blockquote>.

Noms de programmes et code

Pour les noms de programmes et le code informatique, il existe une balise nommée <code>. Les navigateurs devraient normalement savoir comment afficher le code et les noms de programmes, mais l'affichage peut aussi être modifié par une feuille de style. Utiliser <tt> n'est pas une bonne idée car cela ne renseigne pas sur le contenu.

Exemples d'affichages d'ordinateur

Pour les affichages d'ordinateur à l'écran, il existe une balise spéciale nommée <samp>. Si vous avez un grand bloc d'affichage, vous devriez également regarder dans le fichier de feuille de style si une classe particulière existe.

Saisie au clavier

S'il y a des exemples où l'utilisateur doit saisir quelque chose au clavier, la balise <kbd> devrait être utilisée pour la saisie de l'utilisateur. Veuillez également vous reporter au chapitre sur les variables pour savoir comment baliser les saisies variables.

Variables

Parfois, il est nécessaire d'indiquer qu'une entrée variable telle qu'une adresse IP particulière ou un nom d'utilisateur doit être fournie à un programme sur la ligne de commande. Pour ces entrées variables, la balise <var> devrait être utilisée.

Contenu préformaté

La balise <pre> ne devrait être utilisée que pour le texte préformaté. La longueur des lignes, les espaces et d'autres choses seront préservés. Naturellement, cette balise ne peut pas contenir la plupart des autres balises HTML.

Images

Si des images sont ajoutées à la page, il n'est pas nécessaire d'ajouter un attribut border=0 invalide. Mais, si possible, la taille de l'image et un attribut alt devraient être ajoutés. La taille devrait être ajoutée par wml si elle n'est pas présente mais cela demande du temps de compilation. L'attribut alt devrait contenir quelque chose qui explique aux utilisateurs navigant avec lynx et aux aveugles ce que contient l'image.