Articles

Comment insérer des (beaux) exemples de code dans MadCap Flare

Quand vous produisez de la documentation au format HTML, il peut être délicat d’insérer du code à la fois facile à lire, visuellement attrayant et qui répond aux attentes des développeurs de logiciels. Heureusement, nous avons trouvé une façon simple de rendre cela possible!

On dit que la forme passe après la fonction, mais nous voulons tous que notre documentation attire le regard. Si vous travaillez dans l’industrie du logiciel, vous savez probablement que les exemples de code peuvent parfois manquer un peu d’éclat dans MadCap Flare, s’ils n’ont pas de coloration syntaxique. Pire encore, il peut être difficile de formater le code pour qu’il ressemble à ce que les développeurs de logiciels voudraient. Mais qu’est-ce qu’un rédacteur technique peut faire?

Je sais, je vais simplement prendre des photos de mon code!

Prendre des captures d’écran de votre code tout bien formaté peut être une façon rapide et simple d’arriver à vos fins. Mais qu’est-ce qui se passe si vos utilisateurs veulent copier vos exemples et les modifier pour les utiliser dans leurs propres projets? Toute la beauté de votre formatage va rapidement perdre de l’intérêt quand votre lecteur frustré devra retranscrire votre code ligne par ligne. De plus, le code dans vos captures d’écran n’apparaîtra jamais comme résultat de recherche, ce qui signifie que moins de gens verront votre travail.

J’ai copié mon code sous forme de texte, mais c’est un fouillis total.

En effet. On ne se rend pas compte à quel point les sauts de ligne, les indentations et la coloration syntaxique sont importants, jusqu’à ce qu’ils aient disparu. Et décrypter ce genre de code peut causer de sérieux maux de tête :

Mais pas de panique! Vous pouvez toujours copier votre code dans des balises <pre><code class="language-xxx"></code></pre>, ce qui aura au moins pour effet de préserver vos indentations et de faire afficher votre code dans une simple police à espacement constant :

La mauvaise nouvelle, c’est que vous devrez vous contenter d’une bonne vieille police de caractère noire, ou que vous devrez créer des styles personnalisés pour chaque couleur de police et les appliquer à la main. Nous ne savons pas pour vous, mais peu de gens ont autant de temps à perdre.

S’il vous plaît, dites-moi qu’il y a une meilleure solution.

Vous avez de la chance, il y en a une. Grâce aux gens chez Prism (et aux concepteurs d’autres outils de coloration syntaxique), vous pouvez télécharger un script de coloration syntaxique qui vous permettra de réaliser vos rêves de code coloré :

Envie de l’essayer? Suivez les étapes ci-dessous.

Télécharger Prism

La première chose à faire, c’est de télécharger Prism à partir du site Web :

1. Allez au prismjs.com.
2. Cliquez sur le gros bouton DOWNLOAD sur la page d’accueil.
   
3. Modifiez les paramètres de téléchargement si vous voulez personnaliser le thème de couleur ou les langues supportées.
   
4. Dans le bas de la page, cliquez sur DOWNLOAD JS et DOWNLOAD CSS.
   

Configurer Prism dans Flare

Une fois que vous avez tous les fichiers dont vous avez besoin, c’est le temps de configurer votre projet pour qu’il fonctionne avec Prism :

1. Dans Flare, dans l’Explorateur de contenu, cliquez à droite sur le dossier Resources et sélectionnez Nouveau > Dossier. Nommez ce nouveau dossier Scripts.
   
2. Enregistrez le fichier .js que vous avez téléchargé dans le dossier Scripts que vous venez de créer.
3. Enregistrez le fichier .css que vous avez téléchargé dans votre dossier Stylesheets.
4. Pour vous assurer que votre code sera formaté avec la coloration syntaxique de Prism, vous devez importer le CSS de Prism dans votre feuille de style. Pour ce faire, ouvrez Flare, cliquez à droite sur la feuille de style associée à votre cible et ouvrez-la avec l’Éditeur de texte interne.
   
5. Entrez @import url('prism.css'); dans le haut de votre feuille de style. Cela fera en sorte que votre code sera formaté avec la coloration syntaxique de Prism.
   
6. Pour vous assurer que le script sera exécuté sur chaque page, vous devrez appeler le script Prism dans votre page modèle. Pour ce faire, cliquez à droite sur votre page modèle et ouvrez-la avec l’Éditeur de texte interne.
   
7. Entrez <script type="text/javascript" src="../Scripts/prism.js"></script> dans la section <head>.
   

Insérer du code dans vos rubriques

1. Ouvrez la rubrique dans laquelle vous voulez ajouter un bloc de code.
2. En utilisant l’Éditeur XML, copiez votre code dans la rubrique.
3. Cliquez sur l’icône qui s’affiche sous le code que vous avez copié et sélectionnez Coller le texte inséré. Cela fait en sorte que tous les caractères spéciaux qui se trouvent dans votre code (ex. <, >, &) sont convertis en code HTML (ex. <, >, &).

   Conseil : Si votre code est écrit dans un langage qui n’utilise pas de caractères spéciaux, comme JavaScript, vous pouvez aussi copier votre code directement dans l’Éditeur de texte.

4. Allez dans l’Éditeur de texte et encadrez votre code avec des balises (remplacez “xxx” par le langage de votre code, comme “html” ou “css”).
   

Enfin (enfin!), publiez votre projet et admirez votre bloc de code! Vous pouvez maintenant ajouter du code à votre projet partout où vous en avez besoin, sans perdre aucune des mises en forme que vous voyez dans votre éditeur de code.

Conseil : Pour accélérer encore davantage ce processus, vous pouvez créer un modèle de bloc dans Flare pour chaque langage de code. Voici un modèle que nous utilisons :