[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
5.1 Modes and Hooks | ||
5.2 Multifile Documents | ||
5.3 Automatic Parsing of TeX Files | ||
5.4 Language Support | ||
5.5 Automatic Customization | ||
5.6 Writing Your Own Style Support |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX supports a wide variety of derivatives and extensions of
TeX. Besides plain TeX those are LaTeX, AMS-TeX,
ConTeXt, Texinfo and docTeX. For each of them there is a separate
major mode in AUCTeX and each major mode runs text-mode-hook
,
TeX-mode-hook
as well as a hook special to the mode in this
order. The following table provides an overview of the respective mode
functions and hooks.
Type | Mode function | Hook |
---|---|---|
Plain TeX | plain-TeX-mode | plain-TeX-mode-hook |
LaTeX | LaTeX-mode | LaTeX-mode-hook |
AMS-TeX | ams-tex-mode | AmS-TeX-mode-hook |
ConTeXt | ConTeXt-mode | ConTeXt-mode-hook |
Texinfo | Texinfo-mode | Texinfo-mode-hook |
DocTeX | docTeX-mode | docTeX-mode-hook |
If you need to make a customization via a hook which is only relevant
for one of the modes listed above, put it into the respective mode hook,
if it is relevant for any AUCTeX mode, add it to TeX-mode-hook
and if it is relevant for all text modes, append it to
text-mode-hook
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section Outlining the Document)). 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". |
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.
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’.
(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 section Automatic Customization for a Directory.
(C-c C-d) Save all buffers known to belong to the current document.
If non-nil, then query the user before saving each file with
TeX-save-document
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX depends heavily on being able to extract information from the buffers by parsing them. Since parsing the buffer can be somewhat slow, the parsing is initially disabled. You are encouraged to enable them by adding the following lines to your ‘.emacs’ file.
(setq TeX-parse-self t) ; Enable parse on load. (setq TeX-auto-save t) ; Enable parse on save. |
The latter command will make AUCTeX store the parsed information in an ‘auto’ subdirectory in the directory each time the TeX files are stored, see section Automatic Customization for a Directory. If AUCTeX finds the pre-parsed information when loading a file, it will not need to reparse the buffer. The information in the ‘auto’ directory is also useful for multifile documents, see section Multifile Documents, since it allows each file to access the parsed information from all the other files in the document. This is done by first reading the information from the master file, and then recursively the information from each file stored in the master file.
The variables can also be done on a per file basis, by changing the file local variables.
%%% Local Variables: %%% TeX-parse-self: t %%% TeX-auto-save: t %%% End: |
Even when you have disabled the automatic parsing, you can force the generation of style information by pressing C-c C-n. This is often the best choice, as you will be able to decide when it is necessary to reparse the file.
Parse file after loading it if no style hook is found for it.
Automatically save style information when saving the buffer.
(C-c C-n) Remove all information about this buffer, and apply the style hooks again. Save buffer first including style information. With optional argument, also reload the style hooks.
When AUCTeX saves your buffer, it can optionally convert all tabs in your buffer into spaces. Tabs confuse AUCTeX’s error message parsing and so should generally be avoided. However, tabs are significant in some environments, and so by default AUCTeX does not remove them. To convert tabs to spaces when saving a buffer, insert the following in your ‘.emacs’ file:
(setq TeX-auto-untabify t) |
Automatically remove all tabs from a file before saving it.
Instead of disabling the parsing entirely, you can also speed it
significantly up by limiting the information it will search for (and
store) when parsing the buffer. You can do this by setting the default
values for the buffer local variables TeX-auto-regexp-list
and
TeX-auto-parse-length
in your ‘.emacs’ file.
;; Only parse LaTeX class and package information. (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list) ;; The class and package information is usually near the beginning. (setq-default TeX-auto-parse-length 2000) |
This example will speed the parsing up significantly, but AUCTeX will no longer be able to provide completion for labels, macros, environments, or bibitems specified in the document, nor will it know what files belong to the document.
These variables can also be specified on a per file basis, by changing the file local variables.
%%% Local Variables: %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list %%% TeX-auto-parse-length: 999999 %%% End: |
List of regular expressions used for parsing the current file.
Maximal length of TeX file that will be parsed.
The pre-specified lists of regexps are defined below. You can use these before loading AUCTeX by quoting them, as in the example above.
Parse nothing
Only parse LaTeX class and packages.
Only parse LaTeX labels.
Parse common LaTeX commands.
Parse common plain TeX commands.
Parse all TeX and LaTeX commands that AUCTeX can use.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
TeX and Emacs are usable for European (Latin, Cyrillic, Greek) based languages. Some LaTeX and EmacsLisp packages are available for easy typesetting and editing documents in European languages.
For CJK (Chinese, Japanese, and Korean) languages, Emacs or XEmacs with MULE (MULtilingual Enhancement to GNU Emacs) support is required. MULE is part of Emacs by default since Emacs 20. XEmacs has to be configured with the ‘--with-mule’ option. Special versions of TeX are needed for CJK languages: CTeX and ChinaTeX for Chinese, ASCII pTeX and NTT jTeX for Japanese, HLaTeX and kTeX for Korean. The CJK-LaTeX package is required for supporting multiple CJK scripts within a single document.
Note that Unicode is not fully supported in Emacs 21 and XEmacs 21. CJK characters are not usable. Please use the MULE-UCS EmacsLisp package or Emacs 22 (not released yet) if you need CJK.
5.4.1 Using AUCTeX with European Languages | ||
5.4.2 Using AUCTeX with Japanese TeX | Using AUCTeX with Japanese |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
First you will need a way to write non-ASCII characters. You can either use macros, or teach TeX about the ISO character sets. I prefer the latter, it has the advantage that the usual standard emacs word movement and case change commands will work.
With LaTeX2e, just add ‘\usepackage[latin1]{inputenc}’. Other languages than Western European ones will probably have other encoding needs.
To be able to display non-ASCII characters you will need an appropriate font and a version of GNU Emacs capable of displaying 8-bit characters (e.g. Emacs 21). The manner in which this is supported differs between Emacsen, so you need to take a look at your respective documentation.
A compromise is to use an European character set when editing the file, and convert to TeX macros when reading and writing the files.
Much like ‘iso-tex.el’ but is bundled with Emacs 19.23 and later.
Similar package bundled with new versions of XEmacs.
a much more complete package for both Emacs and XEmacs that can also handle a lot of mathematical characters and input methods.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX supports style files for several languages. Each style file may modify AUCTeX to better support the language, and will run a language specific hook that will allow you to for example change ispell dictionary, or run code to change the keyboard remapping. The following will for example choose a Danish dictionary for documents including ‘\usepackage[danish]{babel}’. This requires parsing to be enabled, see section Automatic Parsing of TeX Files.
(add-hook 'TeX-language-dk-hook (lambda () (ispell-change-dictionary "danish"))) |
The following style files are recognized:
Runs style hook TeX-language-bg-hook
. Gives ‘"’ word
syntax, makes the <"> key insert a literal ‘"’. Typing <">
twice will insert insert ‘"`’ or ‘"'’ depending on context.
Typing <-> twice will insert ‘"=’, three times ‘--’.
Runs style hook TeX-language-cz-hook
. Pressing <"> will
insert ‘\uv{’ and ‘}’ depending on context.
Runs style hook TeX-language-dk-hook
. Pressing <"> will
insert ‘"`’ and ‘"'’ depending on context. Typing <->
twice will insert ‘"=’, i.e. a hyphen string allowing hyphenation
in the composing words.
Runs style hook TeX-language-nl-hook
.
Runs style hook TeX-language-de-hook
. Gives ‘"’ word
syntax, makes the <"> key insert a literal ‘"’. Pressing the
key twice will give you opening or closing German quotes (‘"`’ or
‘"'’). Typing <-> twice will insert ‘"=’, three times
‘--’.
Runs style hook TeX-language-fr-hook
. Pressing <"> will
insert ‘\\og’ and ‘\\fg’ depending on context. Note that the
language name for customizing TeX-quote-language-alist
is
‘french’.
Runs style hook TeX-language-is-hook
. Gives ‘"’ word
syntax, makes the <"> key insert a literal ‘"’. Typing <">
twice will insert insert ‘"`’ or ‘"'’ depending on context.
Typing <-> twice will insert ‘"=’, three times ‘--’.
Runs style hook TeX-language-it-hook
. Pressing <"> will
insert ‘"<’ and ‘">’ depending on context.
Runs style hook TeX-language-pl-hook
. Gives ‘"’ word syntax
and makes the <"> key insert a literal ‘"’. Pressing <">
twice will insert ‘"`’ or ‘"'’ depending on context.
Runs style hook TeX-language-pl-hook
. Makes the <"> key
insert a literal ‘"’. Pressing <"> twice will insert ‘,,’
or ‘''’ depending on context.
Runs style hook TeX-language-sk-hook
. Pressing <"> will
insert ‘\uv{’ and ‘}’ depending on context.
Runs style hook TeX-language-sv-hook
. Pressing <"> will
insert ‘''’. Typing <-> twice will insert ‘"=’, three
times ‘--’.
Replacement of language-specific hyphen strings like ‘"=’ with dashes does not require to type <-> three times in a row. You can put point after the hypen string anytime and trigger the replacement by typing <->.
In case you are not satisfied with the suggested behavior of quote and
hyphen insertion you can change it by customizing the variables
TeX-quote-language-alist
and
LaTeX-babel-hyphen-language-alist
respectively.
Used for overriding the default language-specific quote insertion behavior. This is an alist where each element is a list consisting of four items. The first item is the name of the language in concern as a string. See the list of supported languages above. The second item is the opening quotation mark. The third item is the closing quotation mark. Opening and closing quotation marks can be specified directly as strings or as functions returning a string. The fourth item is a boolean controlling quote insertion. It should be non-nil if if the special quotes should only be used after inserting a literal ‘"’ character first, i.e. on second key press.
Used for overriding the behavior of hyphen insertion for specific languages. Every element in this alist is a list of three items. The first item should specify the affected language as a string. The second item denotes the hyphen string to be used as a string. The third item, a boolean, controls the behavior of hyphen insertion and should be non-nil if the special hyphen should be inserted after inserting a literal ‘-’ character, i.e. on second key press.
The defaults of hyphen insertion are defined by the variables
LaTeX-babel-hyphen
and LaTeX-babel-hyphen-after-hyphen
respectively.
String to be used when typing <->. This usually is a hyphen alternative or hyphenation aid provided by ‘babel’ and the related language style files, like ‘"=’, ‘"~’ or ‘"-’.
Set it to an empty string or nil in order to disable language-specific hyphen insertion.
Control insertion of hyphen strings. If non-nil insert normal hyphen on
first key press and swap it with the language-specific hyphen string
specified in the variable LaTeX-babel-hyphen
on second key press.
If nil do it the other way round.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To write Japanese text with AUCTeX, you need to have versions of TeX and Emacs that support Japanese. There exist at least two variants of TeX for Japanese text (NTT jTeX and ASCII pTeX). AUCTeX can be used with MULE (MULtilingual Enhancement to GNU Emacs) supported Emacsen.
To use the Japanese TeX variants, simply activate
japanese-plain-tex-mode
or japanese-latex-mode
and
everything should work. If not, send mail to Masayuki Ataka
‘<ataka@milk.freemail.ne.jp>’, who kindly donated the code for
supporting Japanese in AUCTeX. None of the primary AUCTeX
maintainers understand Japanese, so they cannot help you.
If you usually use AUCTeX in Japanese, setting the following variables is useful.
Mode to enter for a new file when it cannott be determined whether the file is plain TeX or LaTeX or what.
If you want to enter Japanese LaTeX mode whenever this may happen, set the variable like this:
(setq TeX-default-mode 'japanese-latex-mode) |
The default command for TeX-command
in Japanese TeX mode.
The default value is ‘"pTeX"’.
The default command for TeX-command
in Japanese LaTeX mode.
The default value is ‘"LaTeX"’.
The default style/class when creating a new Japanese LaTeX document.
The default value is ‘"jarticle"’.
See ‘tex-jp.el’ for more information.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since AUCTeX is so highly customizable, it makes sense that it is able to customize itself. The automatic customization consists of scanning TeX files and extracting symbols, environments, and things like that.
The automatic customization is done on three different levels. The global level is the level shared by all users at your site, and consists of scanning the standard TeX style files, and any extra styles added locally for all users on the site. The private level deals with those style files you have written for your own use, and use in different documents. You may have a ‘~/lib/TeX/’ directory where you store useful style files for your own use. The local level is for a specific directory, and deals with writing customization for the files for your normal TeX documents.
If compared with the environment variable TEXINPUTS
, the
global level corresponds to the directories built into TeX. The
private level corresponds to the directories you add yourself, except for
‘.’, which is the local level.
5.5.1 Automatic Customization for the Site | ||
5.5.2 Automatic Customization for a User | ||
5.5.3 Automatic Customization for a Directory |
By default AUCTeX will search for customization files in all the
global, private, and local style directories, but you can also set the
path directly. This is useful if you for example want to add another
person’s style hooks to your path. Please note that all matching files
found in TeX-style-path
are loaded, and all hooks defined in the
files will be executed.
List of directories to search for AUCTeX style files. Each must end with a slash.
By default, when AUCTeX searches a directory for files, it will recursively search through subdirectories.
Whether to search TeX directories recursively: nil means do not recurse, a positive integer means go that far deep in the directory hierarchy, t means recurse indefinitely.
By default, AUCTeX will ignore files name ‘.’, ‘..’, ‘SCCS’, ‘RCS’, and ‘CVS’.
Regular expression matching file names to ignore.
These files or directories will not be considered when searching for TeX files in a directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Assuming that the automatic customization at the global level was done when AUCTeX was installed, your choice is now: will you use it? If you use it, you will benefit by having access to all the symbols and environments available for completion purposes. The drawback is slower load time when you edit a new file and perhaps too many confusing symbols when you try to do a completion.
You can disable the automatic generated global style hooks by setting
the variable TeX-auto-global
to nil.
Directories containing the site’s TeX style files.
Directory containing hand generated TeX information. Must end with a slash.
These correspond to TeX macros shared by all users of a site.
Directory containing automatically generated information.
For storing automatic extracted information about the TeX macros shared by all users of a site.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You should specify where you store your private TeX macros, so
AUCTeX can extract their information. The extracted information will
go to the directories listed in TeX-auto-private
Use M-x TeX-auto-generate <RET> to extract the information.
Directories where you store your personal TeX macros. The value
defaults to the directories listed in the ‘TEXINPUTS’ and
‘BIBINPUTS’ environment variables or to the respective directories
in $TEXMFHOME
if no results can be obtained from the environment
variables.
List of directories containing automatically generated AUCTeX style files. These correspond to the personal TeX macros.
(M-x TeX-auto-generate <RET>) Generate style hook for TEX and store it in AUTO. If TEX is a directory, generate style hooks for all files in the directory.
List of directories containing hand generated AUCTeX style files. These correspond to the personal TeX macros.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX can update the style information about a file each time you
save it, and it will do this if the directory TeX-auto-local
exist. TeX-auto-local
is by default set to ‘"auto"’, so
simply creating an ‘auto’ directory will enable automatic saving of
style information.
The advantage of doing this is that macros, labels, etc. defined in any
file in a multifile document will be known in all the files in the
document. The disadvantage is that saving will be slower. To disable,
set TeX-auto-local
to nil.
Directory containing hand generated TeX information. Must end with a slash.
These correspond to TeX macros found in the current directory.
Directory containing automatically generated TeX information. Must end with a slash.
These correspond to TeX macros found in the current directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See section Automatic Customization, for a discussion about automatically generated global, private, and local style files. The hand generated style files are equivalent, except that they by default are found in ‘style’ directories instead of ‘auto’ directories.
5.6.1 A Simple Style File | ||
5.6.2 Adding Support for Macros | ||
5.6.3 Adding Support for Environments | ||
5.6.4 Adding Other Information | ||
5.6.5 Automatic Extraction of New Things |
If you write some useful support for a public TeX style file, please send it to us.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a simple example of a style file.
;;; book.el - Special code for book style. (TeX-add-style-hook "book" (lambda () (LaTeX-largest-level-set "chapter"))) |
This file specifies that the largest kind of section in a LaTeX document
using the book document style is chapter. The interesting thing to
notice is that the style file defines an (anonymous) function, and adds it
to the list of loaded style hooks by calling TeX-add-style-hook
.
The first time the user indirectly tries to access some style specific information, such as the largest sectioning command available, the style hooks for all files directly or indirectly read by the current document is executed. The actual files will only be evaluated once, but the hooks will be called for each buffer using the style file.
Add hook to the list of functions to run when we use the TeX file style.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The most common thing to define in a style hook is new symbols (TeX macros). Most likely along with a description of the arguments to the function, since the symbol itself can be defined automatically.
Here are a few examples from ‘latex.el’.
(TeX-add-style-hook "latex" (lambda () (TeX-add-symbols '("arabic" TeX-arg-counter) '("label" TeX-arg-define-label) '("ref" TeX-arg-label) '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t) '("newtheorem" TeX-arg-define-environment [ TeX-arg-environment "Numbered like" ] t [ TeX-arg-counter "Within counter" ])))) |
Add each symbol to the list of known symbols.
Each argument to TeX-add-symbols
is a list describing one symbol.
The head of the list is the name of the symbol, the remaining elements
describe each argument.
If there are no additional elements, the symbol will be inserted with point inside braces. Otherwise, each argument of this function should match an argument of the TeX macro. What is done depends on the argument type.
If a macro is defined multiple times, AUCTeX will chose the one with the longest definition (i.e. the one with the most arguments).
Thus, to overwrite
'("tref" 1) ; one argument |
you can specify
'("tref" TeX-arg-label ignore) ; two arguments |
ignore
is a function that does not do anything, so when you
insert a ‘tref’ you will be prompted for a label and no more.
You can use the following types of specifiers for arguments:
string
Use the string as a prompt to prompt for the argument.
number
Insert that many braces, leave point inside the first.
nil
Insert empty braces.
t
Insert empty braces, leave point between the braces.
other symbols
Call the symbol as a function. You can define your own hook, or use one of the predefined argument hooks.
list
If the car is a string, insert it as a prompt and the next element as initial input. Otherwise, call the car of the list with the remaining elements as arguments.
vector
Optional argument. If it has more than one element, parse it as a list, otherwise parse the only element as above. Use square brackets instead of curly braces, and is not inserted on empty user input.
A lot of argument hooks have already been defined. The first argument to all hooks is a flag indicating if it is an optional argument. It is up to the hook to determine what to do with the remaining arguments, if any. Typically the next argument is used to overwrite the default prompt.
TeX-arg-conditional
Implements if EXPR THEN ELSE. If EXPR evaluates to true, parse THEN as an argument list, else parse ELSE as an argument list.
TeX-arg-literal
Insert its arguments into the buffer. Used for specifying extra syntax for a macro.
TeX-arg-free
Parse its arguments but use no braces when they are inserted.
TeX-arg-eval
Evaluate arguments and insert the result in the buffer.
TeX-arg-label
Prompt for a label completing with known labels.
TeX-arg-macro
Prompt for a TeX macro with completion.
TeX-arg-environment
Prompt for a LaTeX environment with completion.
TeX-arg-cite
Prompt for a BibTeX citation.
TeX-arg-counter
Prompt for a LaTeX counter.
TeX-arg-savebox
Prompt for a LaTeX savebox.
TeX-arg-file
Prompt for a filename in the current directory, and use it without the extension.
TeX-arg-input-file
Prompt for the name of an input file in TeX’s search path, and use it without the extension. Run the style hooks for the file.
TeX-arg-define-label
Prompt for a label completing with known labels. Add label to list of defined labels.
TeX-arg-define-macro
Prompt for a TeX macro with completion. Add macro to list of defined macros.
TeX-arg-define-environment
Prompt for a LaTeX environment with completion. Add environment to list of defined environments.
TeX-arg-define-cite
Prompt for a BibTeX citation.
TeX-arg-define-counter
Prompt for a LaTeX counter.
TeX-arg-define-savebox
Prompt for a LaTeX savebox.
TeX-arg-corner
Prompt for a LaTeX side or corner position with completion.
TeX-arg-lr
Prompt for a LaTeX side with completion.
TeX-arg-tb
Prompt for a LaTeX side with completion.
TeX-arg-pagestyle
Prompt for a LaTeX pagestyle with completion.
TeX-arg-verb
Prompt for delimiter and text.
TeX-arg-pair
Insert a pair of numbers, use arguments for prompt. The numbers are surrounded by parentheses and separated with a comma.
TeX-arg-size
Insert width and height as a pair. No arguments.
TeX-arg-coordinate
Insert x and y coordinates as a pair. No arguments.
If you add new hooks, you can assume that point is placed directly after
the previous argument, or after the macro name if this is the first
argument. Please leave point located after the argument you are
inserting. If you want point to be located somewhere else after all
hooks have been processed, set the value of exit-mark
. It will
point nowhere, until the argument hook sets it.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Adding support for environments is very much like adding support for TeX macros, except that each environment normally only takes one argument, an environment hook. The example is again a short version of ‘latex.el’.
(TeX-add-style-hook "latex" (lambda () (LaTeX-add-environments '("document" LaTeX-env-document) '("enumerate" LaTeX-env-item) '("itemize" LaTeX-env-item) '("list" LaTeX-env-list)))) |
It is completely up to the environment hook to insert the environment,
but the function LaTeX-insert-environment
may be of some help.
The hook will be called with the name of the environment as its first
argument, and extra arguments can be provided by adding them to a list
after the hook.
For simple environments with arguments, for example defined with
‘\newenvironment’, you can make AUCTeX prompt for the arguments
by giving the prompt strings in the call to
LaTeX-add-environments
. The fact that an argument is optional
can be indicated by wrapping the prompt string in a vector.
For example, if you have defined a loop
environment with the
three arguments from, to, and step, you can add
support for them in a style file.
%% loop.sty \newenvironment{loop}[3]{...}{...} |
;; loop.el (TeX-add-style-hook "loop" (lambda () (LaTeX-add-environments '("loop" "From" "To" "Step")))) |
If an environment is defined multiple times, AUCTeX will choose the one with the longest definition. Thus, if you have an enumerate style file, and want it to replace the standard LaTeX enumerate hook above, you could define an ‘enumerate.el’ file as follows, and place it in the appropriate style directory.
(TeX-add-style-hook "latex" (lambda () (LaTeX-add-environments '("enumerate" LaTeX-env-enumerate foo)))) (defun LaTeX-env-enumerate (environment &optional ignore) ...) |
The symbol foo
will be passed to LaTeX-env-enumerate
as
the second argument, but since we only added it to overwrite the
definition in ‘latex.el’ it is just ignored.
Add each env to list of loaded environments.
Insert environment of type env, with optional argument extra.
Following is a list of available hooks for
LaTeX-add-environments
:
LaTeX-env-item
Insert the given environment and the first item.
LaTeX-env-figure
Insert the given figure-like environment with a caption and a label.
LaTeX-env-array
Insert the given array-like environment with position and column specifications.
LaTeX-env-label
Insert the given environment with a label.
LaTeX-env-list
Insert the given list-like environment, a specifier for the label and the first item.
LaTeX-env-minipage
Insert the given minipage-like environment with position and width specifications.
LaTeX-env-tabular*
Insert the given tabular*-like environment with width, position and column specifications.
LaTeX-env-picture
Insert the given environment with width and height specifications.
LaTeX-env-bib
Insert the given environment with a label for a bibitem.
LaTeX-env-contents
Insert the given environment with a filename as its argument.
LaTeX-env-args
Insert the given environment with arguments. You can use this as a hook
in case you want to specify multiple complex arguments just like in
elements of TeX-add-symbols
. This is most useful if the
specification of arguments to be prompted for with strings and strings
wrapped in a vector as described above is too limited.
Here is an example from ‘listings.el’ which calls a function with one argument in order to prompt for a key=value list to be inserted as an optional argument of the ‘lstlisting’ environment:
(LaTeX-add-environments `("lstlisting" LaTeX-env-args [TeX-arg-key-val ,LaTeX-listings-key-val-options])) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can also specify bibliographical databases and labels in the style file. This is probably of little use, since this information will usually be automatically generated from the TeX file anyway.
Add each bibliography to list of loaded bibliographies.
Add each label to the list of known labels.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The automatic TeX information extractor works by searching for regular expressions in the TeX files, and storing the matched information. You can add support for new constructs to the parser, something that is needed when you add new commands to define symbols.
For example, in the file ‘macro.tex’ I define the following macro.
\newcommand{\newmacro}[5]{% \def#1{#3\index{#4@#5~cite{#4}}\nocite{#4}}% \def#2{#5\index{#4@#5~cite{#4}}\nocite{#4}}% } |
AUCTeX will automatically figure out that ‘newmacro’ is a macro that takes five arguments. However, it is not smart enough to automatically see that each time we use the macro, two new macros are defined. We can specify this information in a style hook file.
;;; macro.el --- Special code for my own macro file. ;;; Code: (defvar TeX-newmacro-regexp '("\\\\newmacro{\\\\\\([a-zA-Z]+\\)}{\\\\\\([a-zA-Z]+\\)}" (1 2) TeX-auto-multi) "Matches \newmacro definitions.") (defvar TeX-auto-multi nil "Temporary for parsing \\newmacro definitions.") (defun TeX-macro-cleanup () "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'." (mapcar (lambda (list) (mapcar (lambda (symbol) (setq TeX-auto-symbol (cons symbol TeX-auto-symbol))) list)) TeX-auto-multi)) (defun TeX-macro-prepare () "Clear `Tex-auto-multi' before use." (setq TeX-auto-multi nil)) (add-hook 'TeX-auto-prepare-hook 'TeX-macro-prepare) (add-hook 'TeX-auto-cleanup-hook 'TeX-macro-cleanup) (TeX-add-style-hook "macro" (lambda () (TeX-auto-add-regexp TeX-newmacro-regexp) (TeX-add-symbols '("newmacro" TeX-arg-macro (TeX-arg-macro "Capitalized macro: \\") t "BibTeX entry: " nil)))) ;;; macro.el ends here |
When this file is first loaded, it adds a new entry to
TeX-newmacro-regexp
, and defines a function to be called before
the parsing starts, and one to be called after the parsing is done. It
also declares a variable to contain the data collected during parsing.
Finally, it adds a style hook which describes the ‘newmacro’ macro,
as we have seen it before.
So the general strategy is: Add a new entry to TeX-newmacro-regexp
.
Declare a variable to contain intermediate data during parsing. Add hook
to be called before and after parsing. In this case, the hook before
parsing just initializes the variable, and the hook after parsing
collects the data from the variable, and adds them to the list of symbols
found.
List of regular expressions matching TeX macro definitions.
The list has the following format ((REGEXP MATCH TABLE) …), that is, each entry is a list with three elements.
REGEXP. Regular expression matching the macro we want to parse.
MATCH. A number or list of numbers, each representing one parenthesized subexpression matched by REGEXP.
TABLE. The symbol table to store the data. This can be a function, in
which case the function is called with the argument MATCH. Use
TeX-match-buffer
to get match data. If it is not a function, it
is presumed to be the name of a variable containing a list of match
data. The matched data (a string if MATCH is a number, a list of
strings if MATCH is a list of numbers) is put in front of the table.
List of functions to be called before parsing a TeX file.
List of functions to be called after parsing a TeX file.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Build Daemon user on September 10, 2012 using texi2html 1.82.