Splitting the input

LaTeX lets you split a large document into several smaller ones. This can simplify editing or allow multiple authors to work on the document. It can also speed processing.

Regardless of how many separate files you use, there is always one root file, on which LaTeX compilation starts. This shows such a file with five included files.

\documentclass{book}
\includeonly{  % comment out lines below to omit compiling
  pref,
  chap1,
  chap2,
  append,
  bib
  }
\begin{document}
\frontmatter
\include{pref} 
\mainmatter
\include{chap1} 
\include{chap2}
\appendix
\include{append}
\backmatter
\include{bib} 
\end{document}

This will bring in material from pref.tex, chap1.tex, chap2.tex, append.tex, and bib.tex. If you compile this file, and then comment out all of the lines inside \includeonly{...} except for chap1, and compile again, then LaTeX will only process the material in the first chapter. Thus, your output will appear more quickly and be shorter to print. However, the advantage of the \includeonly command is that LaTeX will retain the page numbers and all of the cross reference information from the other parts of the document so these will appear in your output correctly.

See Larger book template for another example of \includeonly.


\endinput

Synopsis:

\endinput

When you \include{filename}, inside filename.tex the material after \endinput will not be included. This command is optional; if filename.tex has no \endinput then LaTeX will read all of the file.

For example, suppose that a document’s root file has \input{chap1} and this is chap1.tex.

\chapter{One}
This material will appear in the document. 
\endinput
This will not appear.

This can be useful for putting documentation or comments at the end of a file, or for avoiding junk characters that can be added during mailing. It is also useful for debugging: one strategy to localize errors is to put \endinput halfway through the included file and see if the error disappears. Now, knowing which half contains the error, moving \endinput to halfway through that area further narrows down the location. This process rapidly finds the offending line.

After reading \endinput, LaTeX continues to read to the end of the line, so something can follow this command and be read nonetheless. This allows you, for instance, to close an \if... with a \fi.


\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.


\input

Synopsis:

\input{filename}

LaTeX processes the file as if its contents were inserted in the current file. For a more sophisticated inclusion mechanism see \include & \includeonly.

If filename does not end in ‘.tex’ then LaTeX first tries the filename with that extension; this is the usual case. If filename ends with ‘.tex’ then LaTeX looks for the filename as it is.

For example, this

\input{macros}

will cause LaTeX to first look for macros.tex. If it finds that file then it processes its contents as thought they had been copy-pasted in. If there is no file of the name macros.tex then LaTeX tries the name macros, without an extension. (This may vary by distribution.)

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:

\input{"amo\space amas\space amat"}

and this works under MiKTeX on Windows:

\input{{"amo amas amat"}}