LaTeX/Multiple files

Getting LaTeX to process multiple files

As your work grows, your LaTeX file can become unwieldy and confusing, especially if you are writing a long article with substantial, discrete sections, or a full-length book. In such cases it is good practice to split your work into several files. For example, if you are writing a book, it makes a lot of sense to write each chapter in a separate .tex file. LaTeX makes this very easy thanks to two commands:

\input{filename}

and

\include{filename}

The differences between these files will be explained below but what they have in common is that they process the contents of filename.tex before continuing with the rest of the base file. When the compiler processes your base file and reaches the command \input or \include, it reads filename.tex and processes its content in accordance with the formatting commands specified in the base file. This way you can put all the formatting options in your base file and then input or include the files which contain the actual content of your work. This means that the important part of your working process, i.e. writing, is kept largely separate from formatting choices (which is one of the main reasons why LaTeX is so good for serious writing!). You will thus be dealing solely with text and very basic commands such as \section, \emph etc. Your document will be uncluttered and much easier to work with.

The second method of including a file, \include{filename}, differs from the first in some important ways. You cannot nest \include statements within a file added via \include; \input, on the other hand, allows you to call files which themselves call other files, ad infinitum (well, nearly!). You can, however, \include a file which contains one or more \input commands. Please resist the temptation to nest files in this way simply because the system can do it: you will end up with just another kind of complexity!

A further important difference is that using \include will force a page break (which makes it ideal for a book's chapters), whereas the input command does not (which in turn makes it ideal for, say, a long article with discrete sections, which of course are not normally set on a new page).

Working on discrete parts of your documents has consequences for how the base file is compiled; these will be dealt with below.

Using different paths

When the LaTeX compiler finds a reference to an external file in the base file, it will look for it in the same directory. However, you can in principle refer to any file on your system, using both absolute and relative paths.

An absolute path is a full path- and filename with every element specified. So, filename.tex might have the full path,

\input{/home/user/texfiles/filename.tex}

If you had created the directory myfiles for your writing project, in your texfiles directory, its full path would be,

\input{/home/user/texfiles/myfiles/filename.tex}

Obviously, using absolute paths is inefficient if you are referring to a file in the current directory. If, however, you need to include a file which is always kept at a specific place in your system, you may refer to it with an absolute path, for example,

\input{/home/user/documents/useful/foo.tex}

In practice, an absolute file path is generally used when one has to refer to a file which is quite some way away in the file system (or perhaps even on a different server!). One word of warning: do not leave empty spaces in the filenames, they can cause ambiguous behaviour. Either leave no spaces or use underscores _ instead.

You may, however, need to make your source portable (to another computer or to a different location of your harddisk), in which case relative paths should be used if you wish to avoid unnecessary re-writing of path names. Or, a relative path may simply be a more efficient and elegant way of referring to a file. A relative path is one which is defined in relation to the current directory, in our case the one which contains the base file. LaTeX uses the standard UNIX notation: with a simple dot . you refer to the current directory, and by two dots .. you refer to the previous directory, that is the one above the current directory in the file system tree. The slash / is used to separate the different components of a pathname: directories and filenames. So by ./ you refer to the current directory, by ../ you refer to the previous directory, by ../../ you refer to a directory which is two steps upwards in the filesystem tree. Writing

\input{./filename.tex}

will have exactly the same effect as writing

\input{filename.tex}

but if you found it more convenient to put all your files in a sub-directory of your current directory, called myfiles, you would refer to that file by specifying

\input{./myfiles/filename.tex}

Indeed, in our example of the absolute path above, you could refer to that file relatively, too:

\input{../../documents/useful/foo.tex}

Of course, all commonly used file systems – Linux, Mac OS X and Windows – also feature the UNIX ./, ../ facility outlined above. Do note, however, that LaTeX uses forward slashes / even on Microsoft Windows platforms, which use backslashes \ in pathnames. LaTeX implementations for Windows systems perform this conversion for you, which ensures that your document will be valid across all installations.

This flexibility, inherent in the way in which LaTeX is integrated with modern file systems, lets you input files in a way which suits your particular set-up.

Compiling the base file

When you compile your document, page references and the like will change according to your use of the \input and \include commands. Normally LaTeX users only run the compiler on parts of the document to check that an individual chapter is syntactically correct and looks as the writer intended. A full run is generally only performed for producing a full draft or the final version. In such cases, it is invariably necessary to run LaTeX twice or more to resolve all the page numbers, references, etc. (especially if you are using bibliographic software such as BiBTeX, too).

The simplest way to check that one or more of the various components of your work is syntactically robust, is to comment out the command with a percentage sign, for example:

\documentclass{article}
\begin{document}
%\input{Section_1}
%\input{Section_2}
%\input{Section_3}
\input{Section_4}
%\input{Section_5}
\end{document}

This code will process your base file with the article conventions but only the material in the file Section_4.tex will be processed. If that was, say, the last thing you needed to check before sending off to that major journal, you would then simply remove all the percentage signs and re-run LaTeX, repeating the compiling process as necessary to resolve all references, page numbers and so on.

Using \includeonly

Using this command provides more complex, and hence more useful possibilities. If you include the following command in your preamble, i.e. before \begin{document},

\includeonly{filename1,filename2,...}

only the files specified between the curly braces will be included. Note that you can have one or more files as the argument to this command: separate them with a comma, no spaces.

This requires that there are \include commands in the document which specify these files. The filename should be written without the .tex file extension:

\documentclass{book}
\includeonly{Chapter_1,Chapter_4)
\begin{document}
\include{Chapter_1}  %Note that we are using Chapter_1 and not Chapter_1.tex
\include{Chapter_2}
\include{Chapter_3}
\include{Chapter_4}
\end{document}

This code would process the base file but only include the content of the author's first and fourth chapters (Chapter_1.tex and Chapter_4.tex). Importantly, this alternative retains as much of the .aux information as possible from the previous run, so messes up your cross-references much less than the makeshift suggestion above.

Subfiles package

A disadvantage of using \input and \include is that only the "root" document can be compiled and not the "child" documents individually. The package subfiles resolves this problem.

In the "root" document the package must be loaded as:

\usepackage{subfiles}

Instead of using \input and \include, "child" documents must be loaded as follows:

\subfile{filename}

The "child" documents must start with the following statements:

\documentclass[rootdocument.tex]{subfiles} 
\begin{document}

and end with:

\end{document}

In summary, root document (main.tex) looks like:

\documentclass{book} 
\usepackage{subfiles}
\begin{document}
%% my document content
\subfile{chapter1}
%% more of my document content
\end{document}

and chapter 1 (chapter1.tex) looks like:

\documentclass[main.tex]{subfiles} 
\begin{document}
%% my chapter 1 content
%%
%% more of my chapter 1 content
\end{document}

Some linux distributions, don't have subfiles package in their latex distributions. You can download subfiles.zip to generate subfiles.cls and subfiles.sty files:

wget http://mirror.ctan.org/macros/latex/contrib/subfiles.zip
unzip subfiles.zip
cd subfiles
latex subfiles.dtx
latex subfiles.ins

Inserting PDF files

If you need to insert an existing, possibly multi-page, PDF file into your LaTeX document, whether or not the included PDF was compiled with LaTeX or another tool, consider using the pdfpages package. In the preamble, include the package:

\usepackage[final]{pdfpages}

This package also allows you to specify which pages you wish to include: for example, to insert pages 3 to 6 from some file insertme.pdf, use:

\includepdf[pages=3-6]{insertme.pdf}

To insert the whole of insertme.pdf:

\includepdf[pages=-]{insertme.pdf}

For full functionality, compile the output with pdflatex.

External Links

• Subfiles package documentation
• pdfpages package documentation