Multifile Documents

If you spread a document over many files (as you are likely to do if there are multiple authors, or if you have not yet discovered the power of the outline commands (see section Outlining the Document)), that can be done by having a "master" file from where you include the various files with the TeX macro `\input' or the LaTeX macro `\include'. These files may also include other files themselves. However, to format the document you must run the commands on the top level file.

When you for example ask AUC TeX to run a command on the master file, it has no way to know what the name of the master file is. If it find the line indication the end of the header in a master file (`TeX-header-end`), it can figure out for itself that this is a master file. Otherwise, it will ask for the name of the master file associated with the buffer. To avoid asking you again, AUC TeX will automatically insert the name of the master file as a file variable (see section `File Variables' in The Emacs Editor). You can also insert the file variable yourself, by putting the following text at the end of your files.

```% Local Variables:
% TeX-master: "mymaster"
% End:
```

You should always set this variable to the top level document.

User Option: TeX-master

The master file associated with the current buffer. If the file being edited is actually included from another file, you can tell AUC TeX the name of the master file by setting this variable. If there are multiple levels of nesting, specify the top level file.

If this variable is `nil`, AUC TeX will query you for the name.

If the variable is `t`, AUC TeX will assume the file is a master file itself.

If the variable is `'shared`, AUC TeX will query for the name, but not change the file.

It is suggested that you use the File Variables (see section `File Variables' in The Emacs Editor) to set this variable permanently for each file.

User Option: TeX-one-master

Regular expression matching ordinary TeX files.

You should set this variable to match the name of all files, where automatically adding a file variable with the name of the master file is a good idea. When AUC TeX add the name of the master file as a file variable, it does not need to ask next time you edit the file.

If you dislike AUC TeX automatically modifying your files, you can set this variable to `"<none>"'. By default, AUC TeX will modify any file with an extension of `.tex'.

AUC TeX keeps track of what macros, environments, labels, and style files that are used in a given document. For this to work with multifile documents, AUC TeX has to have a place to put the information about the files in the document. This is done by having an `auto' subdirectory placed in the directory where your document is located. Each time you save a file, AUC TeX will write information about the file into the `auto' directory. When you load a file, AUC TeX will then read the information in the `auto' directory about the file you loaded, and the master file specified by `TeX-master`. Since the master file (perhaps indirectly) includes all other files in the document, AUC TeX will get information from all files in the document. This means that you from each file will get e.g. completion for all labels defined anywhere in the document.

You must create the `auto' directory manually for this to work. If you don't do this, the other files in the document will not know anything about each other, except for the name of the master file. See section Automatic Customization for a Directory.