24.2 \include & \includeonly ¶

Synopsis:

\includeonly{  % in document preamble
  ...
  filename,
  ...
  }
  ...
\include{filename}  % in document body 

Bring material from the external file filename.tex into a LaTeX document.

The \include command does three things: it executes \clearpage (see \clearpage & \cleardoublepage), then it inputs the material from filename.tex into the document, and then it does another \clearpage. This command can only appear in the document body.

The \includeonly command controls which files will be read by LaTeX under subsequent \include commands. Its list of filenames is comma-separated. It must appear in the preamble or even earlier, e.g., the command line; it can’t appear in the document body.

This example root document, constitution.tex, brings in three files, preamble.tex, articles.tex, and amendments.tex.

\documentclass{book}
\includeonly{
  preamble,
  articles,
  amendments
  }
\begin{document}
\include{preamble}
\include{articles}
\include{amendments}
\end{document}

The file preamble.tex contains no special code; you have just excerpted the chapter from consitution.tex and put it in a separate file just for editing convenience.

\chapter{Preamble}
We the People of the United States,
in Order to form a more perfect Union, ...

Running LaTeX on constitution.tex makes the material from the three files appear in the document but also generates the auxiliary files preamble.aux, articles.aux, and amendments.aux. These contain information such as page numbers and cross-references (see Cross references). If you now comment out \includeonly’s lines with preamble and amendments and run LaTeX again then the resulting document shows only the material from articles.tex, not the material from preamble.tex or amendments.tex. Nonetheless, all of the auxiliary information from the omitted files is still there, including the starting page number of the chapter.

If the document preamble does not have \includeonly then LaTeX will include all the files you call for with \include commands.

The \include command makes a new page. To avoid that, see \input (which, however, does not retain the auxiliary information).

See Larger book template, for another example using \include and \includeonly. That example also uses \input for some material that will not necessarily start on a new page.

File names can involve paths.

\documentclass{book}
\includeonly{
  chapters/chap1,
  }
\begin{document}
\include{chapters/chap1}
\end{document}

To make your document portable across distributions and platforms you should avoid spaces in the file names. The tradition is to instead use dashes or underscores. Nevertheless, for the name ‘amo amas amat’, this works under TeX Live on GNU/Linux:

\documentclass{book}
\includeonly{
  "amo\space amas\space amat"
  }
\begin{document}
\include{"amo\space amas\space amat"}
\end{document}

and this works under MiKTeX on Windows:

\documentclass{book}
\includeonly{
  {"amo amas amat"}
  }
\begin{document}
\include{{"amo amas amat"}}
\end{document}

You cannot use \include inside a file that is being included or you get ‘LaTeX Error: \include cannot be nested.’ The \include command cannot appear in the document preamble; you will get ‘LaTeX Error: Missing \begin{document}’.

If a file that you \include does not exist, for instance if you \include{athiesm} but you meant \include{atheism}, then LaTeX does not give you an error but will warn you ‘No file athiesm.tex.’ (It will also create athiesm.aux.)

If you \include the root file in itself then you first get ‘LaTeX Error: Can be used only in preamble.’ Later runs get ‘TeX capacity exceeded, sorry [text input levels=15]’. To fix this, you must remove the inclusion \include{root} but also delete the file root.aux and rerun LaTeX.