\include & \includeonly (LaTeX2e unofficial reference manual (November 2018))

Next: \input, Previous: \endinput, Up: Splitting the input [Contents][Index]

### 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, and it can only appear in the preamble.

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.tex`. 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.

Unofficial LaTeX2e reference manual