Trabajar con documentos grandes

Nadie escribe una tesis de 300 páginas en un único archivo .tex. La respuesta de LaTeX a un documento extenso son tres órdenes —\input, \include e \includeonly— que reparten el proyecto en un archivo por capítulo y luego permiten recomponer solo el capítulo en curso. Lo ingenioso está en la maquinaria de debajo: cada vez que termina un capítulo incluido, LaTeX escribe un punto de control en el .aux de ese capítulo y anota en él el valor de todos los contadores, número de página incluido. Por eso un capítulo omitido no descuadra la numeración de los siguientes. Esta página arranca en la organización de carpetas, atraviesa la trampa de las rutas relativas en la que cae casi todo el mundo y acaba con los fallos que solo una compilación completa revela.

Cómo organizar un proyecto LaTeX grande

Todo parte de una regla: el archivo principal no contiene texto. main.tex reúne la clase de documento, el preámbulo y una lista de líneas \include, y nada más. Los capítulos viven en chapters/, las imágenes en figures/, la base bibliográfica en bib/. El archivo principal se lee entonces como un índice, y reordenar capítulos es reordenar líneas. Esa misma propiedad hace llevadera la coautoría: cada persona toca archivos distintos, los conflictos escasean y un diff de Git se queda dentro del capítulo editado. En cuanto el preámbulo crece, conviene moverlo a preamble.tex y cargarlo con \input{preamble}; un preámbulo nunca se incluye con \include, por un motivo que la sección siguiente aclara.

thesis/
  main.tex
  preamble.tex          % packages and settings
  chapters/01-intro.tex  02-method.tex  03-results.tex
  figures/              % all images, next to main.tex
  bib/refs.bib

% main.tex -- no prose here, just structure
\documentclass[11pt,a4paper]{report}
\input{preamble}

\begin{document}
\tableofcontents

\include{chapters/01-intro}
\include{chapters/02-method}
\include{chapters/03-results}

\bibliographystyle{plain}
\bibliography{bib/refs}
\end{document}

Numerar los archivos —01-intro.tex, 02-method.tex— alinea la lista del editor con el orden de lectura. La otra línea que compensa añadir es % !TEX root = ../main.tex al principio de cada archivo de capítulo. TeXShop, TeXstudio, VS Code y la mayoría de los editores la leen y compilan main.tex aunque el archivo en primer plano sea un capítulo. Sin ella, tarde o temprano se compila un capítulo suelto y aparece ! LaTeX Error: Missing \begin{document}., consecuencia inevitable de un archivo sin \documentclass que aun así cuesta unos minutos de desconcierto.

La diferencia entre \input e \include

\input{f} pega el contenido de f.tex en ese punto y nada más. \include{f} opera a nivel de capítulo: emite un \clearpage antes y después y —lo esencial— abre un f.aux propio y desvía allí la información auxiliar. Ese .aux por capítulo es toda la razón de ser de \include. Números de página, etiquetas de referencias cruzadas y líneas del índice quedan guardados capítulo a capítulo, de modo que cuando más tarde se omite un capítulo son justamente sus datos los que se releen de la compilación anterior. \input, en cambio, no deja rastro alguno de frontera de archivo, lo que lo convierte en la herramienta para todo lo menor que un capítulo: cargar el preámbulo, macros comunes, el cuerpo de una tabla, un bloque de texto reutilizable.

La columna de la derecha contiene la diferencia más cara. Escribir un \include dentro de un archivo que a su vez fue incluido detiene la compilación con ! LaTeX Error: \include cannot be nested. Parece una restricción caprichosa, pero la implementación la vuelve inevitable: el núcleo reserva un único flujo de salida para el .aux de un capítulo, de modo que un \include interior no tendría dónde escribir el suyo. Para dividir un capítulo en secciones, se las llama desde el archivo del capítulo con \input{chapters/02-method/setup}. Otra consecuencia: \include tampoco cabe en el preámbulo, donde avisa con \include should only be used after \begin{document}. Por eso justamente un preámbulo se carga con \input.

Otra asimetría sale cara en silencio. \input{chapters/ch9} sobre un archivo inexistente se detiene con ! LaTeX Error: File ... not found., mientras que \include{chapters/ch9} en la misma situación se limita a escribir No file chapters/ch9.tex. en el registro y compila como si nada. Una errata en un \include no produce, pues, un error sino un PDF al que le falta un capítulo entero. Tras renombrar un capítulo, conviene adquirir el hábito de buscar No file en el registro.

Compilar un solo capítulo con \includeonly y por qué la paginación no se descuadra

Poner \includeonly{chapters/02-method} en el preámbulo procesa solo ese \include y omite los demás. Una compilación completa de varios minutos termina en segundos y la paginación y las referencias cruzadas de los capítulos omitidos siguen siendo correctas. El truco tiene dos mitades. Primero, incluso para un capítulo omitido LaTeX escribe en main.aux la línea \@input{chapters/01-intro.aux}: el .aux de la compilación anterior siempre se relee, y las entradas \newlabel que guarda mantienen operativo a \ref. Segundo, al final de cada capítulo LaTeX añade al .aux de ese capítulo el valor actual de todos los contadores. Las fuentes del núcleo llaman a ese registro, literalmente, punto de control; omitir un capítulo consiste sencillamente en reproducirlo, con lo que los contadores de página, capítulo y figura saltan justo adonde ese capítulo lo dejó.

% in the preamble of main.tex
\includeonly{chapters/02-method}
% several at once, comma separated, no spaces needed around the commas
% \includeonly{chapters/02-method,chapters/03-results}

% chapters/01-intro.aux, written by the last full build (trimmed)
\newlabel{ch:intro}{{1}{2}{}{}{}}
\@setckpt{chapters/01-intro}{
\setcounter{page}{5}
\setcounter{chapter}{1}
\setcounter{figure}{0}
}

Gracias a esas dos mitades, el PDF de una compilación parcial se parece al definitivo más de lo que cabría esperar. Hasta el índice aguanta: el .toc se escribe al final de la compilación a partir de los archivos .aux, de modo que un capítulo omitido sigue apareciendo en el índice con su número de página de la vez anterior. Queda, eso sí, una condición: hacer antes una compilación completa. Omitir un capítulo cuyo .aux todavía no existe deja sus referencias en ?? y escribe LaTeX Warning: There were undefined references. en el registro. Dos detalles útiles: tanto \include como \includeonly quitan un .tex final antes de comparar nombres, así que \includeonly{chapters/02-method.tex} también coincide; y \includeonly pertenece solo al preámbulo, pues tras \begin{document} da ! LaTeX Error: Can be used only in preamble. Antes de entregar hay que borrar la línea y recompilar todos los capítulos. El PDF de una compilación parcial es una aproximación de trabajo, no el documento terminado.

Por qué las rutas relativas se resuelven desde el archivo principal

Ni \input ni \include cambian el directorio actual. TeX resuelve toda ruta relativa respecto al directorio de trabajo de la compilación, que normalmente es donde está main.tex. Así que una ruta de imagen escrita dentro de chapters/02-method.tex debe escribirse tal como se ve desde main.tex. \includegraphics{figures/plot} funciona; \includegraphics{../figures/plot}, correcto visto desde la carpeta del capítulo, falla con ! LaTeX Error: File ... not found. Aquí es donde se concluye que mover un capítulo rompió sus figuras. Lo que se movió fue el archivo; el punto de referencia siguió siendo main.tex.

Hay dos remedios. El habitual es \graphicspath, de graphicx, que registra las carpetas donde buscar. Su sintaxis es peculiar y conviene memorizarla: cada carpeta lleva su propio par de llaves y necesita una barra final —\graphicspath{{figures/}{chapters/figures/}}—. A partir de ahí, cualquier capítulo puede escribir \includegraphics{plot}, sin carpeta ni extensión. El separador es la barra inclinada, también en Windows. El segundo remedio encaja en proyectos donde cada capítulo posee sus figuras: \subimport{chapters/}{02-method}, del paquete import, hace que las rutas relativas de ese capítulo se resuelvan desde chapters/. Si el capítulo puede acabar en otro proyecto, esa disposición viaja mejor.

% option A -- one shared figure folder, registered once in the preamble
\usepackage{graphicx}
\graphicspath{{figures/}{chapters/figures/}}   % braces per folder, trailing slash
% then, anywhere in any chapter:
%   \includegraphics[width=0.8\linewidth]{plot}

% option B -- each chapter carries its own figures
\usepackage{import}
% in main.tex, instead of \include{chapters/02-method}:
\subimport{chapters/}{02-method}   % paths inside resolve from chapters/

Componer un capítulo por separado: subfiles y standalone

\includeonly sirve para componer deprisa un capítulo dentro del conjunto, no para convertirlo en un PDF independiente. Cuando se quiere que el capítulo sea en sí mismo un documento, se recurre al paquete subfiles. Con \documentclass[../main]{subfiles} en la cabecera del archivo de capítulo, este compila por su cuenta tomando prestado el preámbulo principal, mientras el archivo principal lo sigue insertando con \subfile{chapters/02-method}. Las figuras cuentan con la misma idea: una imagen TikZ escrita para la clase standalone se compone sola como un PDF de una página, y el documento principal la incorpora con \usepackage{standalone} y un \input corriente.

% main.tex
\documentclass{report}
\usepackage{graphicx}
\usepackage{subfiles}
\begin{document}
\subfile{chapters/02-method}
\end{document}

% chapters/02-method.tex -- also compiles on its own
\documentclass[../main]{subfiles}
\begin{document}
\chapter{Method}
This chapter builds alone and inside the book.
\end{document}

El precio está igual de claro. Un capítulo compilado solo empieza en la página 1 y no ve los \label definidos en otros capítulos, de modo que \ref da ?? y el registro informa LaTeX Warning: There were undefined references. La elección sigue al propósito: \includeonly para ganar velocidad conservando la numeración del conjunto, subfiles para entregar «el capítulo 3» como archivo. Una tesis que se presenta como un único PDF se lleva muy bien con \include más \includeonly; un proyecto cuyos capítulos viven además como artículos, apuntes o material de clase prefiere subfiles. Mezclar ambos en un mismo proyecto obliga a mantener el preámbulo por duplicado, y rara vez compensa.

Compilaciones de prueba más rápidas con la opción draft

\documentclass[draft]{report} cumple dos funciones al probar un documento grande. Primero, marca con una regla negra en el margen toda línea que se sale de la caja de texto —una overfull hbox—, con lo que los cortes defectuosos se ven de un vistazo. Segundo, deja de renderizar imágenes y las sustituye por un marco con el nombre del archivo; al omitirse el procesamiento de imágenes la compilación se aligera de forma apreciable, y cuantas más figuras tenga el capítulo, más se nota. Para limitarlo a las imágenes se acota con \usepackage[draft]{graphicx}. A la inversa, \overfullrule=5pt produce solo las reglas y mantiene visibles las imágenes. Para la compilación definitiva, draft vuelve a ser final.

\documentclass[draft]{report}   % skip images, show overfull rules
% scope it to images only:
% \usepackage[draft]{graphicx}
% keep images, still flag overfull lines:
% \overfullrule=5pt

Cuando un capítulo compila solo pero el documento entero falla

La causa casi siempre es una de cuatro. (1) El capítulo usa un paquete o una macro que solo existe en su propio preámbulo: solo compila, dentro del libro aparece ! Undefined control sequence. (2) Dos capítulos definen la misma \label, con lo que surge LaTeX Warning: Label ... multiply defined. y una referencia apunta calladamente al sitio equivocado. (3) Una ruta relativa escrita desde la carpeta del capítulo, la trampa de la sección anterior. (4) Un .aux caducado. El caso (2) es el peligroso, porque no falla: imprime un número erróneo. Prefijar las etiquetas con el capítulo, como en \label{fig:method-setup}, lo descarta de raíz.

Conviene saber cómo se estropea un .aux. Una compilación interrumpida, o un capítulo renombrado, puede dejar un .aux a medio escribir. La siguiente compilación lo lee y tropieza en una línea que nada tiene que ver con lo último editado. Siempre que el error aparezca donde no se ha tocado nada, lo primero es borrar los archivos generados. A mano son .aux, .toc, .lof, .lot y .out, sin olvidar que los .aux de cada capítulo están además dentro de chapters/. Con latexmk, latexmk -c limpia los archivos intermedios y latexmk -C limpia también la salida. Tras borrar, compilar dos veces para que referencias e índice se asienten.

• Antes de una sesión con \includeonly, hacer una compilación completa para que cada capítulo tenga un .aux reciente.
• Externalizar las figuras TikZ pesadas, o prerrenderizarlas a PDF y cargarlas con \includegraphics.
• Poner % !TEX root = ../main.tex al principio de cada archivo de capítulo para que siempre se compile el documento principal.
• Salvo que se use import, mantener figures/ y bib/ junto a main.tex, no junto a los capítulos.
• Prefijar las etiquetas con el capítulo, como fig:method-setup, para hacer imposible multiply defined.
• Antes de entregar, quitar \includeonly y draft, borrar los archivos generados, compilar en limpio y leer el registro hasta el final buscando Warning y No file.

Una última palabra sobre el ritmo. Los documentos largos les salen bien no a quienes compilan siempre todo, ni a quienes compilan siempre un fragmento, sino a quienes alternan. En el día a día se trabaja el capítulo en curso con \includeonly y se deja que latexmk recompile al guardar. En los hitos se quitan \includeonly y draft, se compila el conjunto y se comprueba cómo se asientan numeración, índice, índice analítico y bibliografía. Antes de entregar se borran los archivos generados, se compila en limpio y se lee el registro hasta el final. Dividir parece un truco de velocidad, pero es igualmente un truco de tranquilidad: hace barato recomponer correctamente el conjunto cualquier día.