Build-Werkzeuge

Wenn davon die Rede ist, LaTeX sei installiert, landet auf der Festplatte kein einzelnes Programm, sondern ein Verzeichnis voller Kommandozeilenwerkzeuge. Auf diesem Rechner mit TeX Live 2024 stehen dort knapp 490 Befehle, und beim gewöhnlichen Schreiben tippt man ein oder zwei davon. Die übrigen gut vierhundertachtzig hält die Distribution für den Tag bereit, an dem ein Dokument nicht mehr mitspielt: kpsewhich fragt, wo ein Paket wirklich liegt, texdoc öffnet dessen Handbuch, tlmgr installiert Fehlendes, pdfcrop beschneidet eine Abbildung. Diese Seite ist eine Karte dieser Reserve, geordnet nach der Frage, die jedes Werkzeug beantwortet. Die darüberliegenden Build-Treiber – latexmk, llmk, arara – haben eine eigene Seite; hier geht es um die Ebene darunter.

„Bei mir übersetzt es doch“ – zuerst kpsewhich aufrufen

Dieselbe .tex-Datei übersetzt auf dem eigenen Rechner und scheitert auf dem der Mitautorin. Fast immer ist das eine Frage danach, wo Dateien liegen, und kpsewhich klärt sie in einer Zeile. Verbindlich ist der Befehl, weil er nicht eigenständig sucht: Jede Engine in TeX Live 2024 ist gegen kpathsea gelinkt, die Bibliothek für die Dateisuche (in dieser Ausgabe Version 6.4.0), und kpsewhich ist genau diese Bibliothek als eigenständiges Kommando. Der ausgegebene Pfad ist also die Datei, welche die Engine tatsächlich öffnen wird, keine Vermutung. Gibt kpsewhich amsmath.sty gar nichts aus, ist das Paket schlicht nicht vorhanden, und beim Übersetzen erscheint ! LaTeX Error: File amsmath.sty not found. Wird dagegen etwas ausgegeben, liegt das Problem nicht am Fehlen, sondern daran, dass das Falsche sichtbar ist.

kpsewhich amsmath.sty
# /usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty

kpsewhich article.cls          # classes are found the same way
kpsewhich --all texmf.cnf      # every match, in search order
kpsewhich --progname=xelatex --format=tfm cmr10.tfm

Mit --all erscheinen alle Treffer in Suchreihenfolge, nicht nur der erste. Genau hier versteckt sich der unangenehmere Fehler – der schlimmer ist als eine fehlende Datei. TeX nimmt den ersten Treffer, und so verdeckt eine vor Jahren ins Manuskriptverzeichnis kopierte alte .sty-Datei klammheimlich die aktuelle Fassung aus der Distribution. Im Log fällt nichts auf; nur das Verhalten unterscheidet sich von Rechner zu Rechner. Ein Aufruf von kpsewhich --all macht es sichtbar, weil derselbe Name zweimal auftaucht. kpsewhich beschränkt sich auch nicht auf .sty-Dateien: Klassen (article.cls), Fontmetriken und Konfigurationsdateien werden über denselben Mechanismus gefunden. Unterscheidet sich die Suche je nach Engine, lässt sich mit --progname=xelatex unter anderem Namen fragen, und mit --format=tfm nach Dateityp eingrenzen (die Liste der Typen zeigt kpsewhich --help-formats).

--var-value und --show-path – auslesen, was die Engine glaubt

kpsewhich --var-value=TEXMFHOME gibt genau eine Konfigurationsvariable aus, kpsewhich --show-path=tex die vollständige, geordnete Liste der Verzeichnisse, in denen nach .tex-Dateien gesucht wird. Das erste beantwortet das „Wo“, das zweite das „In welcher Reihenfolge“. Wer beides kennt, verlässt sich nicht mehr auf allgemeine Angaben in der Dokumentation, sondern liest die Werte, die der Rechner vor einem tatsächlich verwendet. Vier Variablen zählen am meisten, denn die TeX-Suchbäume sind nach Rolle getrennt: persönlich, systemweit, Distribution und erzeugte Dateien. Auch die Reihenfolge trägt Bedeutung – der persönliche Baum steht vor der Distribution, und genau deshalb kann eine eigene .sty-Datei eine mitgelieferte überschreiben.

kpsewhich --var-value=TEXMFHOME
# /Users/you/Library/texmf

kpsewhich --show-path=tex      # the whole ordered search list
kpsewhich --expand-var='$TEXMFDIST/tex/latex'

Wohin mit eigenen .sty-Dateien – der persönliche texmf-Baum

Selbst geschriebene .sty- oder .cls-Dateien und von Hand aus dem CTAN geladene Pakete gehören nach TEXMFHOME. Den Ort nicht raten, sondern kpsewhich --var-value=TEXMFHOME fragen: Unter macOS mit MacTeX lautet die Antwort ~/Library/texmf, bei einer TeX-Live-Installation unter Linux üblicherweise ~/texmf. Hier lauert eine Falle: Das Verzeichnis existiert anfangs meist gar nicht. kpsewhich nennt den konfigurierten, nicht den vorhandenen Ort; der erste Schritt besteht also darin, den ausgegebenen Pfad selbst anzulegen. Innen gilt die TDS (TeX Directory Structure): Ein LaTeX-Paket kommt nach TEXMFHOME/tex/latex/<name>/<name>.sty.

mkdir -p "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle"
cp mystyle.sty "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle/"
kpsewhich mystyle.sty          # found immediately, no texhash needed

texhash und mktexlsr – ein Programm mit zwei Namen

texhash und mktexlsr tun dasselbe – genauer gesagt, sie sind dieselbe Datei. Ein Blick in das bin-Verzeichnis von TeX Live 2024 zeigt: texhash ist ein Symlink auf mktexlsr. Beide bauen ls-R neu auf, die Dateinamendatenbank. Der Distributionsbaum ist riesig; allein texmf-dist/ls-R misst auf diesem Rechner über 5 MB. Jedes Mal die Platte zu durchlaufen wäre viel zu langsam, also werden die Systembäume über ls-R abgefragt – zum Preis, dass die Datenbank nach jedem Hinzufügen von Dateien neu erzeugt werden muss. Deshalb lautet die Antwort auf „etwas liegt in TEXMFLOCAL und wird trotzdem nicht gefunden“ schlicht sudo mktexlsr. Der TEXMFHOME-Baum aus dem vorigen Abschnitt wird dagegen jedes Mal von der Platte gelesen: Eine dort abgelegte .sty-Datei ist sofort auffindbar – anlegen, kpsewhich fragen, und die Antwort kommt, ohne dass texhash je gelaufen wäre. Das spricht zusätzlich für den persönlichen Baum.

texdoc – das Handbuch liegt bereits auf der Platte

Ein texdoc geometry öffnet das PDF-Handbuch des Pakets geometry im Betrachter. Ohne Netzwerk: Als das Paket vom CTAN kam, war seine Dokumentation dabei. Genau darin liegt der Wert des Befehls – das Handbuch zur tatsächlich installierten Fassung ist genauer als irgendein betagtes Tutorial aus der Suchmaschine. Mehrere Dokumente können denselben Namen tragen; im Zweifel listet texdoc -l geometry die Kandidaten auf, auf diesem Rechner das englische geometry.pdf und zusätzlich ein deutsches geometry-de.pdf. Mit -s (showall) kommen auch entfernter verwandte Treffer hinzu, mit -M wird die Ausgabe maschinenlesbar. In TeX Live 2024 steckt Texdoc 4.1 (2024-03-10); die Copyright-Zeile nennt Manuel Pégourié-Gonnard, Takuto Asakura und das TeX Live Team.

texdoc geometry            # open the manual
texdoc -l geometry         # list every candidate first
texdoc texdoc              # the manual for texdoc itself

tlmgr install, update, info – und was „TeX Live 2024 is frozen“ bedeutet

tlmgr ist die Paketverwaltung von TeX Live; drei Unterbefehle decken den Alltag ab: tlmgr info NAME fragt nach einem Paket, tlmgr install NAME installiert es, tlmgr update --self --all bringt alles auf den neuesten Stand. Am praktischsten ist die Ausgabe von info: installed: Yes zeigt, ob es vorhanden ist, revision: welche Fassung, collection: zu welchem Bündel es gehört. Ein Detail spart hier einen halben Tag: Befehlsname und TeX-Live-Paketname stimmen nicht immer überein. Auf tlmgr info llmk beginnt die Antwort mit tlmgr: cannot find package llmk – anschließend durchsucht das Programm von sich aus Beschreibungen und Dateinamen und schlägt light-latex-make vor. Der Befehl llmk steckt eben nicht in einem gleichnamigen Paket.

tlmgr info amsmath             # installed? which revision? which collection?
sudo tlmgr install siunitx     # a system-wide tree needs root
sudo tlmgr update --self --all
tlmgr --version                # also prints which installation is in use

Beim ersten Mal erschreckt außerdem die Einfrier-Meldung. Auf TeX Live 2024 geben die meisten tlmgr-Unterbefehle zunächst TeX Live 2024 is frozen und and will no longer be routinely updated. aus. Das ist ein Hinweis, kein Fehler. Beschrieben wird lediglich, wie TeX Live arbeitet: Sobald eine neue Jahresausgabe erscheint, erhält das Repository des Vorjahres keine regelmäßigen Aktualisierungen mehr. Der Befehl läuft darunter ganz normal weiter – tlmgr info amsmath gibt nach dem Banner wie gewohnt die vollständige Paketinformation aus. Die Abhilfe besteht also nicht im erneuten Versuch, sondern in der Installation der neueren Jahresausgabe. Hinzu kommt: In einer Standardinstallation wie MacTeX gehört /usr/local/texlive/2024/texmf-dist root, weshalb tlmgr install und tlmgr update sudo benötigen. Ohne Administratorrechte ist es oft schneller, die Datei wie im vorigen Abschnitt von Hand in TEXMFHOME zu legen.

pdfcrop – den weißen Rand einer Abbildungs-PDF entfernen

Ein Aufruf von pdfcrop figure.pdf erzeugt figure-crop.pdf, bei dem die Ränder Seite für Seite berechnet und entfernt wurden. Gebraucht wird das, wenn eine TikZ-Grafik als eigene Datei gesetzt wurde oder wenn ein anderes Programm eine PDF als „kleine Zeichnung mitten auf einem A4-Blatt“ exportiert hat. Wird die unverändert mit \includegraphics eingebunden, klebt man das Papier ein und nicht das Bild. Soll ein Rand bewusst bleiben, gibt --margins "5 5 5 5" alle vier Seiten an; die Einheit ist bp (big point). Die Falle liegt in der Abhängigkeit: pdfcrop schneidet nicht selbst – es steuert standardmäßig Ghostscript (gs, änderbar über --gscmd) sowie eine TeX-Engine. Fast alle Meldungen „pdfcrop ist installiert, funktioniert aber nicht“ laufen auf ein fehlendes Ghostscript hinaus. In TeX Live 2024 steckt pdfcrop 1.42 (2023/04/15, von Heiko Oberdiek).

pdfcrop figure.pdf                       # -> figure-crop.pdf
pdfcrop --margins "5 5 5 5" figure.pdf   # keep 5bp on every side
pdfcrop --luatex figure.pdf              # drive lualatex instead of pdftex

In eine fertige PDF hineinsehen – pdftotext ist kein TeX-Befehl

Wer Text aus einer fertigen PDF ziehen will, findet in fast jeder Anleitung pdftotext. Zu beachten ist allerdings: pdftotext gehört nicht zu TeX Live. Im bin-Verzeichnis von TeX Live 2024 taucht es nirgends auf; die Fassung auf diesem Mac stammt vom poppler-Paket aus Homebrew. Für pdfinfo gilt dasselbe. Der Einsatz ist völlig in Ordnung, nur ist pdftotext: command not found auf einem Rechner mit funktionierender TeX-Installation kein Defekt – es handelt sich schlicht um andere Software. Von TeX Live stammt dagegen pdftosrc, dessen Aufrufzeile pdftosrc <PDF-file> [<stream-object-number>] lautet: ein Werkzeug, um ein Stream-Objekt aus einer PDF herauszuholen. Für die tägliche Kontrolle lohnt der Blick in die .log-Datei meist mehr als das Stochern in der PDF; die benachbarten Werkzeuge – texfot zum Eindampfen des Logs, Ghostscript für PDF-Eingriffe, dvisvgm für Vektorausgabe – sind auf einer eigenen Seite versammelt.

Welcher Befehl zu welchem Symptom

Was sich lohnt, ist die Gewohnheit der richtigen Reihenfolge beim Fragen. Wirkt etwas seltsam, prüft man den Ort mit kpsewhich und die Spezifikation mit texdoc, bevor jemand anderes befragt wird: Beides braucht weder Netz noch Administratorrechte und antwortet in Sekunden. Erst wenn sich dabei zeigt, dass wirklich etwas fehlt, kommt tlmgr ins Spiel; und wer beim Ablageort unschlüssig ist, wählt TEXMFHOME. Die Schicht, die Anzahl und Reihenfolge der Engine-Läufe automatisiert – latexmk und Verwandte –, ist eine andere als diese Schicht des Findens, Lesens und Installierens. Wie sorgfältig die erste auch eingerichtet wird: Unterschiede zwischen Rechnern verschwinden erst, wenn die zweite stimmt.