12. Writing Your own Style Support

See section 11. 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.

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

12.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"
 (function (lambda () (setq LaTeX-largest-level
			    (LaTeX-section-level ("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.

Function: TeX-add-style-hook style hook

Add hook to the list of functions to run when we use the TeX file style.

12.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"
 (function
  (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" ])))))

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 chose the one with the longest definition (i.e. the one with the most arguments).

Thus, to overwrite

	'("tref" 1) ; one argument

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

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

Prompt for a tex or sty filename, and use it without the extension. Run the file hooks defined for it.

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 a filename in the current directory, 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.

12.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"
 (function
  (lambda ()
    (LaTeX-add-environments
     '("document" LaTeX-env-document)
     '("enumerate" LaTeX-env-item)
     '("itemize" LaTeX-env-item)
     '("list" LaTeX-env-list)))))

The only hook that is generally useful is LaTeX-env-item, which is used for environments that contain items. 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. 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"
 (function
  (lambda ()
    (LaTeX-add-environments
     '("loop" "From" "To" "Step")))))

If an environment is defined multiple times, AUCTeX will chose 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"
 (function
  (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.

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

12.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 (function (lambda (list)
	    (mapcar (function (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"
 (function
  (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.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.