Next: , Previous: , Up: top   [Contents][Index]

5 Customization and Extension


Next: , Up: Customization   [Contents][Index]

5.1 Modes and Hooks

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.

TypeMode functionHook
Plain TeXplain-TeX-modeplain-TeX-mode-hook
LaTeXLaTeX-modeLaTeX-mode-hook
AMS-TeXams-tex-modeAmS-TeX-mode-hook
ConTeXtConTeXt-modeConTeXt-mode-hook
TexinfoTexinfo-modeTexinfo-mode-hook
DocTeXdocTeX-modedocTeX-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.

Variable: TeX-after-compilation-finished-hook

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: , Previous: , Up: Customization   [Contents][Index]

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 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 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.


Next: , Previous: , Up: Customization   [Contents][Index]

5.3 Automatic Parsing of TeX Files

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.

User Option: TeX-parse-self

Parse file after loading it if no style hook is found for it.

User Option: TeX-auto-save

Automatically save style information when saving the buffer.

Command: TeX-normal-mode arg

(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)
User Option: TeX-auto-untabify

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:
User Option: TeX-auto-regexp-list

List of regular expressions used for parsing the current file.

User Option: TeX-auto-parse-length

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.

Constant: TeX-auto-empty-regexp-list

Parse nothing

Constant: LaTeX-auto-minimal-regexp-list

Only parse LaTeX class and packages.

Constant: LaTeX-auto-label-regexp-list

Only parse LaTeX labels.

Constant: LaTeX-auto-index-regexp-list

Only parse LaTeX index and glossary entries.

Constant: LaTeX-auto-class-regexp-list

Only parse macros in LaTeX classes and packages.

Constant: LaTeX-auto-pagestyle-regexp-list

Only parse LaTeX pagestyles.

Constant: LaTeX-auto-counter-regexp-list

Only parse LaTeX counters.

Constant: LaTeX-auto-length-regexp-list

Only parse LaTeX lengths.

Constant: LaTeX-auto-savebox-regexp-list

Only parse LaTeX saveboxes.

Constant: LaTeX-auto-regexp-list

Parse common LaTeX commands.

Constant: plain-TeX-auto-regexp-list

Parse common plain TeX commands.

Constant: TeX-auto-full-regexp-list

Parse all TeX and LaTeX commands that AUCTeX can use.


Next: , Previous: , Up: Customization   [Contents][Index]

5.4 Language Support

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.


Next: , Up: Internationalization   [Contents][Index]

5.4.1 Using AUCTeX with European Languages

5.4.1.1 Typing and Displaying Non-ASCII Characters

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.

iso-cvt.el

Much like iso-tex.el but is bundled with Emacs 19.23 and later.

X-Symbol

a much more complete package for Emacs that can also handle a lot of mathematical characters and input methods.

5.4.1.2 Style Files for Different Languages

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:

bulgarian

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 ‘--’.

czech

Runs style hook TeX-language-cz-hook. Pressing " will insert ‘\uv{’ and ‘}’ depending on context.

danish

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.

dutch

Runs style hook TeX-language-nl-hook.

english
australian
canadian
newzealand

Runs style hook TeX-language-en-hook.

frenchb
francais

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’.

german
ngerman

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 ‘--’.

icelandic

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 ‘--’.

italian

Runs style hook TeX-language-it-hook. Pressing " will insert ‘"<’ and ‘">’ depending on context.

polish

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.

polski

Runs style hook TeX-language-pl-hook. Makes the " key insert a literal ‘"’. Pressing " twice will insert ‘,,’ or ‘''’ depending on context.

slovak

Runs style hook TeX-language-sk-hook. Pressing " will insert ‘\uv{’ and ‘}’ depending on context.

swedish

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.

User Option: TeX-quote-language-alist

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.

User Option: LaTeX-babel-hyphen-language-alist

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.

User Option: LaTeX-babel-hyphen

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.

User Option: LaTeX-babel-hyphen-after-hyphen

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: , Up: Internationalization   [Contents][Index]

5.4.2 Using AUCTeX with Japanese TeX

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:

  1. If you use a specific engine (almost) exclusively, customize the option japanese-TeX-engine-default.
    User Option: japanese-TeX-engine-default

    The default TeX engine in Japanese TeX mode.

    The default value is ‘ptex’.

  2. If you want to set the engine on a per file basis, use the file local variables to set 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.

User Option: TeX-default-mode

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)
User Option: japanese-LaTeX-default-style

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.

User Option: japanese-TeX-use-kanji-opt-flag

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.

User Option: TeX-japanese-process-input-coding-system

If non-nil, used for encoding input to Japanese TeX process. When nil, AUCTeX tries to choose suitable coding system.

User Option: TeX-japanese-process-output-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.

C-c C-f g

Insert gothic face font command ‘\textgt{∗}’ or ‘\mathgt{∗}’ depending on the context.

C-c C-f m

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: , Previous: , Up: Customization   [Contents][Index]

5.5 Automatic Customization

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.

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.

User Option: TeX-style-path

List of directories to search for AUCTeX style files.

By default, when AUCTeX searches a directory for files, it will recursively search through subdirectories.

User Option: TeX-file-recurse

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.

User Option: TeX-ignore-file

Regular expression matching file names to ignore.

These files or directories will not be considered when searching for TeX files in a directory.


Next: , Up: Automatic   [Contents][Index]

5.5.1 Automatic Customization for the Site

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.

User Option: TeX-macro-global

Directories containing the site’s TeX style files.

User Option: TeX-style-global

Directory containing hand generated TeX information.

These correspond to TeX macros shared by all users of a site.

User Option: TeX-auto-global

Directory containing automatically generated information.

For storing automatic extracted information about the TeX macros shared by all users of a site.


Next: , Previous: , Up: Automatic   [Contents][Index]

5.5.2 Automatic Customization for a User

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.

User Option: TeX-macro-private

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.

User Option: TeX-auto-private

List of directories containing automatically generated AUCTeX style files. These correspond to the personal TeX macros.

Command: TeX-auto-generate TEX AUTO

(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.

User Option: TeX-style-private

List of directories containing hand generated AUCTeX style files. These correspond to the personal TeX macros.


Previous: , Up: Automatic   [Contents][Index]

5.5.3 Automatic Customization for a Directory

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.

User Option: TeX-style-local

Directory containing hand generated TeX information.

These correspond to TeX macros found in the current directory.

User Option: TeX-auto-local

Directory containing automatically generated TeX information.

These correspond to TeX macros found in the current directory.


Previous: , Up: Customization   [Contents][Index]

5.6 Writing Your Own Style Support

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.

If you write some useful support for a public TeX style file, please send it to us.


Next: , Up: Style Files   [Contents][Index]

5.6.1 A Simple Style File

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.

Function: TeX-add-style-hook style hook &optional dialect-expr

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:

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.

Constant: LaTeX-dialect

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: , Previous: , Up: Style Files   [Contents][Index]

5.6.2 Adding Support for Macros

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" ]))))
Function: TeX-add-symbols symbol

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:

string

Use the string as a prompt to prompt for the argument.

number

Insert 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.

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. 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.

Function: TeX-declare-expert-macros style macros...

Declare MACROS as expert macros of STYLE.

Expert macros are completed depending on ‘TeX-complete-expert-commands’.


Next: , Previous: , Up: Style Files   [Contents][Index]

5.6.3 Adding Support for Environments

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.

Function: LaTeX-add-environments env

Add each env to list of loaded environments.

Function: LaTeX-insert-environment env [ extra ]

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.

Function: LaTeX-declare-expert-environments style ENVIRONMENTS...

Declare ENVIRONMENTS as expert environments of STYLE.

Expert environments are completed depending on ‘TeX-complete-expert-commands’.


Next: , Previous: , Up: Style Files   [Contents][Index]

5.6.4 Adding Other Information

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.

Function: LaTeX-add-bibliographies bibliography

Add each bibliography to list of loaded bibliographies.

Function: LaTeX-add-labels label

Add each label to the list of known labels.


Previous: , Up: Style Files   [Contents][Index]

5.6.5 Automatic Extraction of New Things

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.

Variable: TeX-auto-regexp-list

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.

Variable: TeX-auto-prepare-hook nil

List of functions to be called before parsing a TeX file.

Variable: TeX-auto-cleanup-hook nil

List of functions to be called after parsing a TeX file.


Previous: , Up: Style Files   [Contents][Index]