auctex: Multifile
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 (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
((emacs)File Variables). 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 ((emacs)File Variables) 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. 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'.