Listings de code

Pour présenter joliment du code source, avec numéros de ligne et coloration syntaxique (mots-clés, commentaires et chaînes en couleurs différentes), les deux paquets de référence sont listings et minted. Le premier ne nécessite aucun outil externe et fonctionne partout; le second appelle le moteur externe Pygments pour une coloration beaucoup plus précise. Si vous voulez seulement reproduire le code tel qu’il a été saisi, la famille verbatim plus simple suffit.

Deux approches

Il existe deux voies pour composer du code source, fondées sur des idées différentes. listings est implémenté uniquement en macros LaTeX et ne demande aucun logiciel supplémentaire : \usepackage{listings} suffit, sur Overleaf comme dans une salle informatique verrouillée. minted, au contraire, confie le travail à Pygments, un véritable analyseur lexical écrit en Python, puis réintègre le résultat dans LaTeX. Comme Pygments analyse réellement des centaines de langages, sa coloration est bien plus précise que celle que listings peut fournir.

Cette différence donne directement le critère de choix : listings pour la simplicité et la portabilité, minted pour la qualité de la coloration. Comme minted lance un programme externe, il exige l’autorisation spéciale appelée shell escape (expliquée plus bas) et peut ne pas fonctionner dans les environnements restreints. Si vous voulez seulement reproduire le code verbatim, sans couleurs ni numéros de ligne, verbatim ou fancyvrb sont plus légers; voir la page « Verbatim ».

Bases de listings

Chargez d’abord \usepackage{listings}. Un bloc de code se place dans l’environnement lstlisting; un fichier externe complet s’inclut avec \lstinputlisting; et un court fragment dans le texte avec \lstinline. Plutôt que de répéter les options à chaque appel, la pratique courante consiste à regrouper langue et apparence une fois dans le préambule avec \lstset{...}.

\usepackage{listings}
\usepackage{xcolor}

\lstset{
  language=Python,                 % 言語 / language
  basicstyle=\ttfamily\small,       % 本文の書体 / base font
  keywordstyle=\color{blue}\bfseries,
  commentstyle=\color{teal}\itshape,
  stringstyle=\color{red!60!black},
  numbers=left,                    % 行番号を左に / line numbers on the left
  numberstyle=\tiny\color{gray},
  frame=single,                    % 枠線 / a single-line frame
  breaklines=true,                 % 長い行を折り返す / wrap long lines
  showstringspaces=false,          % 文字列中の空白を記号化しない
  tabsize=2,
}

\begin{lstlisting}[caption={階乗を計算する}, label=lst:fact]
def factorial(n):
    # 再帰で階乗を求める
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{lstlisting}

Les principales clés de \lstset sont les suivantes. basicstyle fixe la police générale (\ttfamily\small est le choix courant); keywordstyle, commentstyle et stringstyle règlent l’apparence des mots-clés, commentaires et chaînes. numbers=left place les numéros de ligne à gauche, et numberstyle les formate. frame=single trace un cadre, breaklines=true coupe les longues lignes, et caption= avec label= transforme le bloc en « listing » numéroté, comme une figure ou une table, référable par \ref.

Chaque bloc peut remplacer les options dans [ ], par exemple \begin{lstlisting}[language=C, numbers=none]. Pour un fichier externe, vous pouvez même extraire un intervalle de lignes : \lstinputlisting[language=Python, firstline=37, lastline=45]{sample.py}. Pour insérer du code dans le texte, choisissez un délimiteur comme avec \verb, par exemple \lstinline|while (i < n)|.

Limites de listings (UTF-8 et japonais)

La coloration de listings est une approximation fondée sur une liste de mots-clés propre à chaque langage et sur des règles simples; elle n’est pas aussi intelligente qu’un vrai lexer. La coloration dépendante du contexte, par exemple quand le même mot est tantôt un nom de type tantôt une variable, lui pose problème, et les défauts se voient davantage dans les langages complexes. C’est une limite de l’approche elle-même.

Un second piège pratique concerne les caractères multioctets. listings ne suppose pas UTF-8 par défaut; des commentaires japonais dans le code peuvent donc être corrompus ou mal alignés. Deux remèdes existent. Si vous saisissez le code directement dans le corps, il faut lui apprendre les caractères un par un avec literate=, comme dans \lstset{... literate={あ}{{あ}}1 ...}; cela devient vite impraticable. Si vous incluez un fichier externe, la solution simple consiste à charger listingsutf8 à la place de listings (cela ne fonctionne qu’avec \lstinputlisting).

Bases de minted (Pygments)

Avec \usepackage{minted}, les blocs de code se placent dans l’environnement minted. La grande différence avec listings est que le nom du langage est le premier argument : \begin{minted}{python}. Il existe aussi le raccourci sur une ligne \mint, la commande en ligne \mintinline et \inputminted pour les fichiers externes.

\usepackage{minted}

% ドキュメント全体の配色テーマ / a color theme for the whole document
\usemintedstyle{monokai}

\begin{minted}[linenos, bgcolor=black!90, fontsize=\small]{python}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{minted}

% 単一行 / a single line
\mint{python}|print("Hello!")|

% 本文中に埋め込む / inline in running text
\mintinline{python}{print("Hello!")}

% 外部ファイルを取り込む / include an external file
\inputminted[linenos]{python}{sample.py}

Les options viennent juste après le nom de l’environnement, dans [ ], sous forme key=value. Les plus courantes sont linenos pour les numéros de ligne, style= pour choisir un thème Pygments (monokai, etc.; galerie sur pygments.org/styles), bgcolor= pour une couleur de fond et fontsize=. Pour appliquer un thème à tout le document, utilisez \usemintedstyle{monokai}; pour fixer plus largement des valeurs par défaut, utilisez \setminted{style=monokai, linenos}. Pour un langage non pris en charge par Pygments, ou pour couper volontairement la coloration, indiquez text comme langage.

Le code de \mint et \mintinline se délimite comme avec \verb : par une paire de délimiteurs correspondants (n’importe quelle ponctuation, par exemple |...|) ou par des accolades {...}. Attention, \mint n’est pas fait pour l’usage en ligne; il évite seulement d’écrire l’environnement quand le code tient sur une ligne. Pour intégrer du code dans le texte courant, utilisez toujours \mintinline.

Shell escape (le point délicat de minted)

Comme minted lance un programme Python externe, il faut compiler avec shell escape activé, c’est-à-dire l’autorisation pour LaTeX d’exécuter des commandes externes. Avec pdfLaTeX, passez l’option -shell-escape.

pdflatex -shell-escape document.tex

Il faut aussi Python 3.8+ et Pygments en dessous. Cela dit, la situation s’est améliorée avec minted version 3, une réécriture complète publiée à partir de 2025. Installé par un gestionnaire de paquets TeX (tlmgr install minted, etc.), tout le côté Python, Pygments compris, est fourni dans l’arbre TeX sous la forme d’un exécutable dédié latexminted; il n’y a donc plus d’installation séparée de Pygments. De plus, latexminted est conçu pour le shell escape restreint : dans TeX Live 2024 et ultérieur, il est enregistré comme exécutable de confiance, si bien que vous pouvez compiler sans -shell-escape du tout.

Malgré cela, avec TeX Live avant 2024 et avec MiKTeX, il faut encore -shell-escape (-enable-write18 sous MiKTeX). Comme shell escape peut exécuter des commandes externes arbitraires, ne l’utilisez pas sur des documents provenant de sources non fiables. À l’inverse, il ne pose pas de problème dans un environnement préconfiguré comme Overleaf, ou en local avec votre propre code (Overleaf prend minted en charge directement). Cette combinaison « dépendance externe plus shell escape » est le principal compromis face à listings, plus portable.

Que choisir ?

• Vous voulez zéro configuration et l’assurance que cela marche partout → listings. Sur Overleaf ou une machine verrouillée, \usepackage suffit.
• La précision de la coloration et la couverture des langages priment → minted. La coloration par Pygments est d’un autre niveau.
• Vous ne pouvez pas installer d’outils externes / utiliser shell escape → listings, sans hésitation.
• Vous voulez seulement reproduire du code verbatim, sans couleur → verbatim ou fancyvrb suffisent (voir « Verbatim »).
• Vous voulez écrire un algorithme en pseudocode → les paquets dédiés algorithm2e / algpseudocode (voir « Algorithms »).