CTAN y documentación

Instalar LaTeX es instalar una biblioteca. Al contar la documentación que hay bajo texmf-dist/doc en TeX Live 2024 —toda ella procedente de CTAN, el Comprehensive TeX Archive Network— salen 10.099 PDF dentro de un árbol de 3,7 GB, y la mayoría no se abrirá jamás. La llave de las copias que ya están en el disco cabe en un comando de una palabra: texdoc. Esta página explica cómo funciona ese archivo y, sobre todo, cómo leer la documentación que ya se tiene: texdoc, kpsewhich, tlmgr info y la reconstrucción de un manual a partir de su fuente .dtx.

texdoc <paquete>: abrir el manual que ya se tiene

Al teclear texdoc booktabs se abre el manual del booktabs que está realmente instalado. No es una búsqueda en línea: es un archivo del disco. Eso importa porque lo que se abre es la documentación de la versión instalada: una entrada de blog encontrada por ahí puede describir una forma de trabajar de hace dos versiones, mientras que el PDF que entrega texdoc describe la máquina propia. El modo por defecto es el modo view, que abre el único resultado que la herramienta considera mejor. Las opciones cambian eso: -l enumera los candidatos y permite elegir uno por su número, -m abre directamente cuando solo hay un buen resultado y en otro caso ofrece el menú, y -s muestra incluso los resultados de baja puntuación, normalmente ocultos.

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)

Lo ingenioso de texdoc es que no se limita a comparar nombres de archivo. Además de recorrer los árboles de documentación (la ruta TEXDOCS), consulta la base de datos de TeX Live, texlive.tlpdb, y así puede seguir el paquete que contiene <nombre>.sty o <nombre>.cls. Por eso texdoc shortvrb abre correctamente el doc.pdf del paquete latex, que es el que trae shortvrb.sty: el archivo de configuración distribuido incluye la línea alias shortvrb = base/doc. Después los candidatos reciben una puntuación numérica: un archivo llamado <nombre>.pdf puntúa alto y un Makefile baja -1000. Y si no coincide nada, una pasada difusa busca el nombre de paquete más cercano, de modo que texdoc bootabs acaba igualmente en el manual de booktabs. Cuando ni eso funciona, el mensaje es Unfortunately, there are no good matches for "...", seguido de un aviso sobre el mismo documento en texdoc.org.

Queda un mecanismo más que importa a quien lee en varios idiomas: texdoc deduce el idioma de la configuración regional del sistema y bonifica <nombre>-<código de idioma>.pdf. Un texdoc -l booktabs muestra, junto al booktabs.pdf en inglés, los directorios booktabs-de y booktabs-fr: manuales traducidos que el propio TeX Live distribuye. Por la misma razón, texdoc -l lshort devuelve más de sesenta resultados, con las ediciones por idioma en cabeza y marcadas [fr], [zh], [ko] y demás. Si la detección automática falla, basta una línea lang = es en el archivo de configuración personal para fijarla; texdoc --files indica dónde está, en macOS ~/Library/texmf/texdoc/texdoc.cnf. Con mode = list en ese mismo archivo, cada llamada futura se comportará como si se hubiera escrito -l.

¿Dónde está ese .sty? kpsewhich y tlmgr info

Un kpsewhich booktabs.sty devuelve en una línea la ruta absoluta del archivo que LaTeX leerá realmente. Cuando un documento se comporta de forma que contradice su manual, la primera sospecha no debería ser la versión sino la posibilidad de que el archivo leído no sea el que uno cree, y este comando lo resuelve al instante. Con --all aparecen todos los candidatos, en orden de búsqueda. Al probar kpsewhich --all article.cls se obtienen dos líneas: texmf-dist/tex/latex/base/article.cls y texmf-dist/tex/latex-dev/base/article.cls. El eclipse de un archivo por otro del mismo nombre se vuelve visible. Si alguna vez se escribió un .sty propio y se dejó en el árbol personal, conviene sospechar del directorio que indica kpsewhich -var-value=TEXMFHOME (~/Library/texmf en macOS). Cuando no encuentra nada, kpsewhich no imprime nada y termina con estado 1, de modo que también sirve dentro de una condición del intérprete de órdenes.

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 responde a otra pregunta: no dónde, sino qué dice el catálogo. Devuelve la descripción de una línea, la descripción larga, la colección a la que pertenece, la licencia (lppl1.3c), el tamaño de las partes src, doc y run, y la versión. También pueden aparecer campos como cat-contact-bugs y cat-contact-repository, que son las direcciones del gestor de incidencias del paquete. Al ejecutar tlmgr info --list booktabs los archivos aparecen en tres grupos, y esos tres grupos son la organización de directorios de TeX Live: tex/latex/booktabs/booktabs.sty (el código que se carga al compilar), doc/latex/booktabs/booktabs.pdf (el manual que abre texdoc) y source/latex/booktabs/booktabs.dtx junto con su .ins (el origen de ambos).

El par .dtx e .ins: una fuente que es su propio manual

Un archivo .dtx hace convivir el código y su comentario en un mismo archivo, y ese mismo archivo se procesa de dos maneras. Con tex <paquete>.ins, docstrip descarta la prosa y escribe el .sty; con pdflatex <paquete>.dtx, en cambio, se compone el código, anotado línea a línea, como manual en PDF. Probado localmente con multirow: tex multirow.ins generó tres archivos —multirow.sty, bigstrut.sty y bigdelim.sty— y pdflatex multirow.dtx produjo una fuente anotada de 30 páginas. La ventaja es poder rastrear comportamientos que el manual que abre texdoc nunca menciona: la implementación está ahí, de modo que la pregunta «¿por qué esta opción hace eso?» puede leerse hasta el final.

# 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

El caso extremo de este montaje es el propio LaTeX. Un texdoc source2e abre The LaTeX 2ε Sources: 1.308 páginas de núcleo anotado, firmadas por Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach y otros. Y en cuanto leer documentación se vuelve costumbre, uno empieza a fijarse en detalles. La versión que informa tlmgr info booktabs es 1.61803398: las cifras del número áureo φ = 1,618033988…, ampliadas en un dígito por cada publicación, y booktabs.dtx lo dice con sus propias palabras: «(converging to phi, the golden ratio)». Un número de versión que en realidad es una sucesión es una broma, pero solo puede confirmarse abriendo el .dtx.

Qué es CTAN: una sola dirección, construida en 1992

CTAN (el Comprehensive TeX Archive Network, ctan.org) existe para que haya un solo sitio donde depositar el material de TeX. Lo construyeron en 1992 Rainer Schöpf y Joachim Schrod en Alemania, Sebastian Rahtz en el Reino Unido y George Greenwade en Estados Unidos —el nombre lo puso Greenwade— y se anunció formalmente en la conferencia EuroTeX de Aston, en el Reino Unido, en 1993; la idea misma se remonta a una discusión de 1991. Antes, las macros y las fuentes estaban repartidas por multitud de servidores FTP y distintas personas volvían a reunir el mismo material cada una por su cuenta. El problema que resolvió CTAN no fue, pues, la falta de un lugar donde guardar las cosas: fue que había demasiados.

La entrada a CTAN hoy es una página de paquete, ctan.org/pkg/<nombre>. En ella figuran Sources, Documentation (el PDF), Version, Licenses, Copyright, Maintainer, Contained in (si TeX Live y MiKTeX lo distribuyen) y Topics. En la práctica, los dos últimos campos son los rentables. Contained in dice de un vistazo si tlmgr install traerá el paquete o si habrá que instalarlo a mano. Topics es la puerta del «no sé cómo se llama pero sé qué debe hacer»: buscando código de tablas, se llega por el tema table. El campo de licencia indica casi siempre LPPL, la LaTeX Project Public License, las condiciones estándar del mundo TeX para redistribución y modificación.

La palabra «Network» no es un adorno. CTAN se compone de un sitio central y de espejos oficiales repartidos por el mundo que se sincronizan automáticamente (mantener uno pide hoy unos 50 GB de disco). Por eso, escribir mirror.ctan.org en una dirección de descarga encamina hacia un espejo cercano: la guía oficial de TeX Live indica que el repositorio de paquetes por defecto es un espejo de CTAN elegido automáticamente a través de https://mirror.ctan.org. Para fijar un espejo concreto, la lista está en ctan.org/mirrors. El tráfico también corre en sentido inverso: los autores suben paquetes nuevos o actualizados al área de entrada del sitio central, el equipo de CTAN los procesa y los espejos los recogen. Las herramientas de ese envío también vienen en TeX Live: ctanify construye un archivo con la estructura que CTAN prefiere y ctan-o-mat valida una remisión antes de mandarla. Y TeX Live es en sí mismo una instantánea de CTAN: esos 3,7 GB de documentación del disco son una copia de este archivo.

Documentación local o en línea: a cuál creer

Lo que decide si un documento compila es la documentación que está en tu propio disco. Así que, cuando la pregunta es «¿por qué no funciona esto?», hay que abrir texdoc primero. Cuando la pregunta es «¿se ha añadido esta función?», lo que toca es mirar la página del paquete en CTAN o texdoc.org: esas fuentes están siempre al día. Ambas divergen de verdad. Cada edición de TeX Live acaba congelándose y las actualizaciones posteriores viajan con la siguiente edición, de modo que es habitual que la versión y la clasificación temática que informa tlmgr info sean más antiguas que las que muestra CTAN. Ante una discrepancia, el orden prudente es: confirmar la versión propia con tlmgr info <paquete> y después leerla frente a la ficha de CTAN. Cuando el código encontrado en la web no funciona, muchas veces el artículo no está anticuado: simplemente el entorno propio y el del autor son distintos.