Herramientas de compilación

Cuando alguien dice que ha instalado LaTeX, lo que de verdad aterriza en el disco no es un programa sino un directorio lleno de herramientas de línea de comandos. En esta máquina con TeX Live 2024 ese directorio guarda cerca de 490 órdenes, y durante una sesión normal de escritura se teclean una o dos. Las otras cuatrocientas ochenta y pico son la reserva que la distribución mantiene para el día en que un documento deja de colaborar: kpsewhich para preguntar dónde vive realmente un paquete, texdoc para abrir su manual, tlmgr para instalar lo que falta, pdfcrop para recortar una figura. Esta página traza el mapa de esa reserva, ordenada por la pregunta que responde cada herramienta. Los controladores de compilación que se sitúan por encima —latexmk, llmk, arara— tienen página propia; aquí nos quedamos un nivel más abajo.

«En mi máquina compila»: la primera orden que hay que lanzar es kpsewhich

El mismo .tex compila en tu máquina y se detiene en la de un coautor. Casi siempre es una cuestión de dónde están los archivos, y kpsewhich la zanja en una línea. La orden resulta concluyente porque no busca por su cuenta: todos los motores de TeX Live 2024 están enlazados con kpathsea, la biblioteca de búsqueda de archivos (versión 6.4.0 en esta edición), y kpsewhich es esa misma biblioteca envuelta como orden independiente. La ruta que imprime es, pues, el archivo que el motor abrirá de verdad, no una conjetura. Si kpsewhich amsmath.sty no imprime nada, el paquete sencillamente no está, y al compilar aparecerá ! LaTeX Error: File amsmath.sty not found. Si imprime algo, el problema no es la ausencia sino que se está viendo lo que no toca.

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

Con --all se obtienen todas las coincidencias en orden de búsqueda, no solo la primera. Ahí se esconde el fallo más desagradable, peor que un archivo ausente. TeX usa el primer resultado, de modo que un .sty viejo copiado en la carpeta del manuscrito hace años tapa sin ruido la versión actual de la distribución. En el registro no aparece nada raro; simplemente el comportamiento cambia de una máquina a otra. Una sola ejecución de kpsewhich --all lo hace visible: el mismo nombre aparece dos veces. kpsewhich tampoco se limita a los .sty: las clases (article.cls), las métricas de fuentes y los archivos de configuración se localizan con el mismo mecanismo. Si la búsqueda cambia según el motor, se puede preguntar bajo otro nombre con --progname=xelatex, y acotar por tipo de archivo con --format=tfm (kpsewhich --help-formats enumera los tipos).

--var-value y --show-path: leer lo que el motor da por cierto

kpsewhich --var-value=TEXMFHOME imprime una sola variable de configuración; kpsewhich --show-path=tex imprime la lista completa y ordenada de directorios en los que se buscan los archivos .tex. La primera responde al «dónde» y la segunda al «en qué orden». Con esas dos órdenes se deja de depender de lo que la documentación dice en general y se leen los valores que la máquina de delante usa de verdad. Cuatro variables importan sobre todo, porque los árboles de búsqueda de TeX están separados por función: personal, del sitio, de la distribución y de archivos generados. El orden también significa algo: el árbol personal va antes que la distribución, y por eso un .sty propio puede sustituir a uno estándar.

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

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

Dónde poner tus propios .sty: el árbol texmf personal

Un .sty o un .cls escrito por uno mismo, o un paquete descargado a mano desde CTAN, va en TEXMFHOME. No conviene adivinar la ubicación: hay que preguntársela a kpsewhich --var-value=TEXMFHOME. En macOS con MacTeX responde ~/Library/texmf; una instalación de TeX Live en Linux suele responder ~/texmf. Aquí acecha una trampa: ese directorio normalmente todavía no existe. kpsewhich informa de la ubicación configurada, no de una existente, así que el primer paso es crear la ruta que imprime. Dentro se sigue la TDS (TeX Directory Structure): un paquete LaTeX va a TEXMFHOME/tex/latex/<nombre>/<nombre>.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 y mktexlsr: un solo programa con dos nombres

texhash y mktexlsr hacen lo mismo; más exactamente, son el mismo archivo. Al mirar dentro del directorio bin de TeX Live 2024, texhash resulta ser un enlace simbólico a mktexlsr. Ambos reconstruyen ls-R, la base de datos de nombres de archivo. El árbol de la distribución es enorme: en esta máquina, texmf-dist/ls-R ocupa por sí solo más de 5 MB. Recorrer el disco cada vez sería demasiado lento, así que los árboles del sistema se consultan a través de ls-R, y el trato es que hay que reconstruir la base cada vez que se añaden archivos. Por eso la respuesta a «he puesto algo en TEXMFLOCAL y sigue sin encontrarse» es sudo mktexlsr. En cambio, el árbol TEXMFHOME de la sección anterior se lee del disco cada vez, de modo que un .sty depositado allí se encuentra al instante: basta crear uno y preguntar a kpsewhich para obtener respuesta sin haber ejecutado texhash ni una vez. Es una razón más para preferir el árbol personal.

texdoc: el manual del paquete ya está en tu disco

Al teclear texdoc geometry se abre en el visor el manual en PDF del paquete geometry. Sin red de por medio: cuando el paquete llegó desde CTAN, su documentación venía dentro. En eso reside el valor de la orden: el manual de la versión que realmente está instalada es más fiable que cualquier tutorial envejecido que devuelva un buscador. Varios documentos pueden compartir nombre, así que ante la duda conviene listar los candidatos con texdoc -l geometry; en esta máquina aparecen el geometry.pdf inglés y también un geometry-de.pdf alemán. La opción -s (showall) amplía la red a resultados menos relacionados, y -M produce una salida legible por máquina. La versión incluida en TeX Live 2024 es Texdoc 4.1 (2024-03-10), cuya línea de copyright menciona a Manuel Pégourié-Gonnard, Takuto Asakura y el 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 y qué significa «TeX Live 2024 is frozen»

tlmgr es el gestor de paquetes de TeX Live, y tres subórdenes cubren el uso diario: tlmgr info NOMBRE para preguntar por un paquete, tlmgr install NOMBRE para añadirlo y tlmgr update --self --all para ponerlo todo al día. La salida de info es la más práctica de las tres: installed: Yes indica si está presente, revision: de qué versión se trata y collection: a qué conjunto pertenece. Un detalle aquí ahorra media tarde: el nombre de una orden y el de un paquete de TeX Live no siempre coinciden. Ante tlmgr info llmk la respuesta empieza por tlmgr: cannot find package llmk, pero acto seguido el programa busca por su cuenta en descripciones y nombres de archivo y ofrece light-latex-make. La orden llmk sencillamente no vive en un paquete con ese nombre.

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

La otra cosa que sobresalta la primera vez es el aviso de congelación. En TeX Live 2024, la mayoría de las subórdenes de tlmgr empiezan imprimiendo TeX Live 2024 is frozen y a continuación and will no longer be routinely updated. Es un aviso, no un error. Solo describe cómo funciona TeX Live: en cuanto aparece una nueva edición anual, el repositorio del año anterior deja de recibir actualizaciones rutinarias. La orden sigue ejecutándose por debajo: tlmgr info amsmath imprime el cartel y después la información completa del paquete, como siempre. El remedio, por tanto, no es reintentar sino instalar la edición anual más reciente. Además, en una instalación estándar como MacTeX el directorio /usr/local/texlive/2024/texmf-dist pertenece a root, de modo que tlmgr install y tlmgr update exigen sudo. En una máquina sin permisos de administrador, dejar el archivo a mano en TEXMFHOME, como en la sección anterior, suele ser más rápido.

pdfcrop: recortar el margen blanco de una figura en PDF

Ejecutar pdfcrop figure.pdf produce figure-crop.pdf, con los márgenes calculados y eliminados página a página. Hace falta cuando una figura TikZ se compuso como archivo aparte, o cuando otro programa exportó un PDF con la forma de «un dibujito en medio de una hoja A4». Incluir eso tal cual con \includegraphics equivale a pegar el papel, no la imagen. Para conservar a propósito un margen, --margins "5 5 5 5" indica los cuatro lados; la unidad es el bp (big point). La trampa está en la dependencia: pdfcrop no recorta por sí mismo, sino que por omisión maneja Ghostscript (gs, modificable con --gscmd) y además un motor TeX. Casi todos los avisos de «pdfcrop está instalado pero no funciona» se reducen a la falta de Ghostscript. La versión incluida en TeX Live 2024 es pdfcrop 1.42 (2023/04/15, de 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

Mirar dentro de un PDF terminado: pdftotext no es una orden de TeX

Para extraer texto de un PDF terminado, casi todas las guías echan mano de pdftotext. Conviene saber, sin embargo, que pdftotext no forma parte de TeX Live. No aparece en ningún rincón del directorio bin de TeX Live 2024; la copia que hay en este Mac la puso el paquete poppler de Homebrew. Lo mismo vale para pdfinfo. Nada impide usarlos, pero un pdftotext: command not found en una máquina con TeX perfectamente instalado no es una avería: sencillamente es otro programa. Lo que sí trae TeX Live es pdftosrc, cuya línea de uso reza pdftosrc <PDF-file> [<stream-object-number>]: una herramienta para extraer un objeto de flujo de un PDF. Para la revisión diaria, leer el archivo .log suele ser más rápido que hurgar en el PDF; y las herramientas vecinas —texfot para condensar el registro, Ghostscript para operar sobre PDF, dvisvgm para salida vectorial— están reunidas en una página propia.

Qué orden para cada síntoma

Lo que vale la pena convertir en hábito es el orden de las preguntas. En cuanto algo parece raro, conviene comprobar la ubicación con kpsewhich y la especificación con texdoc antes de preguntar a nadie: ninguna de las dos exige red ni permisos de administrador, y ambas responden en segundos. Solo cuando eso revela una ausencia real entra en escena tlmgr; y ante la duda sobre dónde dejar un archivo, la elección es TEXMFHOME. La capa que automatiza cuántas veces y en qué orden se ejecuta el motor —latexmk y sus parientes— no es esta, hecha de buscar, leer e instalar. Por mucho que se afine la primera, las discrepancias entre máquinas no desaparecerán hasta que la segunda sea sólida.