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:

\ref

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

\label

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.

\cite

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

\bibitem

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

BibTeX

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 &.

\index

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.

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.

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.

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.

6.4 Multifile Documents

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

• RefTeX has full support for multifile documents. You can edit parts of several (multifile) documents at the same time without conflicts. RefTeX provides functions to run grep, search and query-replace on all files which are part of a multifile document.

• All files belonging to a multifile document should define a File Variable (TeX-master for AUCTeX or tex-main-file for the standard Emacs LaTeX mode) containing the name of the master file. For example, to set the file variable TeX-master, include something like the following at the end of each TeX file:

  %%% Local Variables: *** %%% mode:latex *** %%% TeX-master: "thesis.tex" *** %%% End: ***

  AUCTeX with the setting

  (setq-default TeX-master nil)

  will actually ask you for each new file about the master file and insert this comment automatically. For more details see the documentation of the AUCTeX (see section `Multifile' in The AUC TeX User Manual), the documentation about the Emacs (La)TeX mode (see section `TeX Print' in The GNU Emacs Manual) and the Emacs documentation on File Variables (see section `File Variables' in The GNU Emacs Manual).

• The context of a label definition must be found in the same file as the label itself in order to be processed correctly by RefTeX. The only exception is that section labels referring to a section statement outside the current file can still use that section title as context.

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:

• The mechanism to derive a label from context includes the abbreviation of words and omission of unimportant words. These mechanisms may have to be changed for other languages. See the variables reftex-derive-label-parameters and reftex-abbrev-parameters.

• Also, when a label is derived from context, RefTeX clears the context string from non-ASCII characters in order to make a legal label. If there should ever be a version of TeX which allows extended characters in labels, then we will have to look at the variables reftex-translate-to-ascii-function and reftex-label-illegal-re.

• When a label is referenced, RefTeX looks at the word before point to guess which label type is required. These magic words are different in every language. For an example of how to add magic words, see 3.4.4 Adding Magic Words.

• RefTeX inserts "punctuation" for multiple references and for the author list in citations. Some of this may be language dependent. See the variables reftex-multiref-punctuation and reftex-cite-punctuation.

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:

• Most TeX system have a default search path for both TeX files and BibTeX files which is defined in some setup file. Usually this default path is for system files which RefTeX does not need to see. But if your document needs TeX files or BibTeX database files in a directory only given in the default search path, RefTeX will fail to find them.
• Some TeX systems do not use environment variables at all in order to specify the search path. Both default and user search path are then defined in setup files.

There are three ways to solve this problem:

• Specify all relevant directories explicitly in the environment variables. If for some reason you don't want to mess with the default variables TEXINPUTS and BIBINPUTS, define your own variables and configure RefTeX to use them instead:

  (setq reftex-texpath-environment-variables '("MYTEXINPUTS")) (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))

• Specify the full search path directly in RefTeX's variables.

  (setq reftex-texpath-environment-variables '("./inp:/home/cd/tex//:/usr/local/tex//")) (setq reftex-bibpath-environment-variables '("/home/cd/tex/lit/"))

• Some TeX systems provide stand--alone programs to do the file search just like TeX and BibTeX. E.g. Thomas Esser's teTeX uses the kpathsearch library which provides the command kpsewhich to search for files. RefTeX can be configured to use this program. Note that the exact syntax of the kpsewhich command depends upon the version of that program.

  (setq reftex-use-external-file-finders t) (setq reftex-external-file-finders '(("tex" . "kpsewhich -format=.tex %f") ("bib" . "kpsewhich -format=.bib %f")))

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"))

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.

• Removing Lookup Buffers
  RefTeX will load other parts of a multifile document as well as BibTeX database files for lookup purposes. These buffers are kept, so that subsequent use of the same files is fast. If you can't afford keeping these buffers around, and if you can live with a speed penalty, try

  (setq reftex-keep-temporary-buffers nil)

• Partial Document Scans
  A C-u prefix on the major RefTeX commands reftex-label (C-u C-c (), reftex-reference (C-u C-c )), reftex-citation (C-u C-c [), reftex-toc (C-u C-c =), and reftex-view-crossref (C-u C-c &) initiates re-parsing of the entire document in order to update the parsing information. For a large document this can be unnecessary, in particular if only one file has changed. RefTeX can be configured to do partial scans instead of full ones. C-u re-parsing then does apply only to the current buffer and files included from it. Likewise, the r key in both the label selection buffer and the table-of-contents buffer will only prompt scanning of the file in which the label or section macro near the cursor was defined. Re-parsing of the entire document is still available by using C-u C-u as a prefix, or the capital R key in the menus. To use this feature, try

  (setq reftex-enable-partial-scans t)

• Saving Parser Information
  Even with partial scans enabled, RefTeX still has to make one full scan, when you start working with a document. To avoid this, parsing information can be stored in a file. The file `MASTER.rel' is used for storing information about a document with master file `MASTER.tex'. It is written automatically when you kill a buffer in reftex-mode or when you exit Emacs. The information is restored when you begin working with a document in a new editing session. To use this feature, put into `.emacs':

  (setq reftex-save-parse-info t)

• Automatic Document Scans
  At rare occasions, RefTeX will automatically rescan a part of the document. If this gets into your way, it can be turned off with

  (setq reftex-allow-automatic-rescan nil)

  RefTeX will then occasionally annotate new labels in the selection buffer, saying that their position in the label list in uncertain. A manual document scan will fix this.

• Multiple Selection Buffers
  Normally, the selection buffer `*RefTeX Select*' is re-created for every selection process. In documents with very many labels this can take several seconds. RefTeX provides an option to create a separate selection buffer for each label type and to keep this buffer from one selection to the next. These buffers are updated automatically only when a new label has been added in the buffers category with reftex-label. Updating the buffer takes as long as recreating it - so the time saving is limited to cases where no new labels of that category have been added. To turn on this feature, use

  (setq reftex-use-multiple-selection-buffers t)

  You can also inhibit the automatic updating entirely. Then the selection buffer will always pop up very fast, but may not contain the most recently defined labels. You can always update the buffer by hand, with the g key. To get this behavior, use instead

  (setq reftex-use-multiple-selection-buffers t reftex-auto-update-selection-buffers nil)

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)

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

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.

• AUCTeX calls reftex-label to insert labels
  When a new section is created with C-c C-s, or a new environment is inserted with C-c C-e, AUCTeX normally prompts for a label to go with it. With the interface, reftex-label is called instead. For example, if you type C-c C-e equation RET, AUCTeX and RefTeX will insert

  \begin{equation} \label{eq:1} \end{equation}

  without further prompts.

  Similarly, when you type C-c C-s section RET, RefTeX will offer its default label which is derived from the section title.

• AUCTeX tells RefTeX about new sections
  When creating a new section with C-c C-s, RefTeX will not have to rescan the buffer in order to see it.

• RefTeX supplies macro arguments
  When you insert a macro interactively with C-c RET, AUCTeX normally prompts for macro arguments. Internally, it uses the functions TeX-arg-label, TeX-arg-cite, and TeX-arg-index to prompt for arguments which are labels, citation keys and index entries. The interface takes over these functions(12) and supplies the macro arguments with RefTeX's mechanisms. For example, when you type C-c RET ref RET, RefTeX will supply its label selection process (see section 3.2 Referencing Labels).

• RefTeX tells AUCTeX about new labels, citation-- and index keys
  RefTeX will add all newly created labels to AUCTeX's completion list.

6.8.2 Style Files

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

\newcommand{\molec}[1]{#1\index{Molecules!#1}}
\newcommand{\aindex}[1]{#1\index[author]{#1}

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

(TeX-add-style-hook "myindex"
   (lambda ()
     (TeX-add-symbols
      '("molec" TeX-arg-index)
      '("aindex" TeX-arg-index))
     (if (fboundp 'reftex-add-index-macros)
         (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))))))

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)

6.9 Problems and Work-arounds

• LaTeX commands
  \input, \include, and \section (etc.) statements have to be first on a line (except for white space).

• Commented regions
  RefTeX sees also labels in regions commented out and will refuse to make duplicates of such labels. This is considered to be a feature.

• Wrong section numbers
  When using partial scans (reftex-enable-partial-scans), the section numbers in the table of contents may eventually become wrong. A full scan will fix this.

• Local settings
  The label environment definitions in reftex-label-alist are global and apply to all documents. If you need to make definitions local to a document, because they would interfere with settings in other documents, you should use AUCTeX and set up style files with calls to reftex-add-label-environments, reftex-set-cite-format, reftex-add-index-macros, and reftex-add-section-levels. Settings made with these functions remain local to the current document. See section 6.8 AUC TeX.

• Funny display in selection buffer
  When using packages which make the buffer representation of a file different from its disk representation (e.g. x-symbol, isotex, iso-cvt) you may find that RefTeX's parsing information sometimes reflects the disk state of a file. This happens only in unvisited parts of a multifile document, because RefTeX visits these files literally for speed reasons. Then both short context and section headings may look different from what you usually see on your screen. In rare cases reftex-toc may have problems to jump to an affected section heading. There are three possible ways to deal with this:
  • (setq reftex-keep-temporary-buffers t)
    This implies that RefTeX will load all parts of a multifile document into Emacs (i.e. there won't be any temporary buffers).
  • (setq reftex-initialize-temporary-buffers t)
    This means full initialization of temporary buffers. It involves a penalty when the same unvisited file is used for lookup often.
  • Set reftex-initialize-temporary-buffers to a list of hook functions doing a minimal initialization.
  See also the variable reftex-refontify-context.

• Labels as arguments to \begin
  Some packages use an additional argument to a \begin macro to specify a label. E.g. Lamport's `pf.sty' uses both

  \step{label}{claim} and \begin{step+}{label} claim \end{step+}

  We need to trick RefTeX into swallowing this:

  ;; Configuration for Lamport's pf.sty (setq reftex-label-alist '(("\\step{*}{}" ?p "st:" "~\\stepref{%s}" 2 ("Step" "St.")) ("\\begin{step+}{*}" ?p "st:" "~\\stepref{%s}" 1000)))

  The first line is just a normal configuration for a macro. For the step+ environment we actually tell RefTeX to look for the macro `\begin{step+}' and interpret the first argument (which really is a second argument to the macro \begin) as a label of type ?p. Argument count for this macro starts only after the `{step+}', also when specifying how to get context.

• Idle timers in XEmacs
  In XEmacs, idle timer restart does not work reliably after fast keystrokes. Therefore RefTeX currently uses the post command hook to start the timer used for automatic crossref information. When this bug gets fixed, a real idle timer can be requested with

  (setq reftex-use-itimer-in-xemacs t)

• Viper mode
  With Viper mode prior to Vipers version 3.01, you need to protect RefTeX's keymaps with

  (viper-harness-minor-mode "reftex")

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

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.