Afficher du code informatique avec HTML

HTML offre différents éléments pour écrire de la documentation technique. Dans cet article, nous aborderons les éléments HTML qui portent sur la représentation de code informatique.

Prérequis :	Vous devriez au préalable savoir comment créer un document HTML simple.
Objectifs :	Apprendre comment utiliser HTML afin de représenter des entrées saisies par un utilisateur, des sorties produites par un système, du code, du texte simple et des variables.

HTML et l'informatique

HTML a été conçu par des informaticiens et il sert donc particulièrement bien ce domaine. De nombreux éléments HTML sont apparus et/ou ont disparu au cours des années. Ici, nous n'aborderons que ceux qui sont en vigueur actuellement :

Le texte préformaté

Dans un éditeur de texte, la mise en forme s'applique simplement. Il suffit d'utiliser les caractères du clavier, d'appuyer sur la barre d'espace pour indiquer un espace, d'utiliser la touche Entrée pour passer à la ligne, etc. Normalement, chaque lettre a la même largeur et tout est donc bien aligné. Étant donné que ce qui est écrit est écrit avec du texte simple (plain text en anglais), nul besoin de se préoccuper de la couleur du texte, de sa taille de police, de l'italique, etc.

Un navigateur graphique formate le texte en fonction du code HTML et CSS. Cela fait que beaucoup de blancs (les espaces, les tabulations, les sauts de lignes) sont ignorés. Si vous appuyez sur Entrée lorsque vous tapez du code HTML, le navigateur déduira que vous souhaitez bien aligner votre code HTML. En revanche, pour indiquer clairement qu'on souhaite avoir un nouveau paragraphe, il faudra utiliser le bon élément HTML (en l'occurence <p>).

Généralement lorsqu'on écrit un article qui porte sur l'informatique, on veut afficher, dans le navigateur, du texte, tel qu'il serait lorsqu'on le saisit dans un éditeur de texte. Pour ce faire, on utilisera l'élément <pre>. Par défaut, un navigateur graphique affichera le texte contenu dans cet élément avec une police dont tous les caractères ont la même largeur (monospace). Toutefois, vous pourrez adapter la mise en forme à votre gré grâce à CSS. Par exemple, lorsque vous lisez des exemples de code sur MDN, nous utilisons l'élément <pre> (auquel on ajoute quelques couleurs CSS pour améliorer la lisibilité).

On notera qu'on ne peut toujours pas utiliser les caractères réservés (<>&), par exemple :

<pre>
Un éditeur de texte est pratique car il suffit
d'appuyer sur Entrée pour commencer un nouveau
paragraphe, plutôt que d'avoir à utiliser ces
grossières balises &lt;p&gt; et &lt;/p&gt;.
</pre>

Cela donnera le résultat suivant :

Par défaut, votre éditeur de texte laissera les lignes s'allonger jusqu'à éventuellement dépasser de l'écran. Le retour à la ligne automatique peut toutefois être activé dans la plupart des éditeurs pour garder un œil sur tout le contenu.

On aura la même chose avec <pre>. Il existe une propriété CSS intitulée white-space dont la valeur par défaut est nowrap. Si on veut que le retour à la ligne soit automatique, on utilisera la valeur pre-wrap.

Retranscrire du code

Naturellement, tout le texte préformaté n'est pass du code informatique. Lorsque vous mentionnez du code informatique dans votre document, vous devriez utiliser l'élément <code> :

Un des mots-clés les plus importants est <code>this</code>.

Pour indiquer un bloc de code qui s'étend sur plusieurs lignes, vous pouvez imbriquer un élément <code> dans un élément <pre>. Certains script tiers tels que la bibliothèque highlight.js utiliseront ces balises pour ajouter de la coloration syntaxique à vos exemples de code :

<pre><code class="js">
function coucou() {
  console.log('coucou monde !');
}
</code></pre>

Retranscrire des entrées/sorties (I/O)

Les entrées sont les informations qui sont saisies, généralement par les utilisateurs, dans un ordinateur. L'ordinateur traite ces données et renvoie une sortie. On utilise parfois les termes anglais respectifs input et output, voire un acronyme pour désigner l'ensemble : I/O.

Comment retranscrire une sortie informatique

L'élément <samp> indique que l'ordinateur produit un texte :

Ensuite, vous verrez affiché <samp>thomas@mon-ordinateur:~$</samp>.

Comment retranscrire une entrée informatique

L'élément <kbd> était initialement utilisé pour représenter une entrée saisie au clavier (kbd étant pour keyboard qui signifie clavier en anglais). Cependant, aujourd'hui, cet élément peut être utilisé pour représenter d'autres types d'entrées (comme les commandes vocales).

L'élément <kbd> permet de marquer l'entrée attendue :

Saisissez <kbd>ls --color</kbd> sur l'invite du terminal.

Pour indiquer une touche donnée ou une sous-commande particulière, vous pouvez imbriquer <kbd> avec lui-même :

Appuyez sur <kbd><kbd>Ctrl</kbd> + <kbd>C</kbd></kbd> pour arrêter le processus.

Dans cet exemple, le premier élément <kbd> indique la commande entière alors que les éléments imbriqués indiquent les touches à utiliser.

Assembler le tout

Il arrive souvent de combiner <samp> et <kbd>. Par exemple, lorsque l'ordinateur indique des options à l'utilisateur, on pourra imbriquer des éléments <samp> dans des éléments <kbd> :

Ensuite, choisissez <kbd><samp>Oui</samp></kbd> ou <kbd><samp>Non</samp></kbd>

Inversement, quand l'ordinateur indique quoi faire, on pourra imbrique des éléments <kbd> dans des éléments <samp>:

Attendez que l'invite indique, <samp>Appuyez sur <kbd>Entrée</kbd> pour continuer.</samp>

Selon la spécification HTML, il n'est pas nécessaire de jouer profondément sur l'imbrication de ces éléments. L'aspect le plus important de transmettre les informations avec leur sens.

Les variables de programmes ou les variables mathématiques

Dans ce cas, on utilisera l'élément <var>. Les variables peuvent être annotées dans le texte principal mais pas dans les fragments de code.

Cette fonction utilisera deux paramètres,
<var>x</var> et <var>y</var>.

L'élément <var> permet d'écrire des variables pour des formules simples. En revanche, pour les formules complexes, MathML sera beaucoup plus riche et adapté.