Skip to content
Topos Uranos
English

Long documents

Summary

This lesson teaches how to divide a long document into several files without its ceasing to be a single document. It explains why a thesis, a book or an edited volume should be divided; it distinguishes \input, which inserts a file as if its text were written in its place, from \include, which typesets a chapter on pages of its own and with an auxiliary file of its own; it shows how \includeonly compiles only some chapters while keeping the numbering and the references, and under what condition it achieves this; it proposes an organization of folders and file names; it teaches how to declare the master document in Texmaker and always to compile from the main file; it presents the subfiles package for compiling a chapter on its own; it develops the structure of a thesis as a complete case; and it goes through the most frequent errors, with their real messages.

Learning objectives

  1. Decide, for each piece of a long document, whether it should be inserted with \input or with \include, according to their effects on the pages and on the auxiliary files.
  2. Predict which numbers, pages and references \includeonly produces, and explain on which earlier compilation their preservation depends.
  3. Organize a project into a main file and folders, with paths relative to the main file and file names that cause no trouble.
  4. Configure Texmaker so that it compiles the master document from any file of the project, and prepare with subfiles chapters that also compile on their own.
  5. Recognize in the log the errors peculiar to divided documents, and distinguish those that stop the compilation from those that let it finish with an incomplete result.

Why divide a document

A fifteen-page article fits comfortably in a single file. A two-hundred-page thesis does not: the file runs to thousands of lines, finding a passage means searching for it, and every compilation goes through the whole document even if only a comma in the last chapter has changed. A book adds chapters written at different times; an edited volume, chapters written by different authors, each at their own pace. In all three cases each chapter is best kept in a file of its own.

Dividing the files, however, must not divide the document. The table of contents must list every chapter, the numbering must continue from one to the next, and a reference written in the first must find the section of the fifth. The solution LaTeX offers is a main file, which contains the class, the preamble and the order of the pieces, and which inserts each piece in its place with a command. The engine always compiles the main file; the pieces are not documents, but fragments of its body. From this follows the rule that runs through the whole lesson: a piece has no preamble, and it is compiled from the main file.

There are two commands for inserting a piece, \input and \include, and the difference between them is not one of style: each does something different with the pages and with the auxiliary files.