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.(2)

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.

This document was generated by Ralf Angeli on August, 9 2009 using texi2html 1.78.