[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Viewing Cross--References

RefTeX can display cross--referencing information. This means, if two document locations are linked, RefTeX can display the matching location(s) in another window. The \label and \ref macros are one way of establishing such a link. Also, a \cite macro is linked to the corresponding \bibitem macro or a BibTeX database entry.

The feature is invoked by pressing C-c & (reftex-view-crossref) while point is on the key argument of a macro involved in cross--referencing. You can also click with S-mouse-2 on the macro argument. Here is what will happen for individual classes of macros:

Display the corresponding label definition. All usual variants(8) of the \ref macro are active for cross--reference display. This works also for labels defined in an external document when the current document refers to them through the xr interface (see section 3.6 xr: Cross-Document References).

Display a document location which references this label. Pressing C-c & several times moves through the entire document and finds all locations. Not only the \label macro but also other macros with label arguments (as configured with reftex-label-alist) are active for cross--reference display.

Display the corresponding BibTeX database entry or \bibitem. All usual variants(9) of the \cite macro are active for cross--reference display.

Display a document location which cites this article. Pressing C-c & several times moves through the entire document and finds all locations.

C-c & is also active in BibTeX buffers. All locations in a document where the database entry at point is cited will be displayed. On first use, RefTeX will prompt for a buffer which belongs to the document you want to search. Subsequent calls will use the same document, until you break this link with a prefix argument to C-c &.

Display other locations in the document which are marked by an index macro with the same key argument. Along with the standard \index and \glossary macros, all macros configured in reftex-index-macros will be recognized.

While the display of cross referencing information for the above mentioned macros is hard--coded, you can configure additional relations in the variable reftex-view-crossref-extra.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 RefTeX's Menu

RefTeX installs a Ref menu in the menu bar on systems which support this. From this menu you can access all of RefTeX's commands and a few of its options. There is also a Customize submenu which can be used to access RefTeX's entire set of options.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Default Key Bindings

Here is a summary of the available key bindings.

C-c =      reftex-toc
C-c -      reftex-toc-recenter
C-c (      reftex-label
C-c )      reftex-reference
C-c [      reftex-citation
C-c &      reftex-view-crossref
S-mouse-2  reftex-mouse-view-crossref
C-c /      reftex-index-selection-or-word
C-c \      reftex-index-phrase-selection-or-word
C-c |      reftex-index-visit-phrases-buffer
C-c <      reftex-index
C-c >      reftex-display-index

Note that the S-mouse-2 binding is only provided if this key is not already used by some other package. RefTeX will not override an existing binding to S-mouse-2.

Personally, I also bind some functions in the users C-c map for easier access.

C-c t    reftex-toc
C-c l    reftex-label
C-c r    reftex-reference
C-c c    reftex-citation
C-c v    reftex-view-crossref
C-c s    reftex-search-document
C-c g    reftex-grep-document

These keys are reserved for the user, so I cannot bind them by default. If you want to have these key bindings available, set in your `.emacs' file:

(setq reftex-extra-bindings t)

Changing and adding to RefTeX's key bindings is best done in the hook reftex-load-hook. For information on the keymaps which should be used to add keys, see 8.12 Keymaps and Hooks.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Faces

RefTeX uses faces when available to structure the selection and table of contents buffers. It does not create its own faces, but uses the ones defined in `font-lock.el'. Therefore, RefTeX will use faces only when font-lock is loaded. This seems to be reasonable because people who like faces will very likely have it loaded. If you wish to turn off fontification or change the involved faces, see 8.10 Fontification.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Multifile Documents

The following is relevant when working with documents spread over many files:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.5 Language Support

Some parts of RefTeX are language dependent. The default settings work well for English. If you are writing in a different language, the following hints may be useful:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.6 Finding Files

In order to find files included in a document via \input or \include, RefTeX searches all directories specified in the environment variable TEXINPUTS. Similarly, it will search the path specified in the variables BIBINPUTS and TEXBIB for BibTeX database files.

When searching, RefTeX will also expand recursive path definitions (directories ending in `//' or `!!'). But it will only search and expand directories explicitly given in these variables. This may cause problems under the following circumstances:

There are three ways to solve this problem:

Some people like to use RefTeX with noweb files, which usually have the extension `.nw'. In order to deal with such files, the new extension must be added to the list of valid extensions in the variable reftex-file-extensions. When working with AUCTeX as major mode, the new extension must also be known to AUCTeX via the variable TeX-file-extension. For example:

(setq reftex-file-extensions 
      '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
(setq TeX-file-extensions 
      '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.7 Optimizations

Note added 2002. Computers have gotten a lot faster, so most of the optimizations discussed below will not be necessary on new machines. I am leaving this stuff in the manual for people who want to write thick books, where some of it still might be useful.

Implementing the principle of least surprises, the default settings of RefTeX ensure a safe ride for beginners and casual users. However, when using RefTeX for a large project and/or on a small computer, there are ways to improve speed or memory usage.

As a summary, here are the settings I recommend for heavy use of RefTeX with large documents:

(setq reftex-enable-partial-scans t
      reftex-save-parse-info t
      reftex-use-multiple-selection-buffers t)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.8 AUC TeX

AUCTeX is without doubt the best major mode for editing TeX and LaTeX files with Emacs (see section `Top' in The AUCTeX User Manual). If AUCTeX is not part of your Emacs distribution, you can get it(10) by ftp from the AUCTeX distribution site.

6.8.1 The AUCTeX-RefTeX Interface  How both packages work together
6.8.2 Style Files  AUCTeX's style files can support RefTeX
6.8.3 Bib-Cite  Hypertext reading of a document

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.8.1 The AUCTeX-RefTeX Interface

RefTeX contains code to interface with AUCTeX. When this interface is turned on, both packages will interact closely. Instead of using RefTeX's commands directly, you can then also use them indirectly as part of the AUCTeX environment(11). The interface is turned on with

(setq reftex-plug-into-AUCTeX t)

If you need finer control about which parts of the interface are used and which not, read the docstring of the variable reftex-plug-into-AUCTeX or customize it with M-x customize-variable RET reftex-plug-into-AUCTeX RET.

The following list describes the individual parts of the interface.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.8.2 Style Files

Style files are Emacs Lisp files which are evaluated by AUCTeX in association with the \documentclass and \usepackage commands of a document (see section 6.8.2 Style Files). Support for RefTeX in such a style file is useful when the LaTeX style defines macros or environments connected with labels, citations, or the index. Many style files (e.g. `amsmath.el' or `natbib.el') distributed with AUCTeX already support RefTeX in this way.

Before calling a RefTeX function, the style hook should always test for the availability of the function, so that the style file will also work for people who do not use RefTeX.

Additions made with style files in the way described below remain local to the current document. For example, if one package uses AMSTeX, the style file will make RefTeX switch over to \eqref, but this will not affect other documents.

A style hook may contain calls to reftex-add-label-environments(13) which defines additions to reftex-label-alist. The argument taken by this function must have the same format as reftex-label-alist. The `amsmath.el' style file of AUCTeX for example contains the following:

(TeX-add-style-hook "amsmath"
   (lambda ()
     (if (fboundp 'reftex-add-label-environments)
         (reftex-add-label-environments '(AMSTeX)))))

while a package myprop defining a proposition environment with \newtheorem might use

(TeX-add-style-hook "myprop"
   (lambda ()
     (LaTeX-add-environments '("proposition" LaTeX-env-label))
     (if (fboundp 'reftex-add-label-environments)
          '(("proposition" ?p "prop:" "~\\ref{%s}" t
                           ("Proposition" "Prop.") -3))))))

Similarly, a style hook may contain a call to reftex-set-cite-format to set the citation format. The style file `natbib.el' for the Natbib citation style does switch RefTeX's citation format like this:

(TeX-add-style-hook "natbib"
   (lambda ()
     (if (fboundp 'reftex-set-cite-format)
         (reftex-set-cite-format 'natbib))))

The hook may contain a call to reftex-add-index-macros to define additional \index-like macros. The argument must have the same format as reftex-index-macros. It may be a symbol, to trigger support for one of the builtin index packages. For example, the style `multind.el' contains

(TeX-add-style-hook "multind"
  (lambda ()
    (and (fboundp 'reftex-add-index-macros)
	 (reftex-add-index-macros '(multind)))))

If you have your own package `myindex' which defines the following macros to be used with the LaTeX `index.sty' file


you could write this in the style file `myindex.el':

(TeX-add-style-hook "myindex"
   (lambda ()
      '("molec" TeX-arg-index)
      '("aindex" TeX-arg-index))
     (if (fboundp 'reftex-add-index-macros)
          '(("molec{*}" "idx" ?m "Molecules!" nil nil)
            ("aindex{*}" "author" ?a "" nil nil))))))

Finally the hook may contain a call to reftex-add-section-levels to define additional section statements. For example, the FoilTeX class has just two headers, \foilhead and \rotatefoilhead. Here is a style file `foils.el' that will inform RefTeX about these:

(TeX-add-style-hook "foils"
   (lambda ()
     (if (fboundp 'reftex-add-section-levels)
         (reftex-add-section-levels '(("foilhead" . 3)
                                      ("rotatefoilhead" . 3))))))

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.8.3 Bib-Cite

Once you have written a document with labels, references and citations, it can be nice to read it like a hypertext document. RefTeX has support for that: reftex-view-crossref (bound to C-c &), reftex-mouse-view-crossref (bound to S-mouse-2), and reftex-search-document. A somewhat fancier interface with mouse highlighting is provided (among other things) by Peter S. Galbraith's `bib-cite.el'. There is some overlap in the functionalities of Bib-cite and RefTeX. Bib-cite.el comes bundled with AUCTeX.

Bib-cite version 3.06 and later can be configured so that bib-cite's mouse functions use RefTeX for displaying references and citations. This can be useful in particular when working with the LaTeX xr package or with an explicit thebibliography environment (rather than BibTeX). Bib-cite cannot handle those, but RefTeX does. To make use of this feature, try

(setq bib-cite-use-reftex-view-crossref t)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.9 Problems and Work-arounds

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.10 Imprint

RefTeX was written by Carsten Dominik dominik@science.uva.nl, with contributions by Stephen Eglen. RefTeX is currently maintained by

Carsten Dominik dominik@science.uva.nl

If you have questions about RefTeX, there are several Usenet groups which have competent readers: comp.emacs, gnu.emacs.help, comp.emacs.xemacs, comp.text.tex, de.comp.text.tex. You can also write directly to the maintainer.

If you find a bug in RefTeX or its documentation, or if you want to contribute code or ideas, please contact the maintainer. Remember to provide all necessary information such as version numbers of Emacs and RefTeX, and the relevant part of your configuration in `.emacs'. When reporting a bug which throws an exception, please include a backtrace if you know how to produce one.

RefTeX is bundled and pre-installed with Emacs since version 20.2. It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs 21.x users want to install the corresponding plugin package which is available from the XEmacs ftp site.. See the XEmacs 21.x documentation on package installation for details.

Users of earlier Emacs distributions (including Emacs 19) can get a RefTeX distribution from the maintainers webpage. Note that the Emacs 19 version supports many but not all features described in this manual.

Thanks to the people on the Net who have used RefTeX and helped developing it with their reports. In particular thanks to Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai Grossjohann, Frank Harrell, Stephan Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii.

The view-crossref feature was inspired by Peter Galbraith's `bib-cite.el'.

Finally thanks to Uwe Bolick who first got me interested in supporting LaTeX labels and references with an editor (which was MicroEmacs at the time).

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on October, 2 2007 using texi2html