standalone

standalone est une classe LaTeX qui compose une seule chose — une figure, un dessin TikZ, un tableau — en une page rognée à la taille de son contenu. Sa valeur tient moins au rognage qu’au fait qu’un même fichier a deux visages : compilez figure.tex seul et vous obtenez un PDF de la seule figure ; incluez-le par \input depuis un article et le même fichier entre dans le corps sans qu’un caractère change. Le mécanisme de rognage a lui aussi son histoire. Avant l’option crop, aujourd’hui par défaut, standalone employait le package preview, issu de l’AUCTeX d’Emacs — le code même qui fait apparaître les aperçus de formules dans l’éditeur. Cette page traite de la classe et du package : le fonctionnement de border=, multi et subpreambles, et les erreurs que l’on rencontre vraiment. Transformer la figure finie en PNG ou SVG relève d’une autre page.

Utiliser un même fichier de figure seul et dans un article

Dès qu’un document grossit, on veut mettre les figures dans leurs propres fichiers. Mais compiler un tel fichier seul oblige à réécrire l’ossature — \documentclass, \begin{document} — à chaque fois, et la sortie n’est que la figure posée dans un coin d’une grande page blanche de texte. La classe standalone règle les deux d’un coup. Placez \documentclass{standalone} en tête du fichier de figure : il se compile seul et la sortie est rognée à la taille du contenu — une page de PDF, DVI ou PS, sans numéro de page, en-tête ni pied.

% figure.tex — a figure that is its own document
\documentclass[tikz,border=2pt]{standalone}
\begin{document}
\begin{tikzpicture}
  \draw[thick,->] (0,0) -- (3,0) node[right] {$x$};
  \draw[blue,thick] (0,0) .. controls (1,2) .. (3,1);
\end{tikzpicture}
\end{document}

standalone se présente en deux moitiés : la classe utilisée dans le fichier de figure (\documentclass{standalone}) et le package chargé dans le document principal (\usepackage{standalone}). La classe joue le rôle « composer un bloc seul », le package celui de « faire entrer ce bloc dans le corps ». C’est l’œuvre de Martin Scharrer ; la version présente dans TeX Live 2024 est la v1.3b, d’octobre 2022. La classe requiert xkeyval ; le package y ajoute currfile, gincltex, filemod et adjustbox. Tous sont fournis avec TeX Live et MiKTeX.

crop contre preview, et où le défaut est réellement fixé

Le défaut est crop, avec une marge de 0pt — mais ce défaut se trouve dans le fichier de configuration standalone.cfg, non dans la classe. standalone.cls lui-même a pour valeurs par défaut preview et 0.50001bp, comme le faisait la v0.x ; puis, juste avant le traitement des options, standalone.cfg est lu et écrase les deux par \standaloneconfig{crop} et \standaloneconfig{border=0pt}. Ce dispositif à deux étages est utile : déposez votre propre standalone.cfg dans le répertoire du projet ou dans un arbre TEXMF local et vous changez le défaut de tous les fichiers standalone de cet environnement. Le cfg de la distribution est écrasé à chaque mise à jour ; gardez donc vos réglages dans un fichier à part.

crop et preview s’excluent : donnez les deux et la dernière l’emporte, et l’une comme l’autre impose float=false. La différence pratique apparaît à la mesure. Une figure ne contenant qu’un rectangle de 2 cm × 1 cm, compilée sous TeX Live 2024, sort en 57,09 × 28,75 bp avec le crop par défaut. Ajoutez maintenant une ligne blanche avant \end{document} : sous crop, rien ne bouge ; sous preview, la largeur bondit à 343,71 bp. La ligne blanche vaut fin de paragraphe, et le contenu devient un paragraphe large de tout \linewidth. C’est le classique « grand blanc à droite de ma figure », et c’est précisément pour l’éviter que crop est devenu le défaut. preview subsiste parce qu’il sert d’issue de secours quand les ombrages TikZ se comportent mal sous XeLaTeX.

Ajouter de la marge avec border=, et comment les valeurs sont lues

L’option la plus employée est border= (alias margin=). Une valeur s’applique aux quatre côtés, deux à l’horizontale et à la verticale, quatre à gauche, bas, droite et haut dans cet ordre. Pour passer plusieurs valeurs séparées par des espaces, entourez le tout d’accolades : border={10pt 5pt}. Un nombre nu, sans unité, est lu en bp, le point PostScript. Mesuré sur la même figure de 57,09 × 28,75 bp, border=5pt donne 67,05 × 38,71 bp (5 pt, soit environ 4,98 bp, par côté) et border={10pt 5pt} donne 77,02 × 38,71 bp. Comme border et varwidth ne sont pas des réglages globaux, on peut les modifier ensuite avec \standaloneconfig{...} — dans le préambule, voire au milieu du document si multi est activé.

Tirer plusieurs figures d’un seul fichier (multi)

Par défaut, tout ce qui se trouve dans l’environnement document devient une seule page. Activez multi et chaque occurrence d’un environnement désigné est rognée sur sa propre page. Voilà pourquoi \documentclass[tikz]{standalone} est si commode : en interne, l’option tikz fixe multi=tikzpicture et varwidth=false, si bien que deux environnements tikzpicture à la suite donnent un PDF de deux pages. (pstricks fait de même pour PSTricks.) Pour viser votre propre environnement, déclarez \standaloneenv{myfig} et ne placez rien en dehors ; n’ajoutez ignorerest que si du contenu doit absolument s’intercaler. Il existe aussi une option math, qui découpe les formules une à une et fixe multi et ignoreempty avec une marge de 0.50001bp.

Les erreurs et symptômes que l’on rencontre vraiment

Chaque erreur de standalone a une cause nette, et l’on remonte du symptôme à celle-ci. La plus fréquente : placer un environnement figure dans le fichier standalone. Avec crop ou preview actif, on obtient ! LaTeX Error: Not in outer par mode. ou un message « Float(s) lost ». Le rognage consiste à enfermer le contenu dans une boîte, et un flottant ne peut pas flotter dans une boîte. Comme crop et preview fixent d’eux-mêmes float=false, cette erreur ne peut survenir que si vous avez ensuite écrit float=true à la main. Gardez les flottants dans le document principal et ne laissez que le dessin dans le fichier standalone.

• Grand blanc à droite de la figure. Le contenu est devenu un paragraphe. Supprimez la ligne blanche ou un \par superflu avant \end{document}, ajoutez varwidth, ou déclarez l’environnement avec multi et \standaloneenv.
• Le côté droit est rogné. Le maximum de varwidth (par défaut \linewidth) est trop étroit. Élargissez-le, par exemple varwidth=15cm, ou désactivez-le par varwidth=false.
• Une valeur d’option est refusée. Tout autre chose que true ou false sur une clé booléenne interrompt la compilation, par exemple avec ! Class standalone Error: Invalid value 'maybe' for boolean key 'crop'.
• Une page superflue apparaît dans un fichier multipage. multi est actif et du contenu est composé hors des environnements déclarés. Retirez-le ou activez ignorerest.
• Le rognage se comporte mal sur la route DVI. En mode DVI, crop émet des commandes PostScript, et le manuel qualifie lui-même ce code d’expérimental. Sous latex simple, preview est parfois plus sûr.

Côté package : inclure la figure par \input

Chargez \usepackage{standalone} le plus tôt possible dans le préambule du document principal : le package redéfinit \documentclass de sorte que, pour un fichier de figure inclus par \input, tout ce qui va de son \documentclass à son \begin{document} soit ignoré. L’environnement document du fichier de figure est traité comme un simple groupe TeX, et tout ce qui suit \end{document} est ignoré aussi ; seul le contenu du fichier entre donc dans le corps. Une condition : le document principal doit charger tous les packages nécessaires aux fichiers de figure. Le préambule du fichier étant sauté, tikz et consorts ne peuvent être chargés que par le fichier principal.

\documentclass{article}
% load the standalone package early
\usepackage{standalone}
% and everything the sub-files need
\usepackage{tikz}

\begin{document}
\begin{figure}
  \input{figure}%  the standalone file from above
  \caption{A sub-file}
\end{figure}
\end{document}

Si recopier les préambules à la main vous rebute, \usepackage[subpreambles=true]{standalone} les collecte : le préambule de chaque fichier de figure est réuni dans un fichier auxiliaire puis repris dans le document principal au passage suivant. Ajoutez sort et les packages chargés par chaque figure, avec leurs options, sont accumulés sans doublons et chargés via \PassOptionsToPackage, ce qui évite les conflits d’options. Si vous préférez les transcrire vous-même, print en écrit la liste — mais c’est un mode de collecte pur et, comme le dit sans détour le message Package standalone Warning: Running 'standalone' package in sub-preamble print mode. All body content of file 'figure.tex' is ignored!, le corps n’est pas composé.

\includestandalone et mode= : source ou image

Écrivez \includestandalone{figure} au lieu de \input et l’option de package mode= détermine comment la figure arrive. Les valeurs sont tex (inclure la source — le défaut), image (inclure un PDF ou EPS existant via \includegraphics), image|tex (l’image si elle existe, la source sinon), build (construire à chaque fois), buildmissing (construire seulement si l’image manque) et buildnew (construire seulement si la source est plus récente ; indisponible sous XeLaTeX). L’enjeu est la vitesse : une figure complexe n’a pas à être recomposée à chaque passage du document principal. Seuls les trois modes de construction appellent une commande externe, et il leur faut -shell-escape. Le manuel précise que, si la construction échoue, un avertissement est émis et la source est incluse à la place.

Tout ce qui vient ensuite — transformer le PDF rogné en PNG ou SVG, détourer un PDF existant avec pdfcrop, piloter dvisvgm, les réglages passés à convert= — relève de la page sur l’export des figures en images. Du côté de la classe, il ne reste qu’une chose à retenir : ne pas créer la marge est plus rapide et plus exact que de la couper après coup.

Intégrer standalone dans un projet

Dans un vrai article, traiter chaque fichier standalone comme la source d’une figure, sous une forme vérifiable indépendamment du texte, est payant. Le fichier principal s’appelle paper.tex, les figures vivent sous figures/, et le texte ne dit que \input{figures/energy-flow}. Celui qui révise une figure compile alors figures/energy-flow.tex seul, tandis que le document principal ne gère que légendes, numérotation et renvois. En relecture, joignez ce PDF d’une page et organisez une passe consacrée aux seules figures : le dessin s’améliore sans attendre la recompilation de tout le manuscrit.

paper.tex
standalone.cfg          # optional: your own defaults for every figure
figures/
  energy-flow.tex
  apparatus-layout.tex
  timing-diagram.tex

Lorsque le contenu d’une figure doit suivre les mêmes règles de composition que le corps du texte, accordez la classe sous-jacente avec class=. Pour une figure portant des libellés japonais, \documentclass[class=jsarticle,border=5pt]{standalone} sous upLaTeX — ou class=ltjsarticle sous LuaLaTeX — aligne l’espacement entre caractères et les fontes sur le texte principal. La classe et le package partagent aussi \ifstandalone, \IfStandalone{seul}{inclus} et \onlyifstandalone{...} : de quoi n’afficher une échelle ou un cadre de débogage que dans le fichier de figure, en une ligne.

En quoi subfiles et TikZ external diffèrent

Deux mécanismes visent des fins voisines, et tous deux fonctionnent en sens inverse. Avec subfiles, un sous-fichier importe le préambule du document principal ; standalone fait l’inverse et permet de rassembler les préambules des sous-fichiers dans le document principal. standalone convient donc à la réutilisation d’une même figure dans plusieurs documents — article, exposé, thèse — tandis que subfiles convient à un découpage par chapitres où principal et sous-fichier se correspondent un à un. La bibliothèque external de TikZ écrit des images temporaires depuis le fichier principal, de nouveau en sens contraire. Cela dit, \includestandalone[mode=buildnew] procure au fond le même effet de mise en cache des dessins coûteux, tout en gardant la figure dans un fichier autonome.