standalone

standalone ist eine LaTeX-Klasse, die genau eine Sache – eine Abbildung, ein TikZ-Bild, eine Tabelle – als einzelne, auf den Inhalt zugeschnittene Seite setzt. Ihr eigentlicher Wert liegt weniger im Zuschneiden als darin, dass eine Datei zwei Gesichter hat: Kompiliert man figure.tex allein, entsteht ein PDF nur der Abbildung; bindet man sie per \input in einen Aufsatz ein, fließt dieselbe Datei ohne ein geändertes Zeichen in den Text. Auch der Zuschnitt hat Geschichte. Vor der Option crop, die heute Standard ist, nutzte standalone das Paket preview, das aus Emacs’ AUCTeX hervorging – genau der Code, der Formelvorschauen im Editor einblendet. Diese Seite behandelt Klasse und Paket selbst: wie border= wirkt, multi und subpreambles, und die Fehler, die tatsächlich auftreten. Die fertige Abbildung in ein PNG oder SVG zu verwandeln, gehört auf eine andere Seite.

Dieselbe Abbildungsdatei allein und im Aufsatz nutzen

Sobald ein Dokument wächst, möchte man die Abbildungen in eigenen Dateien haben. Doch eine solche Datei allein zu kompilieren heißt, jedes Mal das Gerüst zu schreiben – \documentclass, \begin{document} –, und die Ausgabe ist die Abbildung in der Ecke einer großen weißen Textseite. Die standalone-Klasse erledigt beides auf einmal. Steht \documentclass{standalone} am Anfang einer Abbildungsdatei, kompiliert sie für sich, und die Ausgabe wird auf die Größe des Inhalts zugeschnitten – eine Seite PDF, DVI oder PS, ohne Seitenzahl, Kopf- oder Fußzeile.

% 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 besteht aus zwei Hälften: der Klasse in der Abbildungsdatei (\documentclass{standalone}) und dem Paket im Hauptdokument (\usepackage{standalone}). Die Klasse übernimmt „ein Stück für sich setzen“, das Paket „dieses Stück in den Text holen“. Es stammt von Martin Scharrer; in TeX Live 2024 liegt v1.3b vom Oktober 2022. Die Klasse braucht xkeyval, das Paket zusätzlich currfile, gincltex, filemod und adjustbox – alle Teil von TeX Live und MiKTeX.

crop gegen preview – und wo der Standard wirklich festgelegt wird

Der Standard ist crop mit einem Rand von 0pt – doch dieser Standard steht in der Konfigurationsdatei standalone.cfg, nicht in der Klasse. standalone.cls selbst setzt preview und 0.50001bp als Vorgabe, wie es v0.x tat; kurz bevor die Optionen verarbeitet werden, wird standalone.cfg gelesen und überschreibt beides mit \standaloneconfig{crop} und \standaloneconfig{border=0pt}. Die zweistufige Anlage ist nützlich: Legt man eine eigene standalone.cfg ins Projektverzeichnis oder in einen lokalen TEXMF-Baum, ändert man den Standard für jede standalone-Datei dieser Umgebung. Die mitgelieferte cfg wird bei jedem Update überschrieben; eigene Einstellungen gehören daher in eine separate Datei.

crop und preview schließen einander aus: Gibt man beide an, gewinnt die zuletzt genannte, und beide erzwingen float=false. Der praktische Unterschied zeigt sich beim Nachmessen. Eine Abbildung, die nur ein Rechteck von 2 cm × 1 cm enthält, ergibt unter TeX Live 2024 mit dem Standard crop 57,09 × 28,75 bp. Setzt man nun eine Leerzeile vor \end{document}, ändert sich unter crop nichts, unter preview springt die Breite dagegen auf 343,71 bp. Die Leerzeile gilt als Absatzende, der Inhalt wird also zu einem Absatz voller \linewidth-Breite. Das ist der klassische „breite weiße Rand rechts neben meiner Abbildung“, und genau seinetwegen wurde crop zum Standard. preview bleibt erhalten, weil es der Notausgang ist, wenn TikZ-Schattierungen unter XeLaTeX Ärger machen.

Rand mit border= hinzufügen – und wie die Werte gelesen werden

Die Option, zu der man am häufigsten greift, ist border= (Alias margin=). Ein Wert gilt für alle vier Seiten, zwei für waagerecht und senkrecht, vier für links, unten, rechts und oben in dieser Reihenfolge. Mehrere durch Leerzeichen getrennte Werte werden als Ganzes geklammert: border={10pt 5pt}. Eine bloße Zahl ohne Einheit gilt als bp, der PostScript-Punkt. An derselben Abbildung von 57,09 × 28,75 bp gemessen, ergibt border=5pt 67,05 × 38,71 bp (5 pt, also rund 4,98 bp, je Seite) und border={10pt 5pt} 77,02 × 38,71 bp. Da border und varwidth keine globalen Einstellungen sind, lassen sie sich später mit \standaloneconfig{...} ändern – in der Präambel oder bei aktiviertem multi sogar mitten im Dokument.

Mehrere Abbildungen aus einer Datei (multi)

Standardmäßig wird alles innerhalb der document-Umgebung zu einer Seite. Mit multi wird jedes Vorkommen einer benannten Umgebung auf eine eigene Seite zugeschnitten. Genau deshalb ist \documentclass[tikz]{standalone} so bequem: Die Option tikz setzt intern multi=tikzpicture und varwidth=false, sodass zwei aufeinanderfolgende tikzpicture-Umgebungen ein zweiseitiges PDF ergeben. (pstricks tut dasselbe für PSTricks.) Für eine eigene Umgebung deklariert man \standaloneenv{myfig} und stellt nichts außerhalb; ignorerest nur ergänzen, wenn dazwischen wirklich Material stehen muss. Es gibt außerdem eine Option math, die Formeln einzeln zuschneidet und dabei multi und ignoreempty sowie einen Rand von 0.50001bp setzt.

Fehler und Symptome, die tatsächlich auftreten

Jeder standalone-Fehler hat eine klare Ursache, und vom Symptom lässt sich zurückgehen. Am häufigsten steckt eine figure-Umgebung in der standalone-Datei: Bei aktivem crop oder preview erscheint ! LaTeX Error: Not in outer par mode. oder eine Meldung „Float(s) lost“. Der Zuschnitt funktioniert, indem der Inhalt in eine Box gepackt wird, und in einer Box kann nichts gleiten. Da crop und preview beide von sich aus float=false setzen, kann dieser Fehler nur auftreten, wenn man danach von Hand float=true geschrieben hat. Floats gehören ins Hauptdokument; in die standalone-Datei kommt nur die Zeichnung.

• Breiter weißer Rand rechts neben der Abbildung. Der Inhalt wurde zu einem Absatz. Leerzeile oder ein überflüssiges \par vor \end{document} löschen, varwidth ergänzen oder die Umgebung mit multi und \standaloneenv deklarieren.
• Die rechte Seite ist abgeschnitten. Das Maximum von varwidth (standardmäßig \linewidth) ist zu schmal. Verbreitern, etwa varwidth=15cm, oder mit varwidth=false abschalten.
• Ein Optionswert wird abgelehnt. Alles außer true oder false bei einem booleschen Schlüssel bricht ab, etwa mit ! Class standalone Error: Invalid value 'maybe' for boolean key 'crop'.
• In einer mehrseitigen Datei erscheint eine überflüssige Seite. multi ist aktiv, und außerhalb der deklarierten Umgebungen wird etwas gesetzt. Entfernen oder ignorerest aktivieren.
• Auf dem DVI-Weg schneidet es falsch zu. Im DVI-Modus gibt crop PostScript-Befehle aus; das Handbuch selbst nennt diesen Code experimentell. Unter reinem latex ist preview mitunter die stabilere Wahl.

Die Paketseite: die Abbildung per \input holen

Lädt man \usepackage{standalone} so früh wie möglich in der Präambel des Hauptdokuments, definiert das Paket \documentclass so um, dass bei einer per \input eingebundenen Abbildungsdatei alles von deren \documentclass bis zum \begin{document} übersprungen wird. Die document-Umgebung der Abbildungsdatei gilt als einfache TeX-Gruppe, und auch alles nach \end{document} wird ignoriert; in den Text fließt also nur der Inhalt der Datei. Eine Voraussetzung gibt es: Das Hauptdokument muss alle Pakete laden, die die Abbildungsdateien brauchen. Da deren Präambel übersprungen wird, kann tikz und Verwandtes nur die Hauptdatei laden.

\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}

Wem das Abschreiben der Präambeln zu mühsam ist, dem sammelt \usepackage[subpreambles=true]{standalone} sie ein: Die Präambel jeder Abbildungsdatei landet in einer Hilfsdatei und wird beim nächsten Lauf ins Hauptdokument übernommen. Mit sort werden die von den Abbildungen geladenen Pakete samt Optionen ohne Dubletten zusammengeführt und über \PassOptionsToPackage geladen, was Optionskonflikte vermeidet. Wer sie lieber selbst überträgt, lässt sie mit print ausgeben – doch das ist ein reiner Sammelmodus, und wie die Meldung Package standalone Warning: Running 'standalone' package in sub-preamble print mode. All body content of file 'figure.tex' is ignored! unmissverständlich sagt: Der Textkörper wird nicht gesetzt.

\includestandalone und mode= – Quelltext oder Bild

Schreibt man statt \input ein \includestandalone{figure}, entscheidet die Paketoption mode=, wie die Abbildung ankommt. Die Werte sind tex (den Quelltext einbinden – Standard), image (ein vorhandenes PDF oder EPS per \includegraphics einbinden), image|tex (Bild, falls vorhanden, sonst Quelltext), build (jedes Mal bauen), buildmissing (nur bauen, wenn das Bild fehlt) und buildnew (nur bauen, wenn der Quelltext neuer ist; unter XeLaTeX nicht verfügbar). Es geht um Tempo: Eine aufwendige Abbildung muss nicht bei jedem Lauf des Hauptdokuments neu gesetzt werden. Nur die drei Build-Modi rufen einen externen Befehl auf, und dafür braucht es -shell-escape. Das Handbuch hält ausdrücklich fest: Scheitert der Build, erscheint eine Warnung und der Quelltext wird stattdessen eingebunden.

Alles Weitere – aus dem zugeschnittenen PDF ein PNG oder SVG machen, ein bestehendes PDF mit pdfcrop beschneiden, dvisvgm steuern, die Einstellungen für convert= – gehört auf die Seite über den Export von Abbildungen als Bilder. Von der Klassenseite bleibt nur eines zu merken: Den Rand gar nicht erst zu erzeugen, ist schneller und genauer, als ihn hinterher abzuschneiden.

standalone in ein Projekt einordnen

In einer echten Arbeit zahlt es sich aus, jede standalone-Datei als Quelle einer Abbildung zu behandeln, in einer Form, die sich getrennt vom Text prüfen lässt. Die Hauptdatei heißt paper.tex, die Abbildungen liegen unter figures/, und im Text steht nur \input{figures/energy-flow}. Wer eine Abbildung überarbeitet, kompiliert dann figures/energy-flow.tex allein, während das Hauptdokument nur Beschriftungen, Nummerierung und Verweise verwaltet. Im Review hängt man dieses einseitige PDF an und macht einen reinen Abbildungsdurchgang: Die Zeichnung wird besser, ohne dass das ganze Manuskript neu gebaut werden muss.

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

Sollen die Inhalte einer Abbildung denselben Satzregeln folgen wie der Haupttext, gleicht man die zugrunde liegende Klasse mit class= an. Bei einer Abbildung mit japanischen Beschriftungen bringt \documentclass[class=jsarticle,border=5pt]{standalone} unter upLaTeX – oder class=ltjsarticle unter LuaLaTeX – Zeichenabstände und Schriften mit dem Haupttext in Einklang. Klasse und Paket stellen gemeinsam auch \ifstandalone, \IfStandalone{allein}{eingebunden} und \onlyifstandalone{...} bereit: So zeigt man einen Maßstab oder einen Debug-Rahmen mit einer einzigen Zeile nur in der Abbildungsdatei.

Wie sich subfiles und TikZ external unterscheiden

Zwei Mechanismen verfolgen ähnliche Ziele – beide laufen in die umgekehrte Richtung. Bei subfiles importiert eine Unterdatei die Präambel des Hauptdokuments; standalone macht es andersherum und sammelt die Präambeln der Unterdateien im Hauptdokument. Deshalb eignet sich standalone für die Wiederverwendung einer Abbildung in mehreren Dokumenten – Aufsatz, Vortrag, Abschlussarbeit –, während subfiles zu einer kapitelweisen Aufteilung mit Eins-zu-eins-Beziehung passt. TikZs Bibliothek external schreibt temporäre Bilder aus der Hauptdatei heraus, also wiederum in die Gegenrichtung. Allerdings liefert \includestandalone[mode=buildnew] im Wesentlichen denselben Zwischenspeicher-Effekt für teure Zeichnungen und hält die Abbildung dabei als eigenständige Datei.