reftex: Options - Defining Label Environments
18.2 Defining Label Environments
================================
-- User Option: reftex-default-label-alist-entries
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.
-- User Option: reftex-label-alist
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:
ENV-OR-MACRO
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-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, 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:’.
REFERENCE-FORMAT
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.
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-WORD-LIST
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.
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 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
− 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’.
-- User Option: reftex-section-prefixes
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.
-- User Option: reftex-default-context-regexps
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.
-- User Option: reftex-trust-label-prefix
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.
Info Catalog
reftex: Options - Table of Contents
reftex: Options
reftex: Options - Creating Labels