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 :

Ce qui donnera :

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.

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 :

Ce qui rendra :

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.

6 comments

  1. >GeSHi est l’un des plus populaires et performant.

    populaire c’est certain. Par contre performant, c’est assez discutable.. Et le parsing est souvent perfectible (sans parler du code dégeulasse qu’il génère, même si ça s’est arrangé récement)

    Conçernant Ajax Syntax Highlighter, je ne vois vraiment pas trop son intérêt par rapport à une solution full client, ou full serveur. Car là tu combines tout les inconvénients de chacune des deux solutions : ça ne s’exécutera pas coté client si le javascript est désactivé, et il peut y avoir ce temps de latence après affichage de la page, pendant lequel la colorisation se fait (même défaut que la solution full client), ce qui, à cause des requêtes http à faire, sera d’autant plus visible, surtout si la connectivité n’est pas top, et ça ralentira quand même le serveur puisqu’il doit prendre en charge le parsing (même défaut que la solution full serveur). Et ça va d’autant plus ralentir le serveur qu’il va y avoir autant de requête http en plus qu’il y a de bloc de code source à coloriser.

    Bref, quels sont les réèls avantages de Ajax Syntax Highlighter par rapport aux deux autres solutions ?

  2. Alors effectivement, la solution n’est pas parfaite. Selon moi ses principaux avantages sont :
    * Profite de la performance et de l’exhaustivité (nombre de langages supportés) des solutions côté serveur. Je cite GeSHi mais on peut tout à fait utiliser Pygments ou n’importe quel autre highlighter côté serveur avec ma solution.
    * S’exécute côté client ce qui à l’avantage de ne pas polluer le code pour les agents logiciels intéressés à parser le code.
    * Respecte les standards et conventions que je présente dans cet article.
    * Peut tout à fait être inclus dans de simples pages HTML statiques (style readme, faq, …). En cas d’utilisation hors-ligne il n’y aura simplement pas de coloration syntaxique.
    * Permet d’avoir quelques fonctionnalités à la SyntaxHighlighter comme changer à la volée de mode coloré / plain text

    Question ralentissement, effectivement il peut y avoir un léger temps de latence du à la requête HTTP, pas forcément plus gros que celui des solutions full JavaScript qui en plus ont tendances à bloquer toute la page.
    Par contre contrairement à ce que tu avances, quelque soit le nombre de snippets dans la page il n’y a qu’une seule requête d’effectuée. Le script récupère l’ensemble des codes et l’envoi (sérialisé en JSON afin de réduire au maximum le traffic réseau).

    Pour la charge du serveur, si elle devient trop importante on pourrait assez simplement mettre en place un mécanisme de mise en cache du code coloré.

    Après effectivement, une solution vraiment efficace côté serveur et respectant les standards ne serait pas un mal, mais ça me prendrait plus de temps à développer que mon petit script.

Leave a Reply