CTAN & docs

Install LaTeX and you install a library. Counting the documentation under texmf-dist/doc in TeX Live 2024 — all of it from CTAN, the Comprehensive TeX Archive Network — gives 10,099 PDFs inside a tree of 3.7 GB, and most are never opened once. The key to the copies already on your disk is a one-word command, texdoc. This page covers how that archive works and, more usefully, how to read the LaTeX documentation you already have: texdoc, kpsewhich, tlmgr info, and rebuilding a manual from its .dtx source.

texdoc <package>: opening the manual you already have

Type texdoc booktabs and the manual for the booktabs you actually have installed opens. Not a web search — a file on your disk. That matters because what opens is the documentation for your installed version: a blog post you found may describe a way of working two releases out of date, but the PDF texdoc hands you describes your machine. The default is view mode, which opens the single result the tool judges best. Options change that: -l lists the candidates and lets you pick one by number, -m opens straight away when there is only one good hit and otherwise offers the menu, and -s shows even the low-scoring results that are normally hidden.

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)

What makes texdoc clever is that it does not match on filenames alone. Alongside walking the documentation trees (the TEXDOCS path) it queries the TeX Live database, texlive.tlpdb, and so it can follow the package that contains <name>.sty or <name>.cls. That is why texdoc shortvrb correctly opens doc.pdf from inside the latex package that ships shortvrb.sty — the default configuration file carries the line alias shortvrb = base/doc. Candidates then get numeric scores: a file called <name>.pdf scores high, a Makefile is pushed down by -1000. And if nothing matches at all, a fuzzy pass looks for the closest package name, which is why texdoc bootabs still lands on the booktabs manual. When even that fails the message is Unfortunately, there are no good matches for "...", followed by a pointer to the same document on texdoc.org.

One more mechanism matters if you read in more than one language. texdoc guesses your language from the system locale and gives a bonus to <name>-<lang>.pdf. Run texdoc -l booktabs and alongside the English booktabs.pdf you get directories called booktabs-de and booktabs-fr — translated manuals that ship inside TeX Live. For the same reason texdoc -l lshort returns more than sixty results, with the language editions near the top, tagged [fr], [zh], [ko] and so on. If the automatic detection guesses wrong, a single line lang = ja in the personal configuration file — texdoc --files prints its location, ~/Library/texmf/texdoc/texdoc.cnf on macOS — pins it. Put mode = list in the same file and every future call behaves as though you had typed -l.

Where is that .sty file? kpsewhich and tlmgr info

A kpsewhich booktabs.sty returns, in one line, the absolute path of the file LaTeX will actually read. When a document misbehaves in a way that contradicts its manual, the first suspicion should not be the version but the possibility that the file being read is not the file you think it is — and this command settles that instantly. Add --all and you get every candidate, in search order. Try kpsewhich --all article.cls and two lines come back: texmf-dist/tex/latex/base/article.cls and texmf-dist/tex/latex-dev/base/article.cls. Shadowing — one copy hiding another that sits later in the path — becomes visible. If you once wrote your own .sty and dropped it in your home tree, suspect the directory kpsewhich -var-value=TEXMFHOME reports (~/Library/texmf on macOS). When nothing is found, kpsewhich prints nothing and exits with status 1, so it works inside a shell conditional too.

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 answers a different question: not where, but what the catalogue says. You get the one-line description, the long description, the collection it belongs to, the licence (lppl1.3c), the size of the src, doc and run parts, and the version. Fields such as cat-contact-bugs and cat-contact-repository may appear too, and those are the package’s issue-tracker addresses. Run tlmgr info --list booktabs and the files themselves appear in three groups — and those three groups are the TeX Live directory layout: tex/latex/booktabs/booktabs.sty (the code loaded at run time), doc/latex/booktabs/booktabs.pdf (the manual texdoc opens), and source/latex/booktabs/booktabs.dtx with its .ins (the origin of both).

The .dtx and .ins pair: source that is its own manual

A .dtx file is code and commentary living in one file, and the same file can be processed two ways. Run tex <package>.ins and docstrip throws the prose away and writes out the .sty; run pdflatex <package>.dtx and the code is typeset instead, annotated line by line, as the manual PDF. Tried locally on multirow, tex multirow.ins generated three files — multirow.sty, bigstrut.sty and bigdelim.sty — and pdflatex multirow.dtx produced a 30-page annotated source. The payoff is that you can chase behaviour the texdoc manual never mentions: the implementation is right there, so “why does this option do that?” can be read to the end.

# 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

The extreme case of this arrangement is LaTeX itself. texdoc source2e opens The LaTeX 2ε Sources — 1,308 pages of annotated kernel, carrying the names of Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach and others. And once reading documentation becomes a habit you start noticing things. The version tlmgr info booktabs reports is 1.61803398: the digits of the golden ratio φ = 1.618033988…, one more added per release, and booktabs.dtx says so in its own words — “(converging to phi, the golden ratio)”. A version number that is really a sequence is a joke, but it is a joke you can only confirm by opening the .dtx.

What CTAN is: one address, built in 1992

CTAN (the Comprehensive TeX Archive Network, ctan.org) exists to make there be one place to put TeX material. It was built in 1992 by Rainer Schöpf and Joachim Schrod in Germany, Sebastian Rahtz in the UK, and George Greenwade in the US — Greenwade is the one who supplied the name — and formally announced at the EuroTeX conference in Aston, UK, in 1993; the idea itself goes back to a discussion in 1991. Before that, macros and fonts were scattered across assorted FTP sites, and different people kept re-collecting the same material independently. The problem CTAN solved, then, was not that there was nowhere to put things: it was that there were too many places.

The way into CTAN today is a package page, ctan.org/pkg/<name>. It carries Sources, Documentation (the PDF), Version, Licenses, Copyright, Maintainer, Contained in (whether TeX Live and MiKTeX ship it) and Topics. The last two are the ones that pay off in practice. Contained in tells you at a glance whether tlmgr install will fetch the package or whether you must install it by hand. Topics is the entry point for “I do not know its name but I know what it should do” — hunting for table code, you can arrive through the table topic. The licence field is almost always LPPL, the LaTeX Project Public License, the TeX world’s standard terms for redistribution and modification.

The word “Network” is not decoration. CTAN is a core site plus official mirrors worldwide that synchronise automatically (running one currently wants around 50 GB of disk). That is why writing mirror.ctan.org into a download URL routes you to a nearby mirror — TeX Live’s own guide states that the default package repository is a CTAN mirror chosen automatically via https://mirror.ctan.org. To pin one particular mirror instead, the list lives at ctan.org/mirrors. Traffic also runs the other way: authors upload new or updated packages into the core site’s incoming area, the CTAN team processes them, and the mirrors pick them up. Tools for that shipment are in TeX Live too — ctanify builds a tarball in CTAN’s preferred layout, and ctan-o-mat validates a submission before it is sent. And TeX Live itself is a snapshot of CTAN: those 3.7 GB of documentation on your disk are a copy of this archive.

Local documentation or online: which one to believe

What decides whether your document compiles is the documentation on your own disk. So when the question is “why does this not work?”, open texdoc first. When the question is “has this feature been added?”, look at the CTAN package page or texdoc.org instead — those are always current. The two genuinely diverge. Each TeX Live release is eventually frozen and later updates ride the next release, so the version and the topic classification that tlmgr info reports can easily be older than what CTAN shows. When you spot a discrepancy, the safe order is: confirm your own version with tlmgr info <package>, then read it against the CTAN entry. A large share of the time that code found on the web fails to run, the article is not out of date — your environment and the author’s simply differ.