Next: Appendices, Previous: Processing, Up: top [Contents][Index]
| • Modes and Hooks | Modes and Hooks | |
| • Multifile | Multifile Documents | |
| • Parsing Files | Automatic Parsing of TeX Files | |
| • Internationalization | Language Support | |
| • Automatic | Automatic Customization | |
| • Style Files | Writing Your Own Style Support |
Next: Multifile, Up: Customization [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.
Other useful hooks are listed below.
Hook which is run after the TeX/LaTeX processor has successfully finished compiling your document. (See Processing, for finding out how to compile your document). Each function in the hook is run with the compiled output document as its argument.
This is useful for automatically refreshing the viewer after
re-compilation especially when using Emacs viewers such as DocView or
PDF Tools. The function TeX-revert-document-buffer can be added
to the hook for this purpose.
Next: Parsing Files, Previous: Modes and Hooks, Up: Customization [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 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 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.
If the variable is dwim, AUCTeX will try to avoid querying by
attempting to “do what I mean”; and then 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 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.
(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.
Next: Internationalization, Previous: Multifile, Up: Customization [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 Automatic Local. 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 Multifile, 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.
Only parse LaTeX index and glossary entries.
Only parse macros in LaTeX classes and packages.
Only parse LaTeX pagestyles.
Only parse LaTeX counters.
Only parse LaTeX lengths.
Only parse LaTeX saveboxes.
Parse common LaTeX commands.
Parse common plain TeX commands.
Parse all TeX and LaTeX commands that AUCTeX can use.
Next: Automatic, Previous: Parsing Files, Up: Customization [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.
All Emacs versions supported by current AUCTeX can handle CJK languages by default.
In most cases, special versions of TeX engines are needed for high-quality typesetting of CJK languages: CTeX and ChinaTeX for Chinese, ASCII pTeX, upTeX and NTT jTeX for Japanese, HLaTeX and kTeX for Korean. They are necessary as well when you want to typeset documents saved in their domestic encodings such as Shift-JIS. Currently, AUCTeX offers native support for pTeX, upTeX and jTeX only.
If you don’t need fine tuning in the result with respect to the typesetting rules of their respective national standards, most unicode based TeX engines e.g. LuaTeX and XeTeX can handle CJK languages by default if they are encoded in UTF-8. The CJK-LaTeX package is provided for supporting CJK scripts in a standard LaTeX document.
| • European | Using AUCTeX with European Languages | |
| • Japanese | Using AUCTeX with Japanese |
Next: Japanese, Up: Internationalization [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. 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.
a much more complete package for Emacs that can also handle a lot of mathematical characters and input methods.
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 Parsing 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-en-hook.
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-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-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.
Previous: European, Up: Internationalization [Contents][Index]
To write Japanese text with AUCTeX, you need the versions of TeX and Emacs that support Japanese. AUCTeX supports three Japanese TeX engines by default: NTT jTeX, ASCII pTeX and upTeX.
To use the Japanese TeX engines, activate
japanese-plain-tex-mode or japanese-latex-mode. If it
doesn’t work, send mail to Masayuki Ataka
‘<masayuki.ataka@gmail.com>’ or Ikumi Keita
‘<ikumikeita@jcom.home.ne.jp>’, who currently concern with
stuff related to Japanese in AUCTeX. None of the primary AUCTeX
maintainers understand Japanese, so they cannot help you.
It is recommended to enable TeX-parse-self for typical Japanese
LaTeX users. When enabled, japanese-latex-mode selects the
suitable Japanese TeX engine automatically based on the class file
name (such as jbook, jsarticle and tjreport) and
its option. see Parsing Files.
It is important to select the suitable Japanese TeX engine because
the selected engine determines the command name such as ‘platex’
and ‘uptex’ to typeset the document. If you find that wrong
command is used, check the value of TeX-engine on that buffer.
If the value does not suit the current document, change the value by the
‘TeXing Options’ submenu below the ‘Command’ menu.
see Processor Options.
To make the selected engine to persist across Emacs sessions, there are two ways from which you can choose one according to your needs:
japanese-TeX-engine-default.
The default TeX engine in Japanese TeX mode.
The default value is ‘ptex’.
TeX-engine.
Here is a sample code to set TeX-engine to ‘uptex’:
%%% Local Variables: %%% mode: japanese-latex %%% TeX-engine: uptex %%% End:
In the both cases above, the valid value is one of ‘ptex’, ‘jtex’ and ‘uptex’.
You can override the command names associated with the above three
engines or define your own engine by customizing
TeX-engine-alist. See Processor Options.
It is sometimes necessary to use an engine which differs from the one
AUCTeX selects automatically. For example, even when you want to use
j-article document class deliberately with ASCII pLaTeX,
AUCTeX selects NTT jLaTeX command if TeX-parse-self is
enabled, because j-article originally belongs to NTT jLaTeX.
In such cases, use the file local variable method above to select the
engine you intend to use.
If you usually use AUCTeX in Japanese, setting the following variables is useful.
Mode to enter for a new file when it cannot 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 style/class when creating a new Japanese LaTeX document.
The default value is ‘"jarticle"’.
It is recommended also for Japanese users to customize the option
TeX-PDF-from-DVI to "Dvipdfmx". See Processor Options
There are three customize options with regard to the encoding of Japanese text.
If non-nil, AUCTeX adds -kanji option to the typesetting
command when TeX-engine is ‘ptex’.
Usually AUCTeX guesses the right coding systems for input to and output from the Japanese TeX process, but you can override them by the following two customize options.
If non-nil, used for encoding input to Japanese TeX process.
When nil, AUCTeX tries to choose suitable coding system.
If non-nil, used for decoding output from Japanese TeX process.
When nil, AUCTeX tries to choose suitable coding system.
The former customize options japanese-TeX-command-default,
japanese-LaTeX-command-default and
japanese-TeX-command-list are removed from AUCTeX. Use
japanese-TeX-engine-default instead. If you need to customize
the executable file name such as ‘"latex"’, the options for them,
or both, customize TeX-engine-alist.
The following two additional font commands are available in LaTeX mode buffer.
Insert gothic face font command ‘\textgt{∗}’ or ‘\mathgt{∗}’ depending on the context.
Insert mincho font command ‘\textmc{∗}’ or ‘\mathmc{∗}’ depending on the context.
Although they are meaningful only with ‘ptex’ and ‘uptex’ engines, it won’t matter in buffers with other engines.
See tex-jp.el for more information.
Next: Style Files, Previous: Internationalization, Up: Customization [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.
| • Automatic Global | Automatic Customization for the Site | |
| • Automatic Private | Automatic Customization for a User | |
| • Automatic Local | 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.
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 named ., .., 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.
Next: Automatic Private, Up: Automatic [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.
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.
Next: Automatic Local, Previous: Automatic Global, Up: Automatic [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.
Previous: Automatic Private, Up: Automatic [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
exists. 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.
These correspond to TeX macros found in the current directory.
Directory containing automatically generated TeX information.
These correspond to TeX macros found in the current directory.
Previous: Automatic, Up: Customization [Contents][Index]
See Automatic, 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.
| • Simple Style | A Simple Style File | |
| • Adding Macros | Adding Support for Macros | |
| • Adding Environments | Adding Support for Environments | |
| • Adding Other | Adding Other Information | |
| • Hacking the Parser | Automatic Extraction of New Things |
If you write some useful support for a public TeX style file, please send it to us.
Next: Adding Macros, Up: Style Files [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")) LaTeX-dialect)
The example is from the AUCTeX sources and is loaded for any LaTeX
document using the book document class (or style before LaTeX2e).
The file specifies that the largest kind of section in such a document
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 are executed. The actual files will only be evaluated once, but the hooks will be called for each buffer using the style file.
Note that the basename of the style file and the name of the style hook should usually be identical.
Add hook to the list of functions to run when we use the TeX file style and the current dialect is one in the set derived from dialect-expr. When dialect-expr is omitted, then hook is allowed to be run whatever the current dialect is.
dialect-expr may be one of:
:latexFor all files in LaTeX mode, or any mode derived thereof.
:bibtexFor all files in BibTeX mode, or any mode derived thereof.
:texinfoFor all files in Texinfo mode.
:plain-texFor all files in plain-TeX mode, or any mode derived thereof.
:contextFor all files in ConTeXt mode.
:classoptFor class options of LaTeX document. This is provided as pseudo-dialect for style hooks associated with class options.
(or dialect-expression1 … dialect-expression_n)For union of the sets of dialects corresponding to dialect-expression1 through dialect-expression_n
(and dialect-expression1 … dialect-expression_n)For intersection of the sets of dialects corresponding to dialect-expression1 through dialect-expression_n
(nor dialect-expression1 … dialect-expression_n)For complement of the union sets of dialects corresponding to dialect-expression1 through dialect-expression_n relatively to the set of all supported dialects
(not dialect-expr)For complement set of dialect corresponding to dialect-expr relatively to the set of all supported dialects
In case of adding a style hook for LaTeX, when calling function
TeX-add-style-hook it is thought more futureproof for argument
dialect-expr to pass constant LaTeX-dialect currently
defined to :latex, rather than passing :latex directly.
Default dialect for use with function TeX-add-style-hook for
argument dialect-expr when the hook is to be run only on LaTeX
file, or any mode derived thereof.
Next: Adding Environments, Previous: Simple Style, Up: Style Files [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-ref)
'("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 choose 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-ref 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:
stringUse the string as a prompt to prompt for the argument.
numberInsert that many braces, leave point inside the first. 0 and -1 are special. 0 means that no braces are inserted. -1 means that braces are inserted around the macro and an active region (e.g. ‘{\tiny foo}’). If there is no active region, no braces are inserted.
nilInsert empty braces.
tInsert empty braces, leave point between the braces.
other symbolsCall the symbol as a function. You can define your own hook, or use one of the predefined argument hooks.
listIf 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.
vectorOptional 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. If RefTeX is active, prompt for the reference format.
TeX-arg-ref
Prompt for a label completing with known labels. If RefTeX is
active, do not prompt for the reference format. Usually, reference
macros should use this function instead of TeX-arg-label.
TeX-arg-index-tag
Prompt for an index tag. This is the name of an index, not the entry.
TeX-arg-index
Prompt for an index entry completing with known entries.
TeX-arg-length
Prompt for a LaTeX length completing with known lengths.
TeX-arg-macro
Prompt for a TeX macro with completion.
TeX-arg-date
Prompt for a date, defaulting to the current date. The format of the
date is specified by the TeX-date-format option. If you want to
change the format when the ‘babel’ package is loaded with a
specific language, set TeX-date-format inside the appropriate
language hook, for details see European.
TeX-arg-version
Prompt for the version of a file, using as initial input the current date.
TeX-arg-environment
Prompt for a LaTeX environment with completion.
TeX-arg-cite
Prompt for a BibTeX citation. If the variable
TeX-arg-cite-note-p is non-nil, ask also for optional note in citations.
TeX-arg-counter
Prompt for a LaTeX counter completing with known counters.
TeX-arg-savebox
Prompt for a LaTeX savebox completing with known saveboxes.
TeX-arg-file
Prompt for a filename in the current directory, and use it with the extension.
TeX-arg-file-name
Prompt for a filename and use as initial input the name of the file being visited in the current buffer, with extension.
TeX-arg-file-name-sans-extension
Prompt for a filename and use as initial input the name of the file being visited in the current buffer, without 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. (Note that
the behavior (type of prompt and inserted file name) of the function can
be controlled by the variable TeX-arg-input-file-search.)
TeX-arg-define-label
Prompt for a label completing with known labels. Add label to list of defined labels.
TeX-arg-define-length
Prompt for a LaTeX length completing with known lengths. Add length to list of defined lengths.
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-document
Prompt for a LaTeX document class, using LaTeX-default-style
as default value and LaTeX-default-options as default list of
options. If the variable TeX-arg-input-file-search is t, you
will be able to complete with all LaTeX classes available on your
system, otherwise classes listed in the variable LaTeX-style-list
will be used for completion. It is also provided completion for options
of many common classes.
LaTeX-arg-usepackage
Prompt for LaTeX packages. If the variable
TeX-arg-input-file-search is t, you will be able to complete with
all LaTeX packages available on your system. It is also provided
completion for options of many common packages.
TeX-arg-bibstyle
Prompt for a BibTeX style file completing with all style available on your system.
TeX-arg-bibliography
Prompt for BibTeX database files completing with all databases available on your system.
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-verb-delim-or-brace
Prompt for delimiter and text. This function is similar to
TeX-arg-verb, but is intended for macros which take their
argument enclosed in delimiters or in braces.
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.
LaTeX-arg-author
Prompt for document author, using LaTeX-default-author as initial
input.
TeX-read-key-val
Prompt for a key=value list of options and return them.
TeX-arg-key-val
Prompt for a key=value list of options and insert it as a TeX macro argument.
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.
Some packages provide macros that are rarely useful to non-expert users.
Those should be marked as expert macros using
TeX-declare-expert-macros.
Declare MACROS as expert macros of STYLE.
Expert macros are completed depending on ‘TeX-complete-expert-commands’.
Next: Adding Other, Previous: Adding Macros, Up: Style Files [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]))
Some packages provide environments that are rarely useful to non-expert
users. Those should be marked as expert environments using
LaTeX-declare-expert-environments.
Declare ENVIRONMENTS as expert environments of STYLE.
Expert environments are completed depending on ‘TeX-complete-expert-commands’.
Next: Hacking the Parser, Previous: Adding Environments, Up: Style Files [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.
Previous: Adding Other, Up: Style Files [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.
Previous: Adding Other, Up: Style Files [Contents][Index]