Licence CC BY-NC-ND

Présenter du code source dans un document LaTeX

Le package minted

Publié :
Auteur :
Catégorie :
Temps de lecture estimé : 32 minutes

Lorsque nous écrivons un document, il peut nous arriver de vouloir illustrer un propos avec un bloc de code. Et comme d’habitude, nous pouvons trouver plusieurs packages pour nous aider à faire ce travail. Dans ce tutoriel, nous apprendrons à le faire en utilisant le package minted.

Prérequis
Connaissance des bases du LaTeX.

Objectifs
Découvrir un moyen efficace de composer des codes sources en LaTeX.

Le texte préformaté et minted

Le texte préformaté

Pour écrire du code source, il nous faut écrire du code qui ne sera pas interprété par LaTeX et sera affiché tel qu’il est présenté (espaces, tabulations, sauts de lignes, etc.). De base, LaTeX propose la commande verb et l’environnement verbatim qui permettent de présenter du texte préformaté. Nativement, nous pouvons donc faire ceci.

\begin{document}
   Ici, on va montrer ce qu’il a entre notre \verb|\begin{document}| et notre \verb|\end{document}|.
\begin{verbatim}

\end{verbatim}
   On voit bien dans ce document que \verb|\verb| et \verb|verbatim| font le travail voulu.
\end{document}

Le texte préformaté est traditionnellement présenté dans une police à chasse fixe (c’est-à-dire que tous les caractères ont la même largeur), \verb et verbatim ne font pas exception. Cependant, le code présenté avec verbatim n’est pas coloré, et nous n’avons pas la possibilité de numéroter les lignes et en fait de personnaliser l’affichage du code. C’est pourquoi plusieurs packages viennent compléter verbatim.

Pourquoi minted ?

Comme nous venons de le dire, plusieurs packages nous permettent de présenter du code. L’un des plus connu est le package listings et ce n’est pas pour rien. Il existe depuis longtemps, est mûr et éprouvé, fait très bien son travail, est très personnalisable, et c’est facile de trouver de la documentation à son sujet. En clair, il a tout ce que nous voulons… Cependant, dans ce tutoriel, nous allons apprendre à utiliser le package minted.

Pourquoi apprendre à utiliser minted quand listings fait déjà ce qu’il faut et le fait bien ? Quels sont les avantages de minted ?

Le package listings a en effet beaucoup d’avantages, mais minted est plus simple à configurer, en particulier sur la coloration syntaxique. Ainsi, alors qu’avec listings, il faut choisir la couleur de chaque type de mots (nous choisissons la couleur des chaînes de caractères, la couleur des mots-clés, la couleur des commentaires, etc.), avec minted, il y a juste à choisir un style et le code aura ce style.

Pour ce faire, minted s’appuie sur un module Python, Pygments. Ce module gère plus de 300 langages différents et une bonne vingtaine de styles. Autant dire que nous avons le choix.

Installer minted

Comme nous venons de le dire, minted s’appuie sur Python et son module Pygments. Il nous faut donc les installer. Pour ceux qui n’utilisent pas Python, cette page explique comment l’installer. Après l’avoir installé, installons Pygments. Pour cela, ouvrons un terminal et tapons la commande suivante.

pip install pygments

Une fois les opérations terminées, vérifions que pygments est bien installé en compilant un premier code qui utilise minted.

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[francais]{babel}
\usepackage{minted}

\begin{document}
   Document de test de minted.
\end{document}

Puisque minted a besoin d’appeler Python, nous ne pouvons pas utiliser la commande pdflatex (ou xelatex, etc.) seule, il nous faut l’utiliser avec l’option -shell-escape. Ainsi, pour compiler notre document, nous utiliserons cette ligne de commande.

pdflatex -shell-escape fichier.tex

Si nous oublions cette option, nous obtiendrons l’erreur « You must invoke LaTeX with the -shell-escape flag ». Si pygments n’est pas installé, nous obtiendrons l’erreur « You muste have `pygmentize` installed to use this package ».

Pour ne pas oublier cette option, nous pouvons créer une nouvelle commande pour ne pas voir à taper cette option à chaque fois. Sous Windows, nous pouvons créer un fichier .bat avec ce contenu (nous pouvons par exemple l’appeler mpdflatex.tex pour « minted pdflatex ».

pdflatex -shell-escape %*

Nous le plaçons alors dans le dossier où sont placés les exécutables latex, pdflatex et autres et pour compiler, nous pouvons maintenant écrire mpdflatex fichier.tex.

Sous Linux


Nous sommes maintenant prêts à apprendre à utiliser minted.

Écrire du code

Utiliser minted

Bloc de code

Comme nous l’avons dit, utiliser minted est très simple. Pour écrire un bloc de code, il nous suffit d’utiliser l’environnement minted, qui prend en paramètre le langage du bloc de code ( nous pouvons voir la liste des langages sur le site de Pygments ou en utilisant la commande pygmentize -L lexers. Voici donc un premier exemple de code.

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[francais]{babel}
\usepackage{minted}

\begin{document}
   Voici un bloc de code en LaTeX.

\begin{minted}{latex}
En LaTeX, on écrit des maths en lignes entre deux signes dollars. Exemple, $1 + 3^2 = 10$.
Pour le code hors-texte, voici un exemple.
\[
   1 + 3^2.
\]
\end{minted}
\end{document}

Compilons-le et ouvrons le document PDF obtenu. Nous remarquons déjà que la coloration syntaxique est bien au rendez-vous, et ce sans rien avoir eu à indiquer. Nous pouvons essayer d’autres langages, d’autres codes et voir comment ils sont composés.

Si nous voulons faire un bloc de code d’une ligne, nous pouvons utiliser la commande mint qui est alors un raccourci de l’environnement minted. Elle prend en paramètre le langage à utiliser et s’utilise comme \verb c’est-à-dire que pour délimiter le code, nous utilisons deux fois un même caractère qui n’est pas présent dans le code.

Observons que nous avons a le même résultat.

\mint{latex}|En LaTeX \begin et \end servent pour les environnements.|

\begin{minted}{latex}
En LaTeX \begin et \end servent pour les environnements.
\end{latex}

Depuis un fichier

Plutôt que d’écrire le code dans le fichier LaTeX, il est possible d’afficher le code d’un fichier en utilisant la commande inputminted qui prend en paramètre le langage et le chemin du fichier. Par exemple, affichons le contenu du fichier fichier.tex que nous sommes en train d’écrire.

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[francais]{babel}
\usepackage{minted}

\begin{document}
   \inputminted{latex}{test.tex}
\end{document}

Code en mode en ligne

Et finalement, pour mettre du code en mode en ligne, nous allons utiliser la commande \mintinline. Elle prend en paramètre le langage à utiliser et le code qui peut être entre accolades, ou, comme avec \mint ou \verb, être autour d’une paire de caractères.

\begin{document}
   La commande \mintinline{latex}{\begin} ouvre un environnement.
\end{document}

La commande \mintinline est une commande fragile. Cela peut poser des problèmes pour l’utiliser dans les commandes de sectionnement par exemple.

Dans certains cas, il nous faudra alors faire attention à la protéger en utilisant la commande \protect. Parfois, cela ne fonctionnera pas ; une autre solution, mais qui n’utilise plus minted et n’a pas la coloration syntaxique, est d’utiliser la commande \texttt pour obtenir une police à chasse fixe. Le problème est alors que nous ne pouvons pas utiliser les caractères spéciaux directement.

\begin{document}
   % \section{\mintinline{latex}{\section}} Ne fonctionne pas.
   \section{\texttt{\textbackslash section}}
\end{document}

Les différents styles

Maintenant que nous connaissons les bases de minted, nous allons voir comment changer de style. Pour cela nous utilisons la commande \usemintedstyle. Elle prend en paramètre un style et l’applique à tous les codes (jusqu’à ce queusemintedstyle pour changer à nouveau de style). La liste des styles est disponible avec la commande pygmentize -L styles. Nous pouvons voir à quoi ils ressemblent en faisant des tests sur le site de Pygments.

Testons par exemple les styles monokay et xcode.

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[francais]{babel}
\usepackage{minted}

\usemintedstyle{monokay}

\begin{document}
   Avec le style \mintinline{latex}{monokay}.
   \inputminted{latex}{test.tex}
   \usemintedstyle{xcode}
   Avec le style \mintinline{latex}{xcode}.
   \inputminted{latex}{test.tex}
\end{document}

La commande \usemintedstyle prend aussi en paramètre facultatif le langage auquel doit s’appliquer le style choisi. Cela permet alors de préciser un style différent pour plusieurs langages. Nous pouvons alors choisir un style pour du Python et un autre pour du Ruby.

\usemintedstyle[python]{vim}
\usemintedstyle[ruby]{emacs}

\mint{python}|print('Hello word')|
\mint{ruby}|puts 'Hello word'|

Si nous voulons choisir un même style pour plusieurs langages, nous n’allons pas utiliser plusieurs fois \usemintesstyle, mais séparer les langages par une virgule dans le paramètre facultatif.

\usemintedstyle[python, ruby]{emacs}

Notons également qu’il est possible de choisir un style pour un bout de code en particulier. En effet, les commandes mint et mintinline ainsi que l’environnement minted prennent en paramètre facultatif des options. L’option style permet de choisir le style.

\mintinline[style = xcode]{python}|print("Hello word")|

Flottants

Tout comme les tableaux, nous pouvons rendre un bloc de code flottant en utilisant l’environnement listing qui fonctionne comme l’environnement figure. Bien sûr, nous pouvons y mettre une légende et y faire référence, et nous disposons même de la commande \listoflistings pour obtenir la liste des listings.

\begin{document}
Voici le code du document.

\begin{listing}
   \inputminted{latex}{test.tex}
   \caption{Code du document.}
   \label{lst:code_1}
\end{listing}

Le code du document (voir code \ref{lst:code_1} page \pageref{lst:code_1}
a pu être écrit facilement grâce à minted.

\listoflistings
\end{document}

C’est une bonne pratique de construire le nom des références en le faisant précéder par lst pour rappeler qu’il s’agit d’un code.

Si nous voulons la possibilité d’avoir une légende sans utiliser de flottants, nous pouvons utiliser le package caption. Avec lui, le code précédent se transforme de cette manière.

\usepackage{caption}
\usepackage{minted}

\begin{document}
Voici le code du document.

\begin{center}
   \inputminted{latex}{test.tex}
   \captionof{listing}{Code du document.}
   \label{lst:code_1}
\end{center}

Le code du document (voir code \ref{lst:code_1} page \pageref{lst:code_1}
a pu être écrit facilement grâce à minted.

\listoflistings
\end{document}

Nous remarquons que la liste des listings est toujours correcte.

Changer les noms

Nous pouvons changer le nom affiché devant les légendes (par défaut c’est « Listing ») en redéfinissant la commande \listingscaption. Nous pouvons alors afficher « Code source » à la place en plaçant ceci dans notre préambule.

\renewcommand{\listingscaption}{Code source}

De même, nous pouvons changer le titre de la liste des codes sources en redéfinissant la commande \listoflistingscaption.

\renewcommand{\listoflistingscaption}{Liste des codes sources}

Personnalisation

En plus du style, nous pouvons personnaliser les blocs de code que nous affichons de plusieurs manières (numéro de ligne, cadre, etc.).

Les options

Nous pouvons choisir plusieurs options grâce à la commande \setminted qui prend en paramètre un langage et les options que nous voilons pour les codes de ce langage. Les options choisies avec cette option s’appliquent aux blocs de code, mais aussi au code en ligne. Cependant, si nous voulons spécifier une option pour le code en ligne, nous pouvons utiliser la commande \setmintedinline qui fonctionne de la même manière.

Les options sont sous la forme clé=valeur, la valeur pouvant être omise s’il s’agit de true. Par exemple, l’option mathscope permet, si elle est mise à true d’activer le mode mathématique dans les commentaires des codes présentés.

\setminted{mathescape}

\begin{minted}{latex}
\[
    \exp(0) + 1 = 2 % Affiche $\exp(0) + 1 = 2$
\]   
\end{minted}

Nous pouvons, comme avec \usemintedstyle, indiquer en paramètre facultatif le ou les langages pour lesquels nous voulons ces options. En fait, style est aussi une option et utiliser \usemintedstyle équivaut à utiliser \setminted pour choisir la valeur de style.

De plus, l’environnement minted, tout comme les commandes \mint et \mintinline prennent aussi des options en paramètre facultatif. Cela permet alors de choisir des options pour un bloc de code particulier.

\begin{minted}[mathescape]{latex}
\[
    \exp(0) + 1 = 2 % Affiche $\exp(0) + 1 = 2$
\]   
\end{minted}

Maintenant, voyons quelques types d’options.

Les césures

Nous avons une bonne vingtaine d’options concernant les césures, c’est-à-dire la manière dont une ligne d’un code est coupée si nous sommes à la fin d’une ligne de notre document. La plus important d’entre elle, breaklines est un booléen, qui vaut false par défaut et permet s’il vaut true d’autoriser LaTeX à couper une ligne trop longue.

Normalement, les coupures ne se font qu’aux espaces, mais ceci peut être changé grâce à l’option breakafter qui prend pour valeur les caractères après lesquels la coupure est autorisée. Notons que les caractères spéciaux doivent être échappés (pour indiquer une accolade ouvrante, ce sera \{). Nous pouvons autoriser les coupures n’importe où grâce à l’option breakanywhere, un booléen qui vaut false par défaut. Bien sûr, ces deux options ne font effet que si breaklines est activée.

\begin{minted}[breaklines, breakafter=-\{\}\%+-*]{latex}
  En LaTeX, on écrit des maths facilement. $23 - 10 * 4 = 23 - 40 = -17$. 
\end{minted}

Nous remarquons ici qu’un symbole est inséré au début de la seconde ligne (après la coupure). Pour changer ce symbole, nous utiliserons l’option breaksymbol (ou l’option breaksymbolleft qui est strictement équivalente), sachant que pour n’avoir aucun symbole, il nous suffit d’utiliser breaksymbol={} ou breaksymbol=.

\begin{minted}[breaklines, breakafter=-\{\}\%+-*, breaksymbol = ]{latex}
  En LaTeX, on écrit des maths facilement. $23 - 10 * 4 = 23 - 40 = -17$. 
\end{minted}

Quand une ligne est coupée, il peut-être intéressant de garder le reste de la ligne au même niveau d’indentation que le début. Pour ce faire, nous allons utiliser l’option breakautoindent, un booléen valant true par défaut et permettant d’indenter le reste de la ligne. Nous pouvons même rajouter une indentation supplémentaire grâce à l’option breakindent, qui est une longueur. Cette longueur est rajoutée au début de chaque ligne coupée.

\begin{minted}[breaklines, breakafter=-+*/., breaksymbol = , breakindent = 3em]{python}
def f(x):
    print("La valeur de x + 4 est {}, celle de x + 5 est {}".format(x + 4, x + 5)) 
end
\end{minted}

L’indentation

Pour continuer avec l’indentation, voici une option utile pour placer l’indentation du code LaTeX dans le code que nous souhaitons afficher sans afficher cette indentation.

\begin{document}
   \begin{minted}{latex}
      \[
         2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
      \]
   \end{minted}
\end{document}

Ici les six espaces de l’indentation dues à notre code LaTeX seront aussi affichés. Pour ne pas les afficher, nous allons utiliser l’option gobble qui est un entier n. Ainsi les n premiers caractères de chaque ligne de code seront supprimés (ici nous voulons n = 6). En fait, nous pouvons même faire mieux grâce à l’option autogobble, un booléen, qui permet de supprimer tous les espaces blancs (espaces et tabulations) communs au début de chaque ligne. Notre code précédent se transforme de cette manière.

\begin{document}
   \begin{minted}[autogobble]{latex}
      \[
         2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
      \]
   \end{minted}
\end{document}

Les cadres

Nous pouvons bien entendu encadrer nos codes (bien sûr, ceci ne s’applique pas aux codes en ligne). Ceci se fait grâce à l’option frame qui peut prendre beaucoup de valeurs.

  • none, qui est la valeur par défaut, ne crée pas de cadre.
  • single crée un cadre complet.
  • leftline crée uniquement la ligne gauche du cadre.
  • topline crée uniquement la ligne en haut du cadre.
  • bottomline crée uniquement la ligne en bas du cadre.
  • topline crée uniquement la ligne en haut du cadre.
  • lines crée uniquement les lignes horizontales du cadre.
\begin{document}
   \begin{minted}[autogobble, frame = single]{latex}
      \[
         2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
      \]
   \end{minted}
   \begin{minted}[autogobble, frame = lines]{latex}
      \[
         2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
      \]
   \end{minted}
\end{document}

Numérotation

Pour numéroter les lignes de code, nous utiliserons l’option linenos (booléen valant true si nous voulons activer la numérotation). Chaque ligne de code est alors numéroté, la numérotation commençant à zéro pour chaque bloc de code (bien entendu, la numérotation n’a pas lieu pour les bouts de code dans le texte. Avec l’option \numbers (qui vaut auto par défaut), nous pouvons choisir de quel côté la numérotation est affichée (left, right ou both pour l’afficher des deux côtés).

De plus, nous pouvons choisir le premier nombre qui servira à numéroter les lignes grâce au paramètre firstnumber qui vaut auto par défaut. Nous pouvons lui donner comme valeur le nombre par lequel nous voulons commencer, mais aussi last, auquel cas, la numérotation continuera celle du précédent bloc de code.

\begin{minted}[autogobble, linenos, frame = single]{latex}
   \[   
      2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
   \]
\end{minted}
    
\begin{minted}[autogobble, linenos, firstnumber = last]{latex}
   \[
      2 * 3 = 2 + 2 + 2 = 4 + 2 = 6. 
   \]
\end{minted}

Ici, la numérotation du second bloc de code continue celle du premier. Nous remarquons de plus que la numérotation se fait en dehors du cadre.

Il y a plusieurs autres options. La documentation nous apprendra à les utiliser.

Un environnement pour un langage

Nous avons la possibilité de définir une commande pour un langage en utilisant la commande \newminted. Elle prend en paramètre un langage et les options que nous voulons.

\newminted{latex}{frame = single, style = xcode, autogobble}

Ici, nous indiquons que nous voulons créer un raccourci pour les code LaTeX et qu’avec ce raccourci, le code sera encadré et aura le style xcode. La commande \newminted crée alors l’environnement codelatex (et donc code<langage> pour un autre langage). Nous pouvons alors l’utiliser et observer le résultat.

\begin{latexcode}
   \begin{document}
      Un document LaTeX
   \end{document}
\end{latexcode}

La commande \newminted permet alors de ne pas spécifier les options à chaque usage de minted (tout comme \setminted) et de ne pas avoir à spécifier le langage à chaque fois.

La commande \newminted crée aussi un environnement étoilé code<langage> qui prend en second paramètre les options supplémentaires que nous pourrions vouloir pour notre code. Par exemple, si dans un document nous voulons tout nos codes LaTeX encadrés et avec le style xcode, et que pour un code particulier, nous voulons numéroter les lignes, l’environnement étoilé est utile.

\begin{latexcode*}{linenos}
   \begin{document}
      Un document LaTeX
   \end{document}
\end{latexcode*}

Il est possible de choisir le nom de l’environnement créé en le spécifiant en paramètre facultatif de \newminted.

\newminted[latex]{latex}{frame = single, style = xcode}

Nous pouvons aussi créer des commandes-raccourcis pour \mint, \mintinline et \inputminted, en utilisant respectivement les commandes \newmint, \newmintinline et \newmintedfile qui fonctionnent de la même manière que \newminted. Les noms par défaut des commandes raccourcis sont alors :

  • \<langage> pour \mint.
  • \<langage>inline pour \mintinline.
  • <langage>file pour \newmintedfile.

Toutes ces commandes nous permettent d’avoir quelque chose d’assez flexible.

Les options de minted

Numérotation

Le package minted a aussi des options (donc à préciser lorsqu’il est chargé). Par exemple, par défaut le compteur pour la numérotation des flottants (donc de l’environnement listing) n’est jamais remis à zéro. Nous pouvons utiliser l’option chapter ou l’option section pour le remettre à zéro à chaque chapitre ou à chaque section et avoir une numérotation adaptée. Essayons par exemple ce code sans rien, puis avec l’option chapter, et enfin avec l’option section.

\newmint[latex]{latex}{frame = single, style = xcode}

\begin{document}
   \chapter{Un}
      \begin{listing}
         \mint{latex}|\begin{document}|
         \caption{Légende}
      \end{listing}
      
   \chapter{Deux}
      \section{sec}
         \begin{listing}
            \mint{latex}|\begin{document}|
            \caption{Légende}
         \end{listing}
         
         \begin{listing}
            \mint{latex}|\begin{document}|
            \caption{Légende}
         \end{listing}
      \section{sec}
         \begin{listing}
            \mint{latex}|\begin{document}|
            \caption{Légende}
         \end{listing}      
\end{document}

Document final

Nous pouvons également choisir entre l’option draft et l’option final (donc entre un document brouillon et un document final), l’option par défaut étant final. L’option draft permet d’obtenir une compilation plus rapide. Pour cela, Pygmentize n’est pas utilisé (donc il n’y a pas de coloration syntaxique). Cela permet alors d’utiliser pdflatex sans -shell-escape. De même, en mode brouillon, autogobble ne fonctionne pas.

L’option draft peut être utile pour faire des tests, mais aussi dans le cas où nous obtenons des erreurs que nous voulons traquer et que l’apparence du code ne nous intéresse pas. Pour faire un ECM, cela peut également être utile.

Options de cache

Lorsque minted croise un bout de code à transformer, il appelle Pygments pour qu’il lui donne le code avec la coloration syntaxique appropriée. À chaque compilation, tout ces appels se font, et ce même si certains codes n’ont pas été modifiés ce qui peut augmenter le temps de compilation dans le cas de très gros documents. Heureusement, l’option cache (un booléen valant true par défaut) permet de mettre ces données en cache (dans un dossier qu’il crée dans le dossier du projet). Puisque ce booléen vaut true par défaut, nous n’avons rien à faire pour activer le cache.


Nous pouvons maintenant mettre du beau code dans nos documents. Bien sûr, nous n’avons pas vu toutes les options disponibles. Pour les voir toutes, il faut se référer à la documentation.

Merci à TD et Héziode pour leurs retours durant la bêta.

1 commentaire

Vous devez être connecté pour pouvoir poster un message.
Connexion

Pas encore inscrit ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte