Verbatim

Il arrive de vouloir faire apparaître du texte exactement comme il a été tapé : commandes, commentaires et caractères spéciaux désactivés, dans une police à chasse fixe de type machine à écrire. Ce mécanisme s’appelle verbatim. Cette page présente \verb en ligne, l’environnement de bloc verbatim, \verbatiminput pour insérer un fichier entier, la limitation importante qui interdit ces formes dans l’argument d’une autre commande, avec les contournements, puis alltt, qui laisse quelques commandes actives, et enfin fancyvrb pour les numéros de ligne et les cadres.

L’environnement verbatim et \verb

La base de la sortie littérale est l’environnement verbatim, intégré à LaTeX. Tout ce qui se trouve entre \begin{verbatim} et \end{verbatim} est imprimé tel quel : une barre oblique inverse ne lance plus une commande mais s’imprime comme \, % ne commence pas un commentaire, les espaces et retours à la ligne sont conservés, et le bloc entier est composé en police machine à écrire (\tt). C’est idéal pour du code source ou pour montrer des chaînes riches en $ et &.

\begin{verbatim}
for i in range(3):
    print("100% & $5")   # nothing here is interpreted
\end{verbatim}

Il n’y a qu’une règle impérative : la chaîne \end{verbatim} ne doit pas apparaître dans l’environnement, car LaTeX l’interprète aussitôt comme la fin de celui-ci. Si vous devez vraiment afficher le texte \end{verbatim}, changez le terminateur avec fancyvrb ci-dessous ou isolez ce fragment avec \verb.

Pour insérer un petit fragment verbatim au milieu d’une ligne, utilisez la forme en ligne \verb. Le principe : placez un délimiteur juste après \verb, puis le texte à rendre littéralement, puis le même délimiteur. Le délimiteur peut être n’importe quel caractère non alphabétique absent du texte. Le choix courant est \verb|...|, mais si | figure dans le contenu, choisissez autre chose, par exemple \verb!...! ou \verb+...+. Ne mettez pas d’espace entre \verb et son délimiteur.

The macro \verb|\textbf{...}| sets bold text, and
the pipe itself is shown with \verb!a|b! instead.

La forme étoilée \verb* imprime les espaces internes sous forme d’espace visible (␣), utile dans les exemples de code où leur nombre exact compte. De même, l’environnement verbatim* affiche les espaces du bloc comme ␣.

Cela dit, si votre seul but est une chaîne contenant souvent ~, #, % ou _, par exemple une URL, \url{...} du package url ou hyperref peut être plus commode, car il sait aussi couper la ligne à des endroits raisonnables.

Composer un fichier entier (\verbatiminput)

Pour insérer tel quel le contenu d’un fichier externe, le package verbatim, qui fait partie des outils requis de LaTeX, fournit \verbatiminput{filename}. Chargez \usepackage{verbatim} dans le préambule, puis écrivez \verbatiminput{program.py} dans le corps : chaque ligne du fichier sera composée verbatim. Contrairement à une copie manuelle dans le manuscrit, modifier le fichier source met automatiquement la sortie à jour ; il n’y a pas à synchroniser code et document à la main.

\usepackage{verbatim}
% ...
\verbatiminput{hello.py}

Le même package verbatim ajoute aussi un environnement comment qui ignore tout ce qui se trouve entre \begin{comment} et \end{comment}. Il ne sert pas à une sortie littérale, mais à *ne rien imprimer*, par exemple pour mettre temporairement de côté un passage de brouillon.

Impossible dans l’argument d’une commande

C’est le piège le plus courant avec verbatim. \verb et l’environnement verbatim ne peuvent pas apparaître dans l’argument d’une autre commande, par exemple dans \section{\verb|code|}, une \footnote{...}, une cellule de table ou une \caption{...}. La raison tient aux codes de catégorie, les catcodes, c’est-à-dire le rôle attribué à chaque caractère. \verb change les catcodes juste avant de lire son argument, mais l’argument d’une commande a déjà été converti en liste de tokens avec les catcodes normaux au moment de l’appel ; l’interprétation est donc terminée avant que \verb puisse changer quoi que ce soit. Cette écriture produit généralement une erreur.

Il existe deux contournements. Le premier est le package cprotect : il suffit de préfixer la commande problématique par \cprotect pour que le verbatim dans son argument passe. Par exemple, écrivez \cprotect\section{\verb"foo"}. Il existe aussi \cprotEnv pour protéger le \begin d’un environnement.

L’autre solution est \SaveVerb / \UseVerb de fancyvrb : une approche en deux temps où l’on enregistre d’abord le texte verbatim sous un nom, puis où l’on appelle simplement ce nom dans l’argument. Enregistrez avec \SaveVerb{label}|verbatim text|, puis composez avec \UseVerb{label}.

% Workaround 1: cprotect
\usepackage{cprotect}
\cprotect\section{The \verb|\foo| command}

% Workaround 2: fancyvrb SaveVerb / UseVerb
\usepackage{fancyvrb}
\SaveVerb{cmd}|\foo|
\section{The \UseVerb{cmd} command}

Garder des commandes actives avec alltt

En verbatim ordinaire, on ne peut pas mettre en valeur ou colorer seulement une partie d’un exemple de code, car les commandes sont désactivées. Le package alltt, lui aussi inclus dans la distribution LaTeX standard, et son environnement alltt résolvent cela. alltt compose le texte en chasse fixe et tel que tapé, presque comme verbatim, sauf que la barre oblique inverse \ et les accolades { et } gardent leur sens habituel. On obtient donc un aspect verbatim tout en pouvant exécuter des commandes LaTeX à l’intérieur.

\usepackage{alltt}
% ...
\begin{alltt}
def \textbf{greet}(name):
    return "Hi, " + name   \textit{# a comment}
\end{alltt}

Dans cet exemple, le nom de fonction greet devient gras et le commentaire italique, tandis que tout le reste reste exactement tel que tapé. En contrepartie, pour imprimer littéralement les trois caractères \, {, }, il faut les écrire sous forme \textbackslash, \{, \} ; l’environnement verbatim, lui, les imprime directement. Utilisez alltt pour ajouter une légère mise en forme à la main, et verbatim quand tout doit rester strictement tel quel.

Numéros de ligne et cadres avec fancyvrb

Le verbatim intégré ne propose ni numéros de ligne ni cadres. Le choix plus puissant est le package fancyvrb, centré sur l’environnement Verbatim avec V majuscule, distinct de verbatim en minuscules. Les options se donnent par environnement, comme \begin{Verbatim}[key=value, ...], ou globalement depuis le préambule avec \fvset{key=value, ...}.

Les options les plus courantes : numbers=left ou right ajoute des numéros de ligne, frame=single trace un cadre autour de tout le bloc, et fontsize=\small fixe la taille de police. commandchars permet en outre de garder quelques commandes actives dans le texte autrement verbatim.

L’exemple suivant est un bloc Verbatim avec numéros de ligne à gauche, cadre simple et police légèrement plus petite.

\usepackage{fancyvrb}
% ...
\begin{Verbatim}[numbers=left, frame=single, fontsize=\small]
def greet(name):
    return "Hello, " + name
\end{Verbatim}

Avec commandchars=\\\{\}, les caractères \, {, } servent, dans le texte verbatim, de caractère d’échappement et de délimiteurs de groupe ; on peut donc y insérer des commandes comme avec alltt. Il existe aussi \VerbatimInput[options]{filename} pour importer un fichier entier ; contrairement à \verbatiminput, il accepte les options ci-dessus. Enfin, grâce à \SaveVerb / \UseVerb, déjà vus, le verbatim fonctionne même dans les arguments de commandes.

Dernière réserve : tout ce qui précède sert à imprimer du texte tel quel, et non à faire de la coloration syntaxique comme le coloriage des mots-clés. Pour présenter du code source avec couleurs et mise en forme, les bons outils sont le package spécialisé listings ou minted, qui utilise Pygments de Python ; c’est traité dans la page « Code listings ».