standalone

standalone est une classe qui compose un seul bloc — figure, dessin TikZ, tableau — comme un document autonome. La sortie est rognée au plus près du contenu : un PDF de la seule figure, sans page autour, numéro de page ni marge. Associée au paquet du même nom, cette figure peut être incluse telle quelle dans le document principal avec \input. Écrite par Martin Scharrer, elle permet à une même figure de servir seule ou comme partie d’un document plus grand.

À quoi sert standalone

Quand on rédige un gros document, on veut souvent mettre les figures et dessins TikZ dans des fichiers séparés, puis les inclure dans le corps du texte. Mais pour compiler et vérifier un tel fichier seul, il faut sans cesse ajouter une ossature — \documentclass, \begin{document} — et la sortie n’est que la figure posée dans un coin d’une grande page blanche. La classe standalone règle les deux problèmes. Placez \documentclass{standalone} en tête du fichier de figure : ce bloc se compile seul, avec une sortie rognée exactement à la taille du contenu — PDF (ou DVI/PS) sans numéro de page, en-tête ni pied.

standalone a deux faces. L’une est la classe utilisée dans le fichier de figure (\documentclass{standalone}) ; l’autre est le paquet chargé dans le document principal (\usepackage{standalone}). La classe sert à « composer un bloc seul », le paquet à « inclure ce bloc dans le document principal » : les deux vont ensemble. Commençons par la classe.

La classe et le paquet standalone exigent tous deux xkeyval. Le paquet a en plus besoin de currfile (qui utilise filehook en interne) pour suivre les noms des fichiers inclus, ainsi que de gincltex et filemod pour la fonction de compilation vers une image. Tous sont fournis avec TeX Live et MiKTeX.

Utilisation comme classe

On l’utilise comme un document LaTeX ordinaire. Choisissez la classe avec \documentclass{standalone}, chargez dans le préambule les paquets nécessaires à la figure (pour TikZ, tikz, etc.), puis écrivez le contenu directement entre \begin{document} et \end{document}. La classe active par défaut l’option crop (voir plus bas), qui rogne la sortie à la taille du contenu.

\documentclass{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
  \draw (0,0) rectangle (2,1) node[midway] {Example};
\end{tikzpicture}
\end{document}

Compilé seul, cet exemple produit un PDF d’une page rogné au seul rectangle. Deux points demandent de l’attention : ne laissez pas de lignes blanches avant ou après le contenu, et placez \begin{document} et \end{document} chacun sur sa propre ligne. La classe standalone traite tout le contenu comme un bloc ; une ligne blanche finale est donc lue comme un paragraphe large de \linewidth, ce qui peut ajouter un espace parasite à droite de la figure.

Pour un dessin TikZ, la voie pratique est l’option tikz, comme dans \documentclass[tikz]{standalone}. Elle charge le paquet tikz et configure même l’environnement tikzpicture pour qu’il soit rogné sur sa propre page (en interne, elle fixe multi=tikzpicture et varwidth=false). Pour les dessins PSTricks, l’option correspondante est pstricks.

Principales options de classe

Les options se placent entre crochets, séparées par des virgules. La plupart des options de standalone sont booléennes : si la valeur est omise, elle vaut true ; sauf indication contraire, la valeur initiale est false. Elles ne sont pas transmises à la classe sous-jacente (article par défaut) : standalone les consomme lui-même pour éviter les conflits de noms. Les plus importantes suivent.

L’option que l’on utilise le plus est border. Avec \documentclass[border=5pt]{standalone}, la figure rognée reçoit 5pt de marge sur les quatre côtés. Pour passer plusieurs valeurs séparées par des espaces, mettez toute la valeur entre accolades : border={10pt 5pt}. Comme border et varwidth n’ont pas d’effet global, vous pouvez les modifier plus tard avec \standaloneconfig{...} — dans le préambule, voire au milieu du document si multi est activé.

Une note historique : avant la v1.0, l’option preview était la valeur par défaut, avec une marge par défaut d’environ 0.5bp. Depuis la v1.0, crop est la valeur par défaut et la marge est passée à 0pt. Pour retrouver l’ancien comportement, placez \standaloneconfig{preview,border=0.50001bp} dans le fichier de configuration, ou indiquez explicitement ces options.

L’inclure comme paquet

Le paquet est l’autre face de standalone. Chargez \usepackage{standalone} le plus tôt possible dans le préambule du document principal : il redéfinit \documentclass de sorte que, lors d’un \input, tout ce qui va du \documentclass du fichier de figure à son \begin{document} soit ignoré. L’environnement document du fichier de figure est traité comme un simple groupe TeX, tandis que le véritable environnement document du document principal reste intact (tout ce qui suit \end{document} est également ignoré). En pratique, le préambule du fichier de figure est retiré à l’inclusion, et un simple \input{figure} fait entrer seulement le contenu dans le corps.

La condition préalable est que le document principal charge lui-même tous les paquets nécessaires aux fichiers de figure. Comme le préambule du fichier de figure est ignoré lors de l’inclusion, les paquets comme tikz doivent être chargés par le document principal. Voici l’exemple officiel : un document principal charge le paquet standalone et inclut une figure avec \input dans un environnement figure.

\documentclass{article}
% load the standalone package early
\usepackage{standalone}
% load 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}

L’idée est que le même figure.tex fonctionne sans changer un seul caractère, seul ou via le document principal. Compilé seul, il devient un PDF d’une page rogné ; inclus par \input, il dépose seulement la figure dans le corps. Il est recommandé de gérer les flottants dans le document principal : gardez l’environnement figure là-bas et ne mettez que le contenu dans le fichier standalone (dans la classe standalone, float vaut false par défaut pour que crop/preview puissent fonctionner).

Si vous voulez que le document principal collecte automatiquement les préambules des fichiers de figure, chargez \usepackage[subpreambles=true]{standalone}. Le préambule de chaque fichier est alors regroupé dans un fichier auxiliaire et repris dans le document principal au passage suivant. Ajoutez l’option sort : les paquets et leurs options, chargés par chaque figure, sont accumulés sans doublons puis chargés via \PassOptionsToPackage, ce qui évite les conflits d’options. Si vous préférez les recopier à la main dans le préambule principal, l’option print écrit la liste.

Compiler en images et mécanismes voisins

standalone peut aussi transformer une figure en image au lieu d’inclure sa source. Dans le document principal, écrivez \includestandalone{figure} à la place de \input{figure} : le fichier de figure est compilé séparément si nécessaire pour produire une image (un PDF, par exemple), puis celle-ci est incluse avec \includegraphics. L’avantage est qu’une figure complexe n’a pas besoin d’être recompilée à chaque fois, ce qui accélère la compilation principale. Comme cette fonction appelle une commande externe, elle exige l’option -shell-escape à la compilation.

En outre, des options comme convert, png, jpg et svg activent une fonction de conversion qui exporte le fichier standalone en image (un outil externe de conversion est nécessaire). C’est pratique pour distribuer une figure seule en PNG ou SVG.

Deux mécanismes voisins visent des besoins proches : subfiles et la bibliothèque external de TikZ. subfiles fonctionne dans l’autre sens : un sous-fichier importe le préambule du document *principal*, alors que standalone permet d’importer le préambule d’un sous-fichier *dans* le document principal. standalone convient donc à la réutilisation d’une même figure dans plusieurs documents (article, présentation, thèse), tandis que subfiles convient à une relation un-à-un entre document principal et sous-fichier. La bibliothèque external de TikZ écrit des images temporaires depuis le fichier principal, dans le sens opposé à standalone.

Vérifications avant d’adopter une figure

Un fichier standalone vaut parce qu’il compile seul ; construisez donc la figure séparément et inspectez le PDF avant de l’inclure dans le document principal. Dans une thèse ou un article, on révise souvent seulement une figure : nommez-la par son rôle, par exemple figures/experiment-flow.tex, et laissez le texte principal dire seulement \input{figures/experiment-flow}. Le remplacement, la réutilisation et la relecture restent simples.

• Regarder la marge. Si un bord est coupé, ajoutez border=2pt ou border=5pt ; si la marge est trop large, suspectez une ligne blanche finale ou un \par inutile.
• Aligner les préambules. Les paquets et réglages utilisés par la figure, comme tikz, les couleurs ou les polices, doivent aussi être chargés par le document principal. Le préambule du sous-fichier est normalement ignoré à l’inclusion.
• Garder les flottants dans le fichier principal. Placez l’environnement figure, la légende et le label dans le document principal ; ne laissez dans le fichier standalone que le dessin lui-même.
• Reconstruire avant remise. Si vous utilisez \includestandalone ou la conversion en images, faites une compilation propre avant la remise pour éviter les anciens PDF ou PNG en cache.

L’intégrer dans un projet

Dans un vrai article ou document technique, traitez le fichier standalone comme la source de la figure, gardée dans une forme vérifiable séparément du texte principal. Par exemple, gardez le fichier principal comme paper.tex, mettez les figures sous figures/, et laissez le texte principal dire seulement \input{figures/energy-flow}. La personne qui révise la figure peut alors compiler figures/energy-flow.tex seul, tandis que le document principal ne gère que légendes, numéros et références. En relecture, joignez ce PDF standalone et organisez un passage « figures seules » ; la figure peut s’améliorer sans attendre la recompilation de tout le manuscrit.

paper.tex
figures/
  energy-flow.tex
  apparatus-layout.tex
  timing-diagram.tex

Rendez aussi explicite le choix au moment de la remise. Si vous vous contentez de \input la source, aucune commande externe n’est nécessaire et la compilation LaTeX normale suffit. Si vous utilisez \includestandalone pour construire la figure séparément et l’inclure comme image, mettez -shell-escape et la règle de nettoyage des fichiers générés dans la configuration de build. En travail collaboratif, indiquez aussi si les PDF générés sont versionnés, afin que d’anciennes images de figures ne se glissent pas dans la version finale.