Du code dans vos pages web !

Sur ce blog comme c’est le cas sur beaucoup d’autres sites traitant de programmation, je suis souvent amené à publié des snippets de code source ou des dialogues homme – machine (des successions de commandes). HTML et XHTML disposent de balises dédiées à cette tache particulière qui sont malheureusement trop souvent ignorées alors qu’elles ont une forte valeur sémantique. Elles sont vieilles comme le web et supportées par tous les navigateurs les plus populaires.

Quels avantages ?

Structurer correctement l’information contenu dans les pages internet permet aux logiciels (robots des moteurs de recherches, …) de plus facilement lui donner un sens et déterminer sa nature. Une application concrète pourrait être la création d’un moteur de recherche de code source et de snippets à la Google Code utilisant les balises présentées ci-dessous pour déterminer le type d’articles et le langage utilisé. A l’échelle d’un blog comme le mien, on pourrait aisément mettre en place un système de coloration syntaxique (qui est en fait déjà développé) ou encore un agrégateur de snippets.

De manière plus pragmatique, utiliser le bon élément associé au type de donnée à représenter (code source, saisie clavier, sortie d’un programme, …) permet de simplement styler la page via les CSS pour en facilité la lecture (exemple : les entrées utilisateur en bleu, les sorties système en vert, …).

Intégrer le code source d’un programme

Comme son l’indique, la balise code permet d’afficher du code source. Combinée à la balise pre qui permet d’afficher du texte préformaté, elle est tout à fait adapté à des blocs de code :

<pre><code class="language-c">#include <stdio.h>

int main() {
  printf("Bienvenue sur Lapin Blanc !\n");
  return 0;
}</code></pre>

Ce qui donnera :

#include <stdio.h>

int main() {
  printf("Bienvenue sur Lapin Blanc !\n");
  return 0;
}

La spécification HTML actuelle ne précise aucun moyen d’indiquer le langage de programmation dans lequel est écrit le code. Nous utilisons ici la convention présente dans le brouillon de HTML 5 (qui reste tout à fait valide en HTML 4.01 et XHTML 1.1) qui consiste à ajouter à la balise code un attribut class dont la valeur commence par language- et se termine par le nom du langage de programmation utilisé en toutes lettres : par exemple pour du C# nous utiliserons language-c-sharp. Comme nous le verrons plus bas, cette convention pourra être utilisée pour activer la coloration syntaxique.

Une autre balise peut être utile, plus spécifiquement lors de la publication de formules mathématiques ou d’algorithmes : il s’agit de var qui permet de représenter une variable.

Tant que la variable <var>x</var> vaut vrai, on boucle.

Ce qui donne : Tant que la variable x vaut vrai, on boucle.

Représenter un dialogue homme – machine

Dans des tutoriels comme celui présentant l’installation d’une solution LAMP sur un serveur Gandi, il est nécessaire de retranscrire un grand nombre d’interactions avec le système. Généralement la saisie de commandes et la sélection d’items dans les menus.

Deux balises sont prévues à cet effet : samp et kbd. Le premier (issue de sample) représente la sortie d’un programme tandis que le second (pour keyboard) spécifie les entrées utilisateurs.

Un petit exemple de leur utilisation avec la saisie de la commande uname dans le terminal de Mac OS X :

<pre><samp>Welcome to Darwin!
<samp class="prompt">Crokette:~ keyes$</samp> <kbd>uname -a</kbd>
Darwin Crokette.local 8.11.1 Darwin Kernel Version 8.11.1: Wed Oct 10 18:23:28 PDT 2007; root:xnu-792.25.20~1/RELEASE_I386 i386 i386
<samp class="prompt">Crokette:~ keyes$</samp> <samp class="cursor">_</samp></pre>

Ce qui rendra :

Welcome to Darwin!
Crokette:~ keyes$ uname -a
Darwin Crokette.local 8.11.1 Darwin Kernel Version 8.11.1: Wed Oct 10 18:23:28 PDT 2007; root:xnu-792.25.20~1/RELEASE_I386 i386 i386
Crokette:~ keyes$ _

Comme vous pouvez le voir, nous utilisons des balises samp et kbd au sein d'une balise samp ce qui nous permettra de le styler simplement à l'aide de CSS et rendre la lecture de cette interaction beaucoup plus claire pour l'utilisateur (par exemple à l'aide d'un code couleur pour les entrées/sorties).

Le brouillon de la spécification de HTML 5 définie plusieurs sortes d’agencement possibles pour les balises samp et kbd :

The kbd element represents user input (typically keyboard input, although it may also be used to represent other input, such as voice commands).

When the kbd element is nested inside a samp element, it represents the input as it was echoed by the system.

When the kbd element contains a samp element, it represents input based on system output, for example invoking a menu item.

When the kbd element is nested inside another kbd element, it represents an actual key or other single unit of input as appropriate for the input mechanism.

En voici une libre traduction :

L’élément kbd représente une entrée utilisateur (généralement une saisie clavier, bien qu’il puisse représenter d’autres entrées, tels que des commandes vocales).

Quand l’élément kbd est imbriqué dans un élément samp, il représente la saisie telle qu’elle a été affichée par le système.

Quand l’élément kbd contient un élément samp, il représente une entrée basé sur une sortie du système, par exemple pour appeler un item de menu.

Quand l’élément kbd est imbriqué dans un autre élément kbd, il représente la touche ou unité d’entrée équivalente utilisable avec le mécanisme d’entré.

La coloration syntaxique

Nous l’avons vu, styler via CSS les éléments présentés précédemment permet de simplifier la lecture de nos articles. Concernant les codes sources publiés, n’importe quel développeur ayant utilisé autre chose que notepad.exe comme éditeur de texte vous le confessera : la coloration syntaxique est un plus indéniable pour la lecture et la compréhension.

Plusieurs logiciels permettent d’activer la coloration syntaxique sur vos pages webs :

• GeSHi est l’un des plus populaires et performant. Écrit en PHP, il supporte de nombreux langages mais à la désavantage de coloré le code coté serveur et de détruire à la conversion tous le soin que vous aurez apporté au balisage de votre page web…
• SyntaxHiglighter est lui un script JavaScript qui colorera le code à sa manière pour les lecteurs humains mais le préservera dans sa forme originelle pour tous les robots et autres terminaux ne supportant pas JavaScript. J’ai créé un tout petit patch afin de le rendre plus ou moins compatible avec les standards présentés dans cette article. (C’est celui qui est utilisé sur ce blog actuellement).
• Ajax Syntax Highlighter est la solution hybride que je développe. Un script JavaScript côté client détecte les snippets inclus dans la page et les envoi côté serveur pour être colorés (pour l’instant à l’aide de GeSHi). Comme SyntaxHighlighter (dont il reprend une partie de la CSS), il dispose d’une fonction “voir comme texte”. (Ce projet n’est pas encore publié, il le sera d’ici très peu de temps).

Ce billet s’inspire en parti de l’article Lesser-know semantic elements disponible sur l’excellent centre de ressource Opera Web Standard Curriculum.