Default label alist specifications. It is a list of symbols with
associations in the constant reftex-label-alist-builtin.
LaTeX should always be the last entry.
Set this variable to define additions and changes to the defaults in
reftex-default-label-alist-entries. 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:
Name of the environment (like ‘table’) or macro (like ‘\myfig’). For macros, indicate the arguments, 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 a cons cell (function
. position) with the function symbol and 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 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 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, directory and extension stripped.
%F Current file name relative to master file directory.
%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:’.
Format string for reference insertion in buffer. ‘%s’ will be replaced by the label. When the format starts with ‘~’, this ‘~’ will only be inserted when the character before point is not a whitespace.
Indication on how to find the short context.
nil, use the text following the ‘\label{...}’ macro.
t, use
caption, item, eqnarray-like,
alignat-like, this symbol will internally be translated into an
appropriate regexp (see also the variable
reftex-default-context-regexps).
\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.
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
word list is the symbol regexp, the strings are interpreted as regular
expressions.
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 which structure the document. 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
nil format and prefix
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.
Prefixes for section labels. When the label prefix given in an entry in
reftex-label-alist contains ‘%S’, this list is used to
determine the correct prefix string depending on the current section
level. The list is an alist, with each entry of the form
(key . prefix). Possible keys are sectioning macro
names like ‘chapter’, integer section levels (as given in
reftex-section-levels), and t for the default.
Alist with default regular expressions for finding context. The emacs
lisp form (format regexp (regexp-quote environment)) is used
to calculate the final regular expression, so ‘%s’ will be
replaced with the environment or macro.
Non-nil means, trust the label prefix when determining label type.
It is customary to use special label prefixes to distinguish different label
types. The label prefixes have no syntactic meaning in LaTeX (unless
special packages like fancyref) are being used. RefTeX can and by
default does parse around each label to detect the correct label type,
but this process can be slow when a document contains thousands of
labels. If you use label prefixes consistently, you may speed up
document parsing by setting this variable to a non-nil value. RefTeX
will then compare the label prefix with the prefixes found in
reftex-label-alist and derive the correct label type in this way.
Possible values for this option are:
t This means to trust any label prefixes found. regexp If a regexp, only prefixes matched by the regexp are trusted. list List of accepted prefixes, as strings. The colon is part of the prefix, e.g., ("fn:" "eqn:" "item:"). nil Never trust a label prefix.
The only disadvantage of using this feature is that the label context displayed in the label selection buffer along with each label is simply some text after the label definition. This is no problem if you place labels keeping this in mind (e.g., before the equation, at the beginning of a fig/tab caption ...). Anyway, it is probably best to use the regexp or the list value types to fine-tune this feature. For example, if your document contains thousands of footnotes with labels fn:xxx, you may want to set this variable to the value "^fn:$" or ("fn:"). Then RefTeX will still do extensive parsing for any non-footnote labels.