5.2 Multifile Documents

You may wish to 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 Outline)). This can be done by having a “master" file in which 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 master file.

When you, for example, ask AUCTeX to run a command on the master file, it has no way of knowing the name of the master file. By default, it will assume that the current file is the master file. If you insert the following in your ‘.emacs’ file AUCTeX will use a more advanced algorithm.

(setq-default TeX-master nil) ; Query for master file. 

If AUCTeX finds the line indicating 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, AUCTeX will automatically insert the name of the master file as a file variable (see (emacs)File Variables 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: "master" %%% End: 

You should always set this variable to the name of the top level document. If you always use the same name for your top level documents, you can set TeX-master in your ‘.emacs’ file.

(setq-default TeX-master "master") ; All master files called "master". 

user option TeX-master

The master file associated with the current buffer. If the file being edited is actually included from another file, then you can tell AUCTeX 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, AUCTeX will query you for the name.

If the variable is t, then AUCTeX will assume the file is a master file itself.

If the variable is shared, then AUCTeX will query for the name, but will not change the file.

If the variable is dwim, AUCTeX will try to avoid querying by attempting to “do what I mean"; and then change the file.

user option TeX-one-master

Regular expression matching ordinary TeX files.

You should set this variable to match the name of all files, for which it is a good idea to append a TeX-master file variable entry automatically. When AUCTeX adds 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 AUCTeX automatically modifying your files, you can set this variable to ‘"<none>"’. By default, AUCTeX will modify any file with an extension of ‘.tex’.

command TeX-master-file-ask

(C-c _) Query for the name of a master file and add the respective File Variables (see (emacs)File Variables section ‘File Variables’ in The Emacs Editor) to the file for setting this variable permanently.

AUCTeX will not ask for a master file when it encounters existing files. This function shall give you the possibility to insert the variable manually.

AUCTeX keeps track of macros, environments, labels, and style files that are used in a given document. For this to work with multifile documents, AUCTeX 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, AUCTeX will write information about the file into the ‘auto’ directory. When you load a file, AUCTeX will 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, AUCTeX will get information from all files in the document. This means that you will get from each file, for example, completion for all labels defined anywhere in the document.

AUCTeX will create the ‘auto’ directory automatically if TeX-auto-save is non-nil. Without it, the files in the document will not know anything about each other, except for the name of the master file. See Automatic Local.

command TeX-save-document

(C-c C-d) Save all buffers known to belong to the current document.

user option TeX-save-query

If non-nil, then query the user before saving each file with TeX-save-document.