reftex-label-alist

reftex-label-alist is a variable defined in `reftex-vars.el'.
Its value is

nil

Documentation:
Alist with information on environments for \label-\ref use.

This doc string is easier to understand after reading the configuration
examples in the manual. Looking at the builtin defaults in the constant
`reftex-label-alist-builtin' may also be instructive.

Set this variable to define additions and changes to the default. The only
things you MUST NOT change is that `?s' is the type indicator for section
labels, and SPC for the `any' label type. These are hard-coded at other
places in the code.

The value of the variable must be a list of items. Each item is a list
itself and has the following structure:

(ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT CONTEXT-METHOD
(MAGIC-WORD ... ) TOC-LEVEL)

Each list entry describes either an environment carrying a counter for use
with \label and \ref, or a LaTeX macro defining a label as (or inside)
one of its arguments. The elements of each list entry are:

ENV-OR-MACRO
Name of the environment (like "table") or macro (like "\\myfig").
For macros, indicate the macro arguments for best results, as in
"\\myfig[]{}{}{*}{}". Use square brackets for optional arguments,
a star to mark the label argument, if any. The macro does not have to
have a label argument - you could also use \label{..} inside one of
its arguments.
Special names: `section' for section labels, `any' to define a group
which contains all labels.

This may also be a function to do local parsing and identify point to
be in a non-standard label environment. The function must take an
argument BOUND and limit backward searches to this value. It should
return either nil or the position where the special environment starts.
See the Info documentation for an example.

Finally this may also be nil if the entry is only meant to change
some settings associated with the type indicator character (see below).

TYPE-KEY
Type indicator character, like `?t', must be a printable ASCII character.
The type indicator is a single character which defines a label type.
Any label inside the environment or macro is assumed to belong to this
type. The same character may occur several times in this list, to cover
cases in which different environments carry the same label type (like
`equation' and `eqnarray').
If the type indicator is nil and the macro has a label argument {*},
the macro defines neutral labels just like \label. In this case
the remainder of this entry is ignored.

LABEL-PREFIX
Label prefix string, like "tab:".
The prefix is a short string used as the start of a label. It may be the
empty string. The prefix may contain the following `%' escapes:
%f Current file name with directory and extension stripped.
%F Current file name relative to directory of master file.
%m Master file name, directory and extension stripped.
%M Directory name (without path) where master file is located.
%u User login name, on systems which support this.
%S A section prefix derived with variable `reftex-section-prefixes'.

Example: In a file `intro.tex', "eq:%f:" will become "eq:intro:").

REFERENCE-FORMAT
Format string for reference insertion in buffer. `%s' will be replaced
by the label.
When the format starts with `~', the `~' will only be inserted if
there is not already a whitespace before point.

CONTEXT-METHOD
Indication on how to find the short context.
- If nil, use the text following the \label{...} macro.
- If t, use
- the section heading for section labels.
- text following the \begin{...} statement of environments.
(not a good choice for environments like eqnarray or enumerate,
where one has several labels in a single environment).
- text after the macro name (starting with the first arg) for macros.
- If an integer, use the nth argument of the macro. As a special case,
1000 means to get text after the last macro argument.
- If a string, use as regexp to search *backward* from the label. Context
is then the text following the end of the match. E.g. setting this to
"\\\\caption[[{]" will use the caption in a figure or table
environment.
"\\\\begin{eqnarray}\\|\\\\\\\\" works for eqnarrays.
- If any of `caption', `item', `eqnarray-like', `alignat-like', this
symbol will internally be translated into an appropriate regexp
(see also the variable `reftex-default-context-regexps').
- If a function, call this function with the name of the environment/macro
as argument. On call, point will be just after the \label macro. The
function is expected to return a suitable context string. It should
throw an exception (error) when failing to find context.
As an example, here is a function returning the 10 chars following
the label macro as context:

(defun my-context-function (env-or-mac)
(if (> (point-max) (+ 10 (point)))
(buffer-substring (point) (+ 10 (point)))
(error "Buffer too small")))

Label context is used in two ways by RefTeX: For display in the label
menu, and to derive a label string. If you want to use a different
method for each of these, specify them as a dotted pair.
E.g. `(nil . t)' uses the text after the label (nil) for display, and
text from the default position (t) to derive a label string. This is
actually used for section labels.

MAGIC-WORDS
List of magic words which identify a reference to be of this type.
If the word before point is equal to one of these words when calling
`reftex-reference', the label list offered will be automatically
restricted to labels of the correct type.
If the first element of this wordlist is the symbol `regexp', the
strings are interpreted as regular expressions. RefTeX will add
a "\\W" to the beginning and other stuff to the end of the regexp.

TOC-LEVEL
The integer level at which this environment should be added to the
table of contents. See also `reftex-section-levels'. A positive
value will number the entries mixed with the sectioning commands of
the same level. A negative value will make unnumbered entries.
Useful only for theorem-like environments, will be ignored for macros.
When omitted or nil, no TOC entries will be made.

If the type indicator characters of two or more entries are the same, RefTeX
will use
- the first non-nil format and prefix
- the magic words of all involved entries.

Any list entry may also be a symbol. If that has an association in
`reftex-label-alist-builtin', the cddr of that association is spliced into the
list. However, builtin defaults should normally be set with the variable
`reftex-default-label-alist-entries'.

You can customize this variable.