standalone

standalone ist eine Klasse, mit der ein einzelner Baustein — eine Abbildung, ein TikZ-Bild, eine Tabelle — als in sich abgeschlossenes Dokument gesetzt wird. Die Ausgabe wird eng auf den Inhalt zugeschnitten: ein PDF nur der Abbildung, ohne umgebende Seite, Seitenzahl oder Rand. Zusammen mit dem gleichnamigen Paket kann diese Datei unverändert per \input in das Hauptdokument übernommen werden. Geschrieben von Martin Scharrer, macht es eine Abbildung sowohl einzeln als auch als Teil eines größeren Dokuments nutzbar.

Wofür standalone gedacht ist

Beim Schreiben eines großen Dokuments möchte man Abbildungen und TikZ-Bilder oft in eigene Dateien auslagern und in den Text einziehen. Soll so eine Abbildungsdatei aber allein kompiliert und geprüft werden, muss man immer wieder ein Gerüst wie \documentclass und \begin{document} hinzufügen, und die Ausgabe ist nur die Abbildung in der Ecke einer großen weißen Textseite. Die standalone-Klasse löst beides. Steht \documentclass{standalone} am Anfang der Abbildungsdatei, lässt sich dieses eine Stück allein kompilieren; die Ausgabe wird eng auf die Größe des Inhalts zugeschnitten — als PDF (oder DVI/PS) ohne Seitenzahl, Kopf- oder Fußzeile.

standalone hat zwei Seiten. Die eine ist die Klasse in der Abbildungsdatei (\documentclass{standalone}), die andere das Paket, das im Hauptdokument geladen wird (\usepackage{standalone}). Die Klasse setzt „ein Stück für sich“, das Paket „nimmt dieses Stück in das Hauptdokument auf“ — beides gehört zusammen. Beginnen wir mit der Klasse.

Sowohl die standalone-Klasse als auch das Paket benötigen xkeyval. Das Paket braucht zusätzlich currfile (das intern filehook nutzt), um die Namen eingebundener Dateien zu verfolgen, sowie gincltex und filemod für die Bildausgabe-Funktion. All das ist in TeX Live und MiKTeX enthalten.

Verwendung als Klasse

Die Verwendung entspricht einem normalen LaTeX-Dokument. Wähle die Klasse mit \documentclass{standalone}, lade in der Präambel die Pakete, die die Abbildung braucht (für TikZ etwa tikz), und schreibe den Inhalt direkt zwischen \begin{document} und \end{document}. Standardmäßig aktiviert die Klasse die Option crop (siehe unten), die die Ausgabe auf die Inhaltsgröße zuschneidet.

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

Allein kompiliert ergibt das ein einseitiges PDF, das auf das Rechteck zugeschnitten ist. Beim Schreiben sind zwei Dinge wichtig: keine Leerzeilen vor oder nach dem Inhalt, und \begin{document} sowie \end{document} jeweils auf eine eigene Zeile setzen. Die standalone-Klasse behandelt den ganzen Inhalt als einen Block; eine abschließende Leerzeile wird daher als Absatz von Breite \linewidth gelesen und kann rechts der Abbildung unerwünschten Raum erzeugen.

Für ein TikZ-Bild ist die Option tikz bequem, etwa \documentclass[tikz]{standalone}. Sie lädt das Paket tikz und richtet sogar die Umgebung tikzpicture so ein, dass jede davon auf eine eigene Seite zugeschnitten wird (intern setzt sie multi=tikzpicture und varwidth=false). Für PSTricks-Bilder gibt es entsprechend die Option pstricks.

Wichtige Klassenoptionen

Optionen stehen kommasepariert in eckigen Klammern. Die meisten standalone-Optionen sind boolesch: Lässt man den Wert weg, gilt true; sofern nicht anders angegeben, ist der Anfangswert false. Diese Optionen werden nicht an die darunterliegende Klasse (article als Vorgabe) weitergereicht, sondern von standalone selbst ausgewertet, um Namenskonflikte zu vermeiden. Die wichtigsten sind:

Am häufigsten greift man zu border. Mit \documentclass[border=5pt]{standalone} erhält die zugeschnittene Abbildung auf allen vier Seiten 5pt Rand. Mehrere durch Leerzeichen getrennte Werte werden als Ganzes geklammert: border={10pt 5pt}. Da border und varwidth keine globale Wirkung haben, kannst du sie später mit \standaloneconfig{...} ändern — in der Präambel oder bei aktiviertem multi sogar mitten im Dokument.

Eine historische Anmerkung: Vor v1.0 war die Option preview die Vorgabe, und der Standardrand betrug etwa 0.5bp. Seit v1.0 ist crop die Vorgabe, und der Rand ist 0pt. Um das alte Verhalten wiederherzustellen, setze \standaloneconfig{preview,border=0.50001bp} in die Konfigurationsdatei oder gib diese Optionen ausdrücklich an.

Einbinden als Paket

Das Paket ist die andere Seite von standalone. Lädt man \usepackage{standalone} so früh wie möglich in der Präambel des Hauptdokuments, definiert das Paket \documentclass so um, dass beim \input einer Abbildungsdatei alles von deren \documentclass bis zu \begin{document} übersprungen wird. Die document-Umgebung der Abbildungsdatei wird als einfache TeX-Gruppe behandelt, während die echte document-Umgebung des Hauptdokuments unverändert bleibt (auch alles nach \end{document} wird ignoriert). Praktisch wird die Präambel der Abbildungsdatei beim Einbinden entfernt, und ein schlichtes \input{figure} lässt nur den Inhalt in den Text fließen.

Voraussetzung ist, dass das Hauptdokument selbst alle Pakete lädt, die die Abbildungsdateien benötigen. Da die Präambel der Abbildungsdatei beim Einbinden übersprungen wird, müssen Pakete wie tikz vom Hauptdokument geladen werden. Hier ist das offizielle Beispiel: Das Hauptdokument lädt das standalone-Paket und bindet eine Abbildung mit \input innerhalb einer figure-Umgebung ein.

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

Der Punkt ist, dass dasselbe figure.tex ohne Änderung eines einzigen Zeichens funktioniert, ob allein oder über das Hauptdokument. Allein kompiliert wird es ein zugeschnittenes Einseiten-PDF; per \input aus dem Hauptdokument gelangt nur die Abbildung in den Text. Empfohlen ist, Floats im Hauptdokument zu verwalten: Die figure-Umgebung bleibt dort, und in die standalone-Datei kommt nur der eigentliche Inhalt (in der standalone-Klasse ist float standardmäßig false, damit crop/preview funktionieren).

Soll das Hauptdokument die Präambeln der Abbildungsdateien automatisch sammeln, lade \usepackage[subpreambles=true]{standalone}. Dann werden die Präambeln der einzelnen Dateien in einer Hilfsdatei gesammelt und beim nächsten Lauf in das Hauptdokument übernommen. Mit der Option sort werden die von den Abbildungen geladenen Pakete samt Optionen ohne Dubletten zusammengeführt und über \PassOptionsToPackage geladen, wodurch Optionskonflikte vermieden werden. Wer sie lieber von Hand in die Hauptpräambel kopiert, kann mit print die Liste ausgeben lassen.

Bilderzeugung und ähnliche Ansätze

standalone kann eine Abbildung auch in ein Bild ausgeben statt ihren Quelltext einzubinden. Im Hauptdokument schreibt man \includestandalone{figure} statt \input{figure}; bei Bedarf wird die Abbildungsdatei separat kompiliert, um ein Bild (etwa ein PDF) zu erzeugen, das anschließend mit \includegraphics eingebunden wird. Der Vorteil: Komplexe Abbildungen müssen nicht jedes Mal neu kompiliert werden, und der Hauptlauf wird schneller. Weil dafür ein externer Befehl aufgerufen wird, ist beim Kompilieren die Option -shell-escape erforderlich.

Darüber hinaus aktivieren Optionen wie convert, png, jpg und svg eine Konvertierungsfunktion, die eine standalone-Datei als Bild ausgibt (ein externes Konvertierungswerkzeug ist nötig). Das ist praktisch, wenn eine Abbildung einzeln als PNG oder SVG verteilt werden soll.

Zwei ähnliche Ansätze verfolgen verwandte Ziele: subfiles und TikZs Bibliothek external. subfiles arbeitet in der Gegenrichtung: Eine Unterdatei importiert die Präambel des *Haupt*dokuments, während standalone erlaubt, die Präambel einer Unterdatei *in* das Hauptdokument zu übernehmen. Daher eignet sich standalone für die Wiederverwendung einer Abbildung in mehreren Dokumenten (Artikel, Präsentation, Abschlussarbeit), während subfiles eher zu einer Eins-zu-eins-Beziehung zwischen Haupt- und Unterdatei passt. TikZs external schreibt temporäre Bilder aus der Hauptdatei heraus und arbeitet damit ebenfalls entgegen der standalone-Richtung.

Prüfen, bevor die Abbildung in den Text geht

Der Wert einer standalone-Datei liegt darin, dass sie allein kompiliert. Baue daher die Abbildung zuerst für sich und prüfe das PDF, bevor sie ins Hauptdokument kommt. In Abschlussarbeiten oder Artikeln ändert man oft nur eine Abbildung; benenne sie deshalb nach ihrer Bedeutung, etwa figures/experiment-flow.tex, und lasse im Haupttext nur \input{figures/experiment-flow} stehen. Das macht Austausch, Wiederverwendung und Review einfacher.

• Rand prüfen. Wird eine Kante abgeschnitten, füge border=2pt oder border=5pt hinzu; ist der Rand zu breit, verdächtige eine abschließende Leerzeile oder ein unnötiges \par.
• Präambeln abgleichen. Pakete und Einstellungen der Abbildung, etwa tikz, Farben oder Schriften, müssen auch im Hauptdokument geladen werden. Die Präambel der Unterdatei wird beim Einbinden normalerweise übersprungen.
• Floats in der Hauptdatei halten. figure-Umgebung, Beschriftung und Label gehören ins Hauptdokument; in die standalone-Datei kommt nur die Zeichnung selbst.
• Vor der Abgabe neu bauen. Wenn du \includestandalone oder Bildkonvertierung nutzt, mache vor der Abgabe einen sauberen Build, damit keine alten gecachten PDFs oder PNGs hineingeraten.

Einordnung in ein Projekt

In einem echten Artikel oder technischen Dokument ist es robust, eine standalone-Datei als Quelle der Abbildung zu behandeln und sie so zu halten, dass sie getrennt vom Haupttext geprüft werden kann. Die Hauptdatei kann etwa paper.tex heißen, Abbildungen liegen unter figures/, und im Text steht nur \input{figures/energy-flow}. Wer die Abbildung überarbeitet, kann dann figures/energy-flow.tex allein kompilieren, während das Hauptdokument nur Beschriftung, Nummerierung und Verweise verwaltet. Im Review kann dieses standalone-PDF angehängt und ein „nur Abbildungen“-Durchgang gemacht werden; die Abbildung verbessert sich, ohne auf den Neubau des ganzen Manuskripts zu warten.

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

Lege auch die Entscheidung für die Abgabe ausdrücklich fest. Wenn du nur den Quelltext per \input einbindest, ist kein externer Befehl nötig, und der normale LaTeX-Build reicht. Wenn du mit \includestandalone die Abbildung getrennt baust und als Bild einbindest, gehören -shell-escape und eine Aufräumregel für erzeugte Dateien in die Build-Einstellungen. Bei gemeinsamer Arbeit sollte auch feststehen, ob erzeugte PDFs ins Repository kommen, damit keine veralteten Abbildungen in die Endfassung rutschen.