Accueil > WordPress > Insérer des exemples de code dans un article WordPress

Insérer des exemples de code dans un article WordPress

Pour un site dont le sujet principal traite de programmation, il est fréquent de devoir ajouter des extraits de code pour illustrer les explications et présenter des exemples. Cependant, leur insertion et leur présentation n’est pas aussi simple à effectuer qu’il n’y paraît, que ce soit sur un site web quelconque ou sur un blog basé sur le moteur WordPress. C’est particulièrement valable si l’on souhaite obtenir un résultat aussi fidèle que possible à l’affichage habituel de ce code dans les logiciels d’édition comme Visual Studio.
Dans la mesure du possible, il faut donc essayer de respecter :

  • L’indentation (retrait du texte) ;
  • La coloration syntaxique ;
  • La police de caractères : à pas fixe pour respecter les alignements ;
  • Les retours à la ligne, en évitant les insertions automatiques pour qu’un copier-coller soit directement utilisable.

Si possible, il faut aussi rendre ces extraits facilement identifiables dans le reste de l’article, et faire très attention au remplacement automatique de certains caractères (les guillemets par exemple). Pas si évident, surtout si l’on débute avec WordPress et que l’on utilise l’éditeur visuel par défaut pour la rédaction des articles. On se rend vite compte que la tâche ne va pas être aussi facile que prévu, en particulier si l’exemple porte sur du XML ou du code HTML, et qu’on se demande alors comment distinguer l’exemple de code HTML du vrai code HTML de l’article !

Cet article a pour but de présenter les différentes méthodes existantes, et les pièges à éviter (dans lesquels je suis à chaque fois tombé…). Il m’a fallut pas mal d’essais avant de trouver une solution qui me permette d’insérer rapidement et simplement des extraits de code dans mes articles sans risquer de devoir tout refaire à chaque modification et avec un rendu visuel le plus proche possible de Visual Studio. Bonne lecture !

 

 

1ère méthode : Avec un éditeur Visuel ou une extension

 

Editeur visuel de WordPress

Parmi les éditeurs visuels les plus courants, comme celui intégré à WordPress ou encore celui de Windows Live Writer, aucun ne propose réellement d’outils pour faciliter l’intégration d’extraits de code. Le premier réflexe est donc d’effectuer un simple copier-coller du code depuis Visual Studio vers un de ces éditeurs visuels, puis d’effectuer la mise en couleur manuellement mot par mot. Séduisante au départ par sa simplicité, cette méthode révèle très vite ses inconvénients : La mise en couleur est pénible et imprécise, les alignements doivent être retravaillés, et certains caractères (comme les guillemets) sont parfois remplacés automatiquement. D’autres problèmes bien plus gênants apparaissent un peu plus tard : Retravailler l’extrait par la suite dans l’éditeur HTML puis revenir à l’éditeur visuel peut modifier la mise en forme du paragraphe, et le rendu final peut être très différent selon le navigateur. Bref, au lieu de faire gagner du temps, les éditeurs visuels sont ici une bonne raison de perdre patience très rapidement !

Pour commencer, on pourrait en théorie améliorer un peu les choses en profitant des informations disponible dans un copier-coller « classique » de Visual Studio, à savoir le fait que ce dernier exporte, en plus du texte, les informations sur la mise en forme comme la police de caractère et la coloration syntaxique. Il suffit de faire un simple copier-coller dans Word pour s’en rendre compte. En partant de cette idée, on pourrait essayer de se simplifier la vie en utilisant la fonction « coller du texte Word » de l’éditeur visuel de WordPress, disponible dans la barre d’outils (en mode avancé) :

Coller à partir de Word

Malheureusement, cette fonction ne semble pas donner le résultat souhaité pour notre extrait de code, même en effectuant un copier-coller intermédiaire sous Word. En ce qui me concerne j’ai eu des résultats extrêmement variables suivant le navigateur utilisé. D’ailleurs l’éditeur visuel intégré de WordPress semble avoir quelques soucis sous Internet explorer 8. Il faudra forcer l’affichage de compatibilité pour ne plus avoir de problèmes de comportement.

 

Style préformatéLa solution la plus simple pour améliorer le résultat reste encore de faire un copier-coller en texte simple, puis de sélectionner le code et utiliser le style de paragraphe « préformaté » (avec une grosse faute dans la traduction française).

Cela permet d’utiliser la balise appropriée pour l’affichage d’un extrait de code (la balise <pre> qui est détaillée un peu plus loin). Cependant il reste encore à refaire à la main toute la coloration syntaxique. Plutôt laborieux en fait, alors que l’éditeur visuel est normalement censé nous faire gagner du temps par rapport à l’édition de code HTML. De plus, il est assez facile de se tromper et d’utiliser des couleurs légèrement différentes pour un même type de mot-clé. Au final, il est difficile d’obtenir un résultat réellement propre et fiable en utilisant uniquement l’éditeur visuel.

 

Extensions

Un des points fort de WordPress concerne son architecture ouverte et sa communauté très active. On trouve donc énormément d’extension (ou plugins) gratuites pour enrichir le moteur par défaut. La plupart peuvent se récupérer directement sur le site de WordPress, au même titre que les thèmes : http://wordpress.org/extend/plugins/. Le site regroupe actuellement plus de 7000 extensions et propose un suivi efficace des mises à jour (et leur installation) via l’interface d’administration du blog.

Sans surprise, on peut donc trouver de nombreuses extensions permettant de faciliter l’insertion d’extraits de code dans les articles. Il suffit d’effectuer une recherche avec les mots-clés « highlighting » ou « syntax highlighting » pour s’en rendre compte.
La plupart de ces extensions sont en fait construites autour d’un module de coloration syntaxique OpenSource appelé GeSHi (Generic Syntax Hilighter). Ce programme, écrit en PHP, supporte près de 150 langages différents et se base notamment sur des fichiers de style CSS pour générer le code HTML final. Il est aussi très utilisé avec d’autres types de plateformes Web, comme les Wikis (avec MediaWiki). Le but des extensions consiste donc à faciliter la saisie des extraits de code et des commandes PHP destinées au moteur GeSHi, étant donné que l’éditeur Visuel ou HTML de WordPress ne permettent pas, par défaut, de saisir des instructions dans ce langage. Elles permettent aussi de rajouter quelques fonctionnalités, comme l’affichage de boutons pour faciliter la copie par exemple.

Bien que cette solution soit largement suffisante dans la plupart des cas, et bien supérieure à la méthode précédente, l’utilisation d’extensions basées sur un moteur aussi générique que GeSHi présente quelques inconvénients : Pour commencer on ne retrouve pas exactement la coloration syntaxique présente dans Visual Studio. Pour des langages comme le XML ou l’HTML par exemple, ce n’est pas vraiment un problème, mais pour un langage fortement lié à son éditeur comme le C#, c’est déjà plus gênant. L’exemple le plus représentatif concerne la coloration des classes (en bleu clair), dont on aurait du mal à se passer. Mais en y réfléchissant bien, on comprend facilement que cette coloration ne soit pas disponible : en effet, il n’est pas possible de distinguer le nom d’une classe de celui d’un espace de nom ou d’une propriété par exemple, simplement en se basant sur la syntaxe. Seule la connaissance du code de l’ensemble du projet, ainsi que des librairies référencées, permet de faire cette distinction.

Voici un exemple d’affichage d’un extrait de code C# à l’aide d’une extension WordPress basée sur le module PHP GeSHi :

Extension coloration syntaxique

 

Un autre inconvénient concerne la dépendance vis-à-vis d’une extension WordPress : Rien ne garanti qu’elle continuera d’être maintenue au fil des années et qu’elle sera compatible avec les prochaines versions du moteur de blogs. De plus, bien que le traitement effectué par le programme GeSHi soit très rapide, on peut aussi se poser la question concernant les performances de cette méthode : le script de coloration étant appelé à chaque calcul de la page finale (sauf mise en cache gérée par les extensions). Pour finir, ces extensions ne permettent pas, en général, d’utiliser des balises HTML pour mettre ponctuellement en évidence un passage dans l’extrait de code (par exemple l’utilisation de <del> pour illustrer une correction dans le code).
C’est pour toutes ces raisons que j’ai finalement choisi de m’intéresser d’un peu plus près à la solution HTML.

 

2ème méthode : Avec l’éditeur HTML

 

Même si elles ne sont pas directement disponibles dans les éditeurs visuels (ou mal identifiées), il existe deux balises HTML prévues pour l’affichage d’extraits de code : les balises <code> et <pre>. Seule la balise <code> est disponible dans la barre d’outils de l’éditeur HTML de WordPress (ce qui n’empêche pas d’écrire l’autre balise manuellement), la balise <pre> par contre est disponible indirectement via l’éditeur visuel en sélectionnant le style de paragraphe « préformaté ». Dans les deux cas, ces balises permettent avant tout d’afficher le code dans une police à pas fixe, ce qui répond à une de nos contraintes. Avant de voir plus en détails ce qui les distingue, pensez à effectuer quelques modifications dans WordPress pour utiliser correctement l’éditeur HTML et éviter les mauvaises surprises :

  • Désactivez l’éditeur Visuel dans les options du profil utilisateur (fortement conseillé pour limiter les mauvaises mises en forme automatiques) ;
  • Augmentez le nombre de lignes visibles de l’éditeur HTML, dans le menu Réglages -> Ecriture ;
  • Désactivez la correction automatique XHTML, toujours dans le menu Ecriture, dans les options de mise en forme.

 

La balise <code>

Pour commencer, je me suis tout d’abord tourné vers la balise <code> puisqu’elle était mise en évidence dans l’éditeur HTML de WordPress, et qu’elle possède un nom assez explicite par rapport à la fonction recherchée. Pour mieux mettre mes exemples de code en évidence, je les entourais d’un bloc <blockquote> (balise prévue pour les citations) :

<blockquote>
<code>Console.WriteLine("Exemple");<code>
</blockquote>

Résultat :

Console.WriteLine("Exemple");

 

Les problèmes ont commencé à apparaître avec l’affichage de plusieurs lignes de code, et l’ajout de l’indentation (retrait du texte). Celui-ci était systématiquement supprimé et l’ensemble du texte se retrouvait aligné sur la gauche au même niveau, à moins de forcer l’ajout d’espaces insécables avec "&nbsp;" (non-breaking space), ce qui était plutôt laborieux et gênait considérablement la lecture et l’édition du code HTML. C’est en essayant d’insérer des exemples un peu plus longs dont le code comportait des lignes vides, que j’ai commencé à réellement comprendre que la balise <code> n’était finalement peut-être pas ce qu’il fallait utiliser ici…

Prenons l’exemple de cet extrait de code écrit à l’aide de la balise <code> :

<blockquote>
<code style="color:Blue" >
if(myVar == 3)
{
    Console.WriteLine("OK");
}

return true;
</code>
</blockquote>

Ici j’ai volontairement ajouté une couleur bleue à la balise <code> afin de mieux identifier le problème. On constate sur les captures ci-dessous que l’affichage n’est pas le même selon le navigateur utilisé :

Résultat sous IE 8 (à gauche) et Firefox (à droite)

Résultat sous IE 8 (à gauche) et Firefox (à droite)

 

Sous Firefox, la dernière ligne n’a ni la même couleur, ni la même police de caractères que le reste de l’extrait de code. Ce problème a en fait deux origines :

Premièrement, en regardant le code source HTML de la page dans un navigateur, on constate que WordPress ajoute des balises à l’emplacement de notre ligne vide :

Code HTML généré par WordPress

Code HTML généré par WordPress

 

On constate que plusieurs balises <p> (balises prévues pour les paragraphes, en jaune sur la capture) et <br /> (balise correspondant à un retour à la ligne, en gris ici) on été insérées. Pour les balises <br /> il n’y a pas vraiment de problème car ce sont des balises indépendantes, mais pour les autres on remarque qu’il y a un gros problème d’imbrication, dont l’enchaînement est le suivant :

<p><code></p><p></code></p>

Notre balise <code> se retrouve encadrée par un bloc <p>, ce qui n’est pas du tout valide selon les standards XHTML. La présence même d’une balise <p> dans un bloc <code> n’est d’ailleurs pas considérée comme valide. En fait, il faut savoir que l’éditeur HTML de WordPress n’est pas exactement un vrai éditeur HTML, car certaines balises sont masquées et générées automatiquement. C’est le cas justement des début et fin de paragraphes <p> et des retours à la ligne <br />. Il est cependant possible de les forcer en insérant par exemple le code <p>&nbsp;</p> pour accentuer la séparation de deux paragraphes (dans ce cas les balises <p> ne seront pas masquées). On est donc ici en présence d’un code HTML invalide généré par le moteur WordPress.

La deuxième raison de ce mauvais affichage vient ensuite de l’interprétation de ce code incorrect par les navigateurs : Internet Explorer va essayer de trouver la fermeture de la balise <code>, tandis que Firefox la clos automatiquement dès qu’il rencontre la balise </p>. De toute façon, le code HTML n’étant pas valide, l’interprétation des navigateurs n’est pas vraiment importante (mis à part la mise en évidence du problème, plus facile à voir sous Firefox que sous IE).

Plusieurs solutions sont possibles pour forcer WordPress à générer un code valide, mais cela reviendrait à faire du « bricolage ». Nous avons vu que la balise <code> fonctionnait correctement lorsque l’exemple à insérer était court (idéalement inférieur à la largeur d’une ligne), nous allons maintenant voir qu’il existe une autre balise destinée aux extraits de code plus conséquents : la balise <pre>.

 

La balise <pre>

La principale différence entre la balise <code> et la balise <pre> consiste dans le fait que cette dernière est spécialement conçue pour l’insertion de blocs de code (que l’on appelle alors « bloc preformaté »), alors que la première sert plutôt pour les extraits de code courts, tenant en général sur une seule ligne, placés à l’intérieur d’un paragraphe. La balise <pre> est en fait un vrai conteneur, au même titre que les balises <p> ou <div> par exemple. C’est la balise généralement utilisée par toutes les extensions WordPress permettant l’insertion d’extraits de code dans un article.

Le remplacement de la balise <code> par <pre> dans l’exemple précédent a donc permis de régler la plupart des problèmes évoqués précédemment :

if(myVar == 3)
{
    Console.WriteLine("OK");
}

return true;

 

Ce n’est pas la seule différence : La balise <pre> reproduit le formatage exact de son contenu comme l’indentation, les retours à la ligne et les sauts de ligne ce qui simplifie nettement l’écriture de son code HTML puisqu’un simple copier-coller depuis Visual Studio (par exemple) suffit. Ce respect du code inséré va jusqu’à laisser intact la présentation des lignes, c’est-à-dire qu’une ligne trop longue ne débordera pas automatiquement sur la ligne suivante (ce qui est le cas avec le texte des paragraphes <p>) mais dépassera du cadre. Ce comportement peut être gênant dans la mesure où l’extrait de code perd de son intérêt s’il ne peut pas être visualisé correctement et dans son intégralité.

 

Les recommandations du W3C fournissent les éléments que doivent respecter les « agents visuels » (navigateurs par exemple) lorsqu’ils rencontrent une balise <pre> :

  • Laisser les espaces blancs intacts : L’indentation est conservée.
  • Utiliser une police à pas fixe : Par exemple « iii » et « www » doivent avoir la même largeur.
  • Désactiver le retour à la ligne automatique.
  • Ne pas désactiver le traitement bi-directionnel : Par exemple il est toujours possible d’utiliser à l’intérieur les balises <strong> (gras) et <em> (italique).

 

Le dernier point indique ainsi qu’il est possible d’insérer certaines balises pour modifier le rendu d’un passage du code. En d’autres termes, cela veut aussi dire que les caractères utilisés pour délimiter les balises doivent être remplacés pour éviter d’être interprétés. Et ces caractères peuvent être très nombreux s’il s’agit d’un extrait de code HTML ou XML par exemple. Ainsi, le caractère "<" devra être remplacé par "&lt;" et le caractère ">" par "&gt;".

 

Pour remédier aux soucis engendrés par la désactivation du retour à la ligne automatique, il est possible d’ajouter des styles à la balise <pre>. Cependant, comme nous allons le voir, tout ceci n’est pas vraiment normalisé (ou a évolué au fil des années), ce qui se traduit par une bonne prise de tête avec les différents navigateurs existants et leurs différentes versions.

 

Mise en forme et retouches finales

 

Césure et barres de défilement

Afficher des exemples de code dans un article présente d’autres types de contraintes en dehors du simple aspect visuel du texte (couleur, police). En effet, il arrive fréquemment que certaines lignes de code dépassent la largeur totale de l’article, Visual Studio (ou autre) n’étant pas soumis à ce genre de limite. Lorsque le cas se présente, les lignes de code en question débordent du cadre et l’excédent peut se retrouver masqué. Le texte n’est pas supprimé car un simple copier-coller permet de le récupérer, mais c’est cependant nettement moins pratique à lire. A noter que ce comportement est spécifique à la balise <pre> afin de garantir que, par défaut, le rendu sera identique en tout points (retour à la ligne y compris) au texte saisi.

 

Ajouter le retour automatique à la ligne

 

J’ai voulu au départ m’inspirer du site MSDN et de ses très nombreux exemples de codes (avant leur changement de design d’octobre 2009). En regardant le code source des pages, on pouvait voir l’utilisation de la balise <pre> avec le style : style="word-wrap:break-word; word-break:break-all" pour forcer le retour à la ligne automatique des lignes trop longues. Cela fonctionne très bien sous IE7 et IE8, mais pas sous Firefox, car ce n’est pas un style valide CSS3 (c’est même rejeté par le validateur de Visual Studio). En affichant le code source HTML de la même page sous Firefox, on pouvait d’ailleurs constater que le style inséré n’était pas le même. Cette fois, il s’agissait de style="white-space: pre-wrap;". On aborde ici un des problèmes bien connus des programmeurs de sites Internet : à savoir l’interprétation des styles CSS par les navigateurs. Étant donné qu’il n’y a jamais eu de vraies normes mais uniquement des recommandations pour les différentes versions, il peut y avoir de grandes différences dans l’affichage d’un même site suivant les navigateurs et les styles utilisés. Bien que de nos jours, les dernières versions soient beaucoup plus respectueuses des standards, il reste encore beaucoup de visiteurs utilisant IE 6 par exemple (en particulier sur les réseaux d’entreprises). Ces problèmes nécessitent souvent l’écriture de fichiers CSS spécifiques pour les différents navigateurs.

Quoi qu’il en soit, la recommandation W3C est d’utiliser style="white-space: pre-wrap;", mais cela ne fonctionnera pas sur certains navigateurs comme les anciennes versions d’IE, pour lesquelles il faudra plutôt utiliser style="word-wrap:break-word;".

Pour compléter ce sujet, il y a un paragraphe intéressant sur la documentation du module GeSHi (en anglais) et les raisons pour lesquelles un bloc <div> est parfois préféré au bloc <pre>.

 

Ajouter une barre de défilement

 

Il y a une autre alternative au retour à la ligne automatique pour afficher les lignes trop longues : l’ajout d’une barre de défilement horizontale. Celle-ci peut s’ajouter à nouveau par l’intermédiaire d’un style à appliquer à la balise <pre> : "overflow".

Les recommandations de cette propriété peuvent se trouver sur le site du W3C mais ici l’absence de réelle norme définitive est encore plus pénalisante que pour le retour à la ligne automatique. Normalement, définir le style "overflow:auto", devrait répondre à la plupart des cas dans les navigateurs actuels. Cela permet d’afficher les barres de défilement uniquement si le texte déborde du cadre (si la hauteur est fixée dans le style, la barre verticale pourrait ainsi s’afficher elle aussi). Certains navigateurs acceptent aussi les attributs "overflow-x" et "overflow-y" qui permettent d’affiner le paramétrage en définissant séparément le comportement des barres verticales et horizontales.

Dernière précision : Par défaut, l’affichage d’une barre de défilement ne modifie pas les dimensions du cadre du bloc préformaté, elles risquent donc de s’afficher au dessus d’une ligne de code et de la masquer. Prévoyez si possible un espace suffisant en bas du bloc dans ce cas. A noter d’ailleurs que "overflow-y:hidden" est souvent utilisé en complément pour éviter que la barre la barre verticale ne s’affiche elle aussi lorsque la barre horizontale apparait, dans les anciennes versions d’Internet Explorer.

Exemple avec overflow:auto :

public static void MethodeLongue(System.Windows.Forms.TextBox myParameter1, System.Windows.Forms.Label myParameter2)
{
    Console.WriteLine(String.Format("Param1 = {0}, Param2 = {1}, Dossier d'exécution = {2}", param1.Text, param2.Text, System.Reflection.Assembly.GetExecutingAssembly().Location);
}

 

Si vous envisagez malgré tout de coder les différents styles nécessaire pour que les barres de défilement apparaissent bien dans chaque navigateur (et leurs versions précédentes encore utilisées), pensez toutefois à n’utilisez cette option que lorsque c’est vraiment nécessaire. Ce n’est pas très agréable pour le lecteur de ne pas avoir une vision d’ensemble de l’exemple. Prenez le temps de penser à ce qu’il est possible de faire en améliorant la mise en forme du code et n’utilisez la barre de défilement qu’en dernier recours.

 

Soigner la présentation du code

 

Pour éviter ces problèmes de rendu suivant les navigateurs, je ne conseillerai qu’une seule chose en fait : Présentez vos extraits de code de façon à ce qu’ils tiennent toujours dans la largeur de la page de l’article. De cette façon, il n’y a plus besoin de se poser la question sur la nécessité d’afficher ou non des barres de défilement, ou de mettre en place le retour à la ligne automatique. De plus, le code est plus agréable à regarder. Pensez donc à bien exploiter la mise en forme sur plusieurs lignes du code et utilisez les retraits (pas de tabulation surtout, utilisez les espaces) pour faciliter la lecture, décomposez les traitements en plusieurs étapes, utilisez des variables intermédiaires et simplifiez l’écriture des espaces de nom à l’aide du mot-clé using.

L’exemple ci-dessous est volontairement bien plus large que l’espace réservé à l’article. Faites un copier-coller vers un éditeur externe pour en voir l’intégralité :

public static void MethodeLongue(System.Windows.Forms.TextBox myParameter1, System.Windows.Forms.Label myParameter2)
{
    Console.WriteLine(String.Format("Param1 = {0}, Param2 = {1}, Dossier d'exécution = {2}", param1.Text, param2.Text, System.Reflection.Assembly.GetExecutingAssembly().Location);
}

Résultat après réécriture :

// En-tête :
using System.Windows.Forms;
using System.Reflection;

// Dans la classe :
public static void MethodeLongue(TextBox param1,
                                 Label param2)
{
    StringBuilder sb = new StringBuilder();

    sb.AppendFormat("Param1 = {0}, ", param1.Text);
    sb.AppendFormat("Param2 = {0}, ", param2.Text);

    Assembly currentAssembly = Assembly.GetExecutingAssembly();
    sb.AppendFormat("Dossier d'exécution = {0}", currentAssembly.Location);

    Console.WriteLine(sb.ToString());
}

 

Évidemment, il y a nettement plus de ligne que dans la première version. Mais c’est un exemple un peu extrême pour illustrer tout ce que l’on peut faire pour réduire la longueur d’une ligne de code et la décomposer en plusieurs éléments. Il reste toutefois un cas d’utilisation où le code pourrait à nouveau dépasser de la largeur de l’article : Si le zoom texte du navigateur est utilisé.

 

Indentation

Curieusement, l’indentation (retrait du texte par rapport à la marge) est aussi un point à ne pas négliger lorsque l’on souhaite insérer des extraits de code dans une page web, même en utilisant la balise <pre>. Habituellement, on a tendance à utiliser les tabulations pour effectuer ces retraits. Cependant, la largeur de ces tabulations n’est pas normalisée. Elle est donc laissée à la libre interprétation des navigateurs qui, en général, choisissent de faire correspondre chaque tabulation à la largeur de 8 espaces, ce qui est beaucoup trop pour notre utilisation. La principale conséquence est la perte de l’alignement lorsque l’on souhaite, par exemple, présenter les paramètres d’une méthode les uns en dessous des autres.

Pour éviter les mauvaises surprises, il faut donc remplacer chaque tabulation par un certain nombre d’espaces. C’est d’ailleurs la méthode par défaut utilisée par Visual Studio. Pour vérifier cela il suffit d’aller jeter un œil aux options, dans le Menu Options, puis Editeur de texte -> C# -> Tabulations :

Options de tabulation sous Visual Studio

Options de tabulation sous Visual Studio

 

Comme on peut le voir ci-dessus, la largeur traditionnelle d’une tabulation est plutôt de 4 espaces, ce qui donne un résultat bien plus satisfaisant. L’utilisation des tabulations à l’intérieur des balises <pre> est d’ailleurs fortement déconseillée par le W3C :

The horizontal tab character (decimal 9 in [ISO10646] and [ISO88591] ) is usually interpreted by visual user agents as the smallest non-zero number of spaces necessary to line characters up along tab stops that are every 8 characters. We strongly discourage using horizontal tabs in preformatted text since it is common practice, when editing, to set the tab-spacing to other values, leading to misaligned documents.

 

Coloration syntaxique

Il nous reste un dernier élément à aborder concernant la mise en forme des extraits de code à l’aide de la balise HTML <pre> : La coloration syntaxique. A défaut d’utiliser un script pour effectuer le travail automatiquement, l’idéal est de trouver une solution pour faciliter la tâche.

Le changement de couleur du code s’effectue à l’aide de la balise HTML <span> qui permet d’appliquer un style sur une portion de texte. Par exemple le code <span style="color:blue">TEST</span> permet d’obtenir le mot TEST. On peut aussi utiliser le code hexadécimal des couleurs : <span style="color:#A31515">TEST</span>, ce qui donne le mot TEST.

Évidemment, devoir se souvenir du nom ou du code hexadécimal des couleurs utilisées pour les commentaires, les mots-clés, les noms de classe, etc. ce n’est pas spécialement pratique. L’idéal étant d’associer chaque catégorie de mot avec sa couleur correspondante une seule et unique fois. On peut réaliser ceci en ajoutant des classes supplémentaires dans la feuille de styles principale du site, à l’aide du langage CSS. Voici par exemple le code que j’ai rajouté pour ce blog :

/* Code box */
.codebox, pre
{
    background:#F4F5F7;
    border:1px dashed #CCC;
    padding:8px 12px 8px 36px;
    margin:5px 0;
}

/* CSharp */
code.csharp .keyword, pre.csharp .keyword { color: Blue; }
code.csharp .classname, pre.csharp .classname { color: #2B91AF; }
code.csharp .comment, pre.csharp .comment { color: Green; }
code.csharp .string, pre.csharp .string { color: #A31515; }
code.csharp .xmldoc, pre.csharp .xmldoc { color: Gray; }
code.csharp .snippet, pre.csharp .snippet { background-color: #B4E4B4; }

Ce code peut être rajouté à la fin du fichier style.css du thème utilisé.

Son utilisation est très simple :

Pour ajouter un cadre à l’exemple de code afin de le mettre en évidence, il suffit d’insérer class="codebox" à l’intérieur d’une balise de type bloc comme <div> ou <p>. Pour la balise <pre> ce style s’appliquera par défaut.

Pour la coloration du code, il suffit d’indiquer le langage dans la balise <code> ou <pre> avec class="csharp", puis d’utiliser les balises <span class="xxxx"> pour appliquer le style souhaité. Les différents noms de classes comme « keyword » ou « xmldoc » ne seront actifs que si le langage correspondant à bien été précisé dans la balise parente <code> ou <pre> (ici je n’ai mis que les styles pour le C#).

 

Exemple d’utilisation :

<pre class="csharp">
<span class="xmldoc">/// Méthode de démonstration</span>
<span class="keyword">public bool</span> Test()
{
    <span class="keyword">string</span> texte;
    texte = <span class="string">"OK"</span>;

    <span class="comment">// Commentaire</span>
    <span class="classname">Console</span>.WriteLine(texte);

    <span class="keyword">return true;</span>
}
</pre>

Résultat :

/// Méthode de démonstration
public bool Test()
{
    string texte;
    texte = "OK";

    // Commentaire
    Console.WriteLine(texte);

    return true;
}

 

Conclusion

 

Finalement, j’ai fait le choix de passer systématiquement par l’éditeur HTML pour insérer mes exemples de code à l’aide des balises <code> ou <pre>. La mise en place des balises <span> pour la coloration syntaxique n’est pas si contraignante que ça et reste relativement rapide à effectuer avec un peu d’habitude. De plus, cela permet d’avoir un code optimisé dont le rendu peut être facilement changé dans le fichier css. On peut ainsi avoir un affichage identique à celui de l’éditeur de Visual Studio, y comprit pour les noms de classes, sans être dépendant d’une extension dont la maintenance peut cesser d’un jour à l’autre.

Attention : Il est très facile de laisser quelques erreurs dans le code HTML (balises mal fermées, erreurs de syntaxe, etc.) ce qui risque de donner des résultats très variables suivant les navigateurs. Pour éviter tout problème, il est préférable de faire une petite vérification de l’extrait de code ou de la page finale dans un validateur HTML, comme celui du W3C : http://validator.w3.org/.

 

En ce qui me concerne, j’ai développé une petite application qui s’occupe de générer le code HTML automatiquement (avec la coloration syntaxique) et limite les opérations manuelles à quelques copier-coller. J’essaierai de la proposer en téléchargement dans la rubrique « projets » une fois que je l’aurais rendue un peu plus présentable !

 

Categories: WordPress Tags: , ,
  1. Pas encore de commentaire
  1. Pas encore de trackbacks