reftex: Reference Styles
3.6 Reference Styles
====================
In case you defined your own macros for referencing or you are using
LaTeX packages providing specialized macros to be used instead of
‘\ref’, RefTeX provides ways to select and insert them in a convenient
way.
RefTeX comes equipped with a set of so-called reference styles where
each relates to one or more reference macros. The standard macros
‘\ref’ and ‘\pageref’ or provided by the “Default” style. The
“Varioref” style offers macros for the ‘varioref’ LaTeX package
(‘\vref’, ‘\Vref’, ‘\Ref’, ‘\vpageref’), “Fancyref” for the ‘fancyref’
package (‘\fref’, ‘\Fref’) and “Hyperref” for the ‘hyperref’ package
(‘\autoref’, ‘\autopageref’).
A style can be toggled by selecting the respective entry in the
‘Reference Style’ menu. Changes made through the menu will only last
for the Emacs session. In order to configure a preference permanently,
the variable ‘reftex-ref-style-default-list’ should be customized. This
variable specifies the list of styles to be activated. It can also be
set as a file variable if the preference should be set for a specific
file.
In case the built-in styles do not suffice, you can add additional
macros and styles to the variable ‘reftex-ref-style-alist’. Those do
not necessarily have to be related to a certain LaTeX package but can
follow an arbitrary grouping rule. For example you could define a style
called “Personal” for your personal referencing macros. (When changing
the variable you should be aware that other Emacs packages, like AUCTeX,
might rely on the entries from the default value to be present.)
Once a style is active the macros it relates to are available for
selection when you are about to insert a reference. In general this
process involves three steps: the selection of a reference macro, a
label type and a label. Reference macros can be chosen in the first and
last step.
In the first step you will be presented with a list of macros from
which you can select one by typing a single key. If you dislike having
an extra step for reference macro selection, you can disable it by
customizing ‘reftex-ref-macro-prompt’ and relying only on the selection
facilities provided in the last step.
In the last step, i.e., the label selection, two key bindings are
provided to set the reference macro. Type <v> in order to cycle forward
through the list of available macros or <V> to cycle backward. The mode
line of the selection buffer shows the macro currently selected.
In case you are not satisfied with the order of macros when cycling
through them you should adapt the order of entries in the variable
‘reftex-ref-style-alist’ to fit your liking.
For each entry in ‘reftex-ref-style-alist’ a function with the name
‘reftex-<package>-<macro>’ (e.g., ‘reftex-varioref-vref’) will be
created automatically by RefTeX. These functions can be used instead of
‘C-c )’ and provide an alternative way of having your favorite
referencing macro preselected and if cycling through the macros seems
inconvenient to you.(1)
In former versions of RefTeX only support for ‘varioref’ and
‘fancyref’ was included. ‘varioref’ is a LaTeX package to create
cross-references with page information. ‘fancyref’ is a package where a
macro call like ‘\fref{FIG:MAP-OF-GERMANY}’ creates not only the number
of the referenced counter but also the complete text around it, like
‘Figure 3 on the preceding page’. In order to make it work you need to
use label prefixes like ‘fig:’ consistently—something RefTeX does
automatically. For each of these packages a variable could be
configured to make its macros to take precedence over ‘\ref’. Those
were ‘reftex-vref-is-default’ and ‘reftex-fref-is-default’ respectively.
While still working, these variables are deprecated now. Instead of
setting them, the variable ‘reftex-ref-style-default-list’ should be
adapted now.
---------- Footnotes ----------
(1) You could, e.g., bind ‘reftex-varioref-vref’ to ‘C-c v’ and
‘reftex-fancyref-fref’ to ‘C-c f’.
Info Catalog
reftex: Reference Info
reftex: Labels and References
reftex: LaTeX xr Package