CTAN und Dokumentation

Wer LaTeX installiert, installiert eine Bibliothek. Zählt man die Dokumentation unter texmf-dist/doc in TeX Live 2024 – sie stammt vollständig von CTAN, dem Comprehensive TeX Archive Network –, kommt man auf 10.099 PDFs in einem Baum von 3,7 GB, und die meisten davon werden nie geöffnet. Der Schlüssel zu den Kopien auf der eigenen Platte ist ein Befehl aus einem einzigen Wort: texdoc. Diese Seite beschreibt, wie dieses Archiv funktioniert, und vor allem, wie sich die bereits vorhandene Dokumentation lesen lässt: texdoc, kpsewhich, tlmgr info und das Neubauen eines Handbuchs aus seiner .dtx-Quelle.

texdoc <Paket>: das vorhandene Handbuch in einer Sekunde öffnen

Ein texdoc booktabs öffnet das Handbuch genau des booktabs, das installiert ist – keine Websuche, sondern eine Datei auf der Platte. Das ist deshalb wichtig, weil die Dokumentation zur installierten Version erscheint: Ein im Netz gefundener Artikel beschreibt womöglich eine Arbeitsweise von vor zwei Releases, das PDF von texdoc beschreibt dagegen die eigene Installation. Voreingestellt ist der view-Modus, der genau das eine Ergebnis öffnet, das das Werkzeug für das beste hält. Optionen ändern das: -l listet die Kandidaten auf und lässt per Nummer auswählen, -m öffnet sofort, wenn es nur einen guten Treffer gibt, und zeigt sonst das Menü, und -s blendet auch die sonst versteckten Treffer mit niedriger Bewertung ein.

texdoc booktabs        # open the manual for the version you have installed
texdoc -l siunitx      # list every candidate, then pick one by number
texdoc -I -l booktabs  # plain list, no interactive prompt
texdoc -M -l lshort    # machine-readable: name, score, path, language
texdoc bootabs         # a typo still finds booktabs (fuzzy search)

Klug ist texdoc deshalb, weil es nicht nur Dateinamen vergleicht. Neben dem Durchlaufen der Dokumentationsbäume (dem TEXDOCS-Pfad) fragt es die TeX-Live-Datenbank texlive.tlpdb ab und folgt damit auch dem Paket, das <Name>.sty oder <Name>.cls enthält. Darum öffnet texdoc shortvrb korrekt die doc.pdf aus dem Paket latex, in dem shortvrb.sty steckt – in der mitgelieferten Konfigurationsdatei steht dazu die Zeile alias shortvrb = base/doc. Die Kandidaten erhalten anschließend Zahlenwerte: eine Datei <Name>.pdf bekommt viel, ein Makefile wird um -1000 heruntergestuft. Findet sich gar nichts, sucht ein unscharfer Durchgang den nächstliegenden Paketnamen, weshalb texdoc bootabs trotzdem beim booktabs-Handbuch landet. Scheitert auch das, lautet die Meldung Unfortunately, there are no good matches for "...", gefolgt von einem Hinweis auf dasselbe Dokument auf texdoc.org.

Ein weiterer Mechanismus ist für mehrsprachige Leserinnen und Leser wichtig: texdoc erschließt die Sprache aus der Systemlokale und wertet <Name>-<Sprachcode>.pdf auf. Ein texdoc -l booktabs liefert neben der englischen booktabs.pdf die Verzeichnisse booktabs-de und booktabs-fr – übersetzte Handbücher, die TeX Live selbst mitbringt. Aus demselben Grund gibt texdoc -l lshort über sechzig Treffer zurück, mit den Sprachausgaben weit oben und Markierungen wie [fr], [zh] oder [ko]. Liegt die automatische Erkennung daneben, genügt eine Zeile lang = de in der persönlichen Konfigurationsdatei; wo diese liegt, verrät texdoc --files (unter macOS ~/Library/texmf/texdoc/texdoc.cnf). Ein mode = list in derselben Datei bewirkt, dass künftig jeder Aufruf so arbeitet, als wäre -l angegeben worden.

Wo liegt diese .sty-Datei? kpsewhich und tlmgr info

Ein kpsewhich booktabs.sty liefert in einer Zeile den absoluten Pfad der Datei, die LaTeX tatsächlich liest. Verhält sich ein Dokument anders, als sein Handbuch beschreibt, ist der erste Verdacht nicht die Version, sondern dass die gelesene Datei eine andere ist als angenommen – und genau das klärt dieser Befehl sofort. Mit --all erscheinen alle Kandidaten in Suchreihenfolge. Ein kpsewhich --all article.cls liefert zwei Zeilen: texmf-dist/tex/latex/base/article.cls und texmf-dist/tex/latex-dev/base/article.cls. Damit wird sichtbar, dass eine Kopie eine spätere verdeckt. Wer einmal eine eigene .sty in den Heimatbaum gelegt hat, sollte das Verzeichnis prüfen, das kpsewhich -var-value=TEXMFHOME nennt (unter macOS ~/Library/texmf). Wird nichts gefunden, gibt kpsewhich nichts aus und endet mit Status 1 – damit lässt es sich auch in einer Shell-Bedingung verwenden.

kpsewhich booktabs.sty          # which file will TeX actually read?
kpsewhich --all article.cls     # every copy, in search order
kpsewhich -var-value=TEXMFHOME  # your personal tree

tlmgr info booktabs             # version, licence, collection, sizes
tlmgr info --list booktabs      # run / source / doc files, one by one

tlmgr info booktabs beantwortet eine andere Frage: nicht wo, sondern was der Katalog sagt. Man erhält die einzeilige Beschreibung, den langen Text, die zugehörige Sammlung, die Lizenz (lppl1.3c), die Größe der Teile src, doc und run sowie die Version. Auch Felder wie cat-contact-bugs und cat-contact-repository können erscheinen; sie nennen die Adresse des Fehlerverfolgungssystems dieses Pakets. Ein tlmgr info --list booktabs zeigt die Dateien selbst in drei Gruppen – und diese drei Gruppen sind das Verzeichnisschema von TeX Live: tex/latex/booktabs/booktabs.sty (der zur Laufzeit geladene Code), doc/latex/booktabs/booktabs.pdf (das Handbuch, das texdoc öffnet) und source/latex/booktabs/booktabs.dtx samt .ins (der Ursprung von beidem).

.dtx und .ins: Quelltext, der sein eigenes Handbuch ist

Eine .dtx-Datei ist Code und Kommentar in einer einzigen Datei, und dieselbe Datei lässt sich auf zwei Weisen verarbeiten. Ein tex <Paket>.ins lässt docstrip die Prosa verwerfen und die .sty schreiben; ein pdflatex <Paket>.dtx setzt stattdessen den Code, Zeile für Zeile kommentiert, als Handbuch-PDF. Lokal an multirow ausprobiert: tex multirow.ins erzeugte drei Dateien – multirow.sty, bigstrut.sty und bigdelim.sty –, und pdflatex multirow.dtx lieferte einen 30-seitigen annotierten Quelltext. Der Gewinn liegt darin, Verhalten nachvollziehen zu können, das im texdoc-Handbuch nicht vorkommt: Die Implementierung liegt offen, und die Frage „warum tut diese Option das?“ lässt sich bis zum Ende lesen.

# copy the two source files out of the tree first, then:
tex multirow.ins        # docstrip: writes multirow.sty, bigstrut.sty, bigdelim.sty
pdflatex multirow.dtx   # the same .dtx typeset as an annotated source PDF
pdflatex multirow.dtx   # run twice so the cross-references settle

Der Extremfall dieser Bauweise ist LaTeX selbst. Ein texdoc source2e öffnet The LaTeX 2ε Sources – 1.308 Seiten kommentierter Kern, mit den Namen Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach und weiteren. Und wer sich das Lesen von Dokumentation angewöhnt, entdeckt Nebensächlichkeiten. Die Version, die tlmgr info booktabs meldet, lautet 1.61803398: die Ziffern des Goldenen Schnitts φ = 1,618033988…, mit jeder Veröffentlichung um eine erweitert – booktabs.dtx schreibt es selbst hin: „(converging to phi, the golden ratio)“. Eine Versionsnummer, die in Wahrheit eine Folge ist, ist ein Scherz; bestätigen lässt er sich nur beim Öffnen der .dtx.

Was CTAN ist: eine Adresse, gebaut 1992

CTAN (das Comprehensive TeX Archive Network, ctan.org) gibt es, damit es einen Ort für TeX-Material gibt. Aufgebaut wurde es 1992 von Rainer Schöpf und Joachim Schrod in Deutschland, Sebastian Rahtz in Großbritannien und George Greenwade in den USA – von Greenwade stammt der Name – und 1993 auf der EuroTeX-Konferenz im britischen Aston offiziell vorgestellt; die Idee selbst geht auf eine Diskussion von 1991 zurück. Zuvor lagen Makros und Schriften über zahllose FTP-Server verstreut, und verschiedene Leute trugen dieselben Dinge immer wieder unabhängig voneinander zusammen. Das Problem, das CTAN löste, war also nicht ein fehlender Ablageort, sondern zu viele davon.

Der Einstieg in CTAN ist heute eine Paketseite, ctan.org/pkg/<Name>. Sie führt Sources, Documentation (das PDF), Version, Licenses, Copyright, Maintainer, Contained in (ob TeX Live und MiKTeX es mitliefern) und Topics auf. Praktisch zahlen sich die letzten beiden aus. Contained in verrät sofort, ob tlmgr install das Paket holt oder ob von Hand installiert werden muss. Topics ist der Einstieg für „Name unbekannt, Funktion bekannt“: Wer Tabellencode sucht, kommt über das Thema table weiter. Im Lizenzfeld steht fast immer LPPL, die LaTeX Project Public License – die Standardbedingungen der TeX-Welt für Weitergabe und Änderung.

Das Wort „Network“ ist keine Zierde. CTAN besteht aus einer Kernsite und offiziellen Spiegelservern in aller Welt, die sich automatisch abgleichen (wer einen betreibt, braucht derzeit rund 50 GB Plattenplatz). Deshalb leitet mirror.ctan.org in einer Download-Adresse automatisch zu einem nahen Spiegel – die offizielle TeX-Live-Anleitung hält fest, dass das voreingestellte Paketdepot ein über https://mirror.ctan.org automatisch gewählter CTAN-Spiegel ist. Wer stattdessen einen bestimmten Spiegel festlegen will, findet die Liste unter ctan.org/mirrors. Der Verkehr läuft auch in die Gegenrichtung: Autoren laden neue oder aktualisierte Pakete in den Eingangsbereich der Kernsite, das CTAN-Team verarbeitet sie, und die Spiegel übernehmen sie. Auch das Werkzeug dafür liegt in TeX Live – ctanify baut ein Archiv in der von CTAN bevorzugten Struktur, ctan-o-mat prüft eine Einreichung vor dem Absenden. Und TeX Live selbst ist eine Momentaufnahme von CTAN: Die 3,7 GB Dokumentation auf der eigenen Platte sind eine Kopie dieses Archivs.

Lokale oder Online-Dokumentation – welcher trauen?

Ob ein Dokument übersetzt, entscheidet die Dokumentation auf der eigenen Platte. Lautet die Frage also „warum funktioniert das nicht?“, gehört texdoc an den Anfang. Lautet sie „ist diese Funktion hinzugekommen?“, sind die CTAN-Paketseite oder texdoc.org der richtige Ort – die sind immer aktuell. Beide gehen tatsächlich auseinander. Jede TeX-Live-Ausgabe wird irgendwann eingefroren, spätere Aktualisierungen fahren mit der nächsten Ausgabe mit; dass die von tlmgr info gemeldete Version oder Themenzuordnung älter ist als die auf CTAN, kommt daher regelmäßig vor. Bei einer Abweichung ist die sichere Reihenfolge: zuerst mit tlmgr info <Paket> die eigene Version feststellen, dann gegen den CTAN-Eintrag lesen. Wenn im Netz gefundener Code nicht läuft, ist erstaunlich oft nicht der Artikel veraltet – die eigene Umgebung ist einfach eine andere.