Working with large documents

Nobody writes a 300-page thesis as a single .tex file. LaTeX’s answer to a large document is three commands — \input, \include and \includeonly — which split the project into one file per chapter and then let you rebuild only the chapter you are working on. The clever part is the machinery underneath: every time LaTeX finishes an included chapter it writes a checkpoint into that chapter’s .aux file, recording the value of every counter, page number included. That is why a skipped chapter does not disturb the numbering of the ones after it. This page starts at directory layout, passes through the relative-path trap that catches almost everyone, and ends with the failures that only a full build reveals.

How to lay out a large LaTeX project

Start from one rule: the main file contains no prose at all. main.tex holds the document class, the preamble and a list of \include lines, and nothing else. Chapters live in chapters/, images in figures/, the bibliography database in bib/. The main file then reads like a table of contents, and reordering chapters becomes a matter of reordering lines. The same property is what makes co-authoring bearable: people touch different files, so conflicts are rare and a Git diff stays inside the one chapter you edited. Once the preamble grows, move it into preamble.tex and pull it in with \input{preamble} — never \include a preamble, for a reason the next section makes clear.

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}

Numbering the files — 01-intro.tex, 02-method.tex — makes the editor’s file list match reading order. The other line worth adding is % !TEX root = ../main.tex at the top of every chapter file. TeXShop, TeXstudio, VS Code and most other editors read it and build main.tex even while a chapter is the frontmost file. Without it, sooner or later you compile a chapter on its own and meet ! LaTeX Error: Missing \begin{document}. — the inevitable result of a file that has no \documentclass, but it still costs a few minutes of puzzlement.

The difference between \input and \include

\input{f} pastes the contents of f.tex at that point and does nothing else. \include{f} is a chapter-level operation: it issues \clearpage before and after, and — the real point — it opens a separate f.aux and redirects auxiliary output there. That per-chapter .aux is the entire reason \include exists. Page numbers, cross-reference labels and table-of-contents lines are stored chapter by chapter, so when a chapter is later skipped, exactly that chapter’s information can be read back from the previous run. \input, by contrast, leaves no trace of a file boundary at all, which makes it the right tool for anything smaller than a chapter: loading the preamble, shared macros, the body of a table, a reusable block of boilerplate.

The rightmost column is where the difference bites hardest. Writing an \include inside a file that was itself included stops the run with ! LaTeX Error: \include cannot be nested. It looks like an arbitrary restriction, but the implementation makes it inevitable: the kernel keeps exactly one output stream for a chapter’s .aux file, so an inner \include would have nowhere to write its own. When you want to break a chapter into sections, call them from the chapter file with \input{chapters/02-method/setup} instead. One more consequence: \include does not belong in the preamble either — it warns \include should only be used after \begin{document}. That is precisely why a preamble is loaded with \input.

One more asymmetry costs people silently. \input{chapters/ch9} on a file that does not exist stops with ! LaTeX Error: File ... not found., but \include{chapters/ch9} in the same situation merely prints No file chapters/ch9.tex. into the log and builds as if nothing happened. A typo in an \include therefore produces not an error but a PDF with an entire chapter missing. After renaming a chapter, make searching the log for No file a habit.

Building one chapter with \includeonly, and why the page numbers stay right

Putting \includeonly{chapters/02-method} in the preamble processes that one \include and skips the rest. A full build that took minutes finishes in seconds — and the page numbers and cross-references of the skipped chapters remain correct. The trick has two halves. First, even for a skipped chapter LaTeX still writes the line \@input{chapters/01-intro.aux} into main.aux, so the previous run’s .aux is always read back and the \newlabel entries it holds keep \ref resolving. Second, at the end of every chapter LaTeX appends the current value of every counter to that chapter’s .aux. The kernel sources call this record, in so many words, a checkpoint; skipping a chapter simply replays it, advancing the page, chapter and figure counters to exactly where that chapter left off.

% 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}
}

Because of those two halves the partial-build PDF is closer to the real thing than you would expect. Even the table of contents survives: the .toc is written from the .aux files at the end of the run, so a skipped chapter still appears in the contents with its page number from last time. One precondition remains, though. Do one full build first. Skip a chapter whose .aux does not yet exist and its references stay ??, with LaTeX Warning: There were undefined references. in the log. Two details worth knowing: both \include and \includeonly strip a trailing .tex before comparing names, so \includeonly{chapters/02-method.tex} matches too; and \includeonly is preamble-only — after \begin{document} it gives ! LaTeX Error: Can be used only in preamble. Delete the line before submitting and rebuild every chapter. A partial-build PDF is a working approximation, not the finished document.

Why relative paths resolve from the main file, not from the chapter

Neither \input nor \include changes the current directory. TeX resolves every relative path against the working directory of the run, which is normally wherever main.tex sits. So an image path written inside chapters/02-method.tex must be spelled as seen from main.tex. \includegraphics{figures/plot} works; \includegraphics{../figures/plot}, which looks right from the chapter’s own folder, fails with ! LaTeX Error: File ... not found. This is where people conclude that moving a chapter broke its figures. The file moved, but the point of reference never did: it is still main.tex.

There are two remedies. The usual one is \graphicspath from graphicx, which registers the folders to search. Its syntax is peculiar and worth memorising: each folder gets its own pair of braces, and each needs a trailing slash — \graphicspath{{figures/}{chapters/figures/}}. After that, any chapter can write \includegraphics{plot} with neither folder nor extension. Use forward slashes as separators even on Windows. The second remedy suits projects where each chapter owns its figures: \subimport{chapters/}{02-method} from the import package makes relative paths inside that chapter resolve from chapters/. If a chapter may later be lifted into another project, that is the more portable arrangement.

% 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/

Compiling a chapter on its own: subfiles and standalone

\includeonly is a tool for building one chapter of the whole, not for turning a chapter into an independent PDF. When you want the chapter itself to be a document, use the subfiles package. Put \documentclass[../main]{subfiles} at the top of the chapter file and it compiles on its own, borrowing the main preamble, while the main file still drops it into place with \subfile{chapters/02-method}. Figures have the same idea available to them: a TikZ picture written against the standalone class typesets as a one-page PDF by itself, and the main document pulls it in with \usepackage{standalone} plus an ordinary \input.

% 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}

The cost is equally clear. A chapter built alone starts at page 1 and cannot see \labels defined in other chapters, so \ref yields ?? and the log reports LaTeX Warning: There were undefined references. Choose by purpose: \includeonly when you want speed while keeping the whole document’s numbering, subfiles when you need to hand your supervisor “chapter 3” as a file. A thesis that will be submitted as one PDF is happiest with \include plus \includeonly; a project whose chapters also live as papers, lecture notes or handouts is happiest with subfiles. Mixing both in one project means maintaining the preamble situation twice, which rarely pays.

Faster test builds with the draft option

\documentclass[draft]{report} does two jobs when test-building something large. First, it marks every line that runs past the text block — an overfull hbox — with a black rule in the margin, so bad breaks are visible at a glance. Second, it stops rendering images and substitutes a frame containing the filename; skipping image processing makes the compile noticeably lighter, and the more figures a chapter has the more it helps. To limit the effect to images, scope it with \usepackage[draft]{graphicx}. For the opposite — images visible but overfull lines flagged — set \overfullrule=5pt and you get the rules alone. Remember to switch draft back to final for the real build.

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

When a chapter compiles alone but the whole document fails

The cause is almost always one of four. (1) The chapter uses a package or macro that exists only in its own preamble — fine alone, ! Undefined control sequence. inside the book. (2) Two chapters define the same \label, so LaTeX Warning: Label ... multiply defined. appears and a reference quietly points at the wrong place. (3) A relative path written as seen from the chapter’s folder, the trap of the previous section. (4) A stale .aux. Case (2) is the dangerous one because it prints a wrong number rather than failing; prefixing labels with the chapter, as in \label{fig:method-setup}, rules it out structurally.

It is worth knowing how an .aux goes bad. Interrupt a build, or rename a chapter, and a half-written .aux can survive. The next run reads it and falls over on a line that has nothing to do with what you just edited. Whenever the error appears somewhere you did not touch, delete the generated files before debugging anything else. By hand that means .aux, .toc, .lof, .lot and .out — remembering that the per-chapter .aux files also sit inside chapters/. With latexmk, latexmk -c clears the intermediate files and latexmk -C clears the output as well. After deleting, run the build twice so references and the contents settle.

• Before starting an \includeonly session, do one full build so every chapter has a fresh .aux.
• Externalise heavy TikZ figures, or pre-render them to PDF and pull them in with \includegraphics.
• Put % !TEX root = ../main.tex at the top of each chapter file so the main document builds whichever file is open.
• Unless you use import, keep figures/ and bib/ next to main.tex, not next to the chapters.
• Prefix labels with the chapter, as in fig:method-setup, to make multiply defined structurally impossible.
• Before submitting, remove \includeonly and draft, delete the generated files, build clean, and read the log to the end for Warning and No file.

A closing word about rhythm. Long documents go well not for people who always build everything, nor for people who only ever build a fragment, but for people who alternate. Day to day, iterate on the current chapter with \includeonly and let latexmk handle rebuilding on save. At milestones, remove \includeonly and draft, build the whole thing, and watch the numbering, contents, index and bibliography settle. Before submission, delete the generated files, build clean, and read the log to the end. Splitting a document looks like a trick for speed, but it is just as much a trick for confidence: it is what makes the whole thing cheap to rebuild correctly, any day you like.