RefTeX ¶

1.1 Installation ¶

RefTeX has been bundled and pre-installed with Emacs since version 20.2.

To turn RefTeX Mode on and off in a particular buffer, use M-x reftex-mode RET. To turn on RefTeX Mode for all LaTeX files, add the following lines to your .emacs file:

(add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
(add-hook 'latex-mode-hook 'turn-on-reftex)   ; with Emacs latex mode

That’s all!

To get started, read the documentation, in particular the summary. (see RefTeX in a Nutshell)

In order to produce a printed version of the documentation, use make pdf to produce a reftex.pdf file. Analogously you can use the dvi, ps, or html targets to create DVI, PostScript or HTML files.

• Environment

1.2 RefTeX in a Nutshell ¶

1. Table of Contents
   Typing C-c = (reftex-toc) will show a table of contents of the document. This buffer can display sections, labels and index entries defined in the document. From the buffer, you can jump quickly to every part of your document. Press ? to get help.
2. Labels and References
   RefTeX helps to create unique labels and to find the correct key for references quickly. It distinguishes labels for different environments, knows about all standard environments (and many others), and can be configured to recognize any additional labeled environments you have defined yourself (variable reftex-label-alist).
   • Creating Labels
     Type C-c ( (reftex-label) to insert a label at point. RefTeX will either
     • derive a label from context (default for section labels)
     • prompt for a label string (default for figures and tables) or
     • insert a simple label made of a prefix and a number (all other environments)

     Which labels are created how is configurable with the variable reftex-insert-label-flags.

   • Referencing Labels
     To make a reference, type C-c ) (reftex-reference). This shows an outline of the document with all labels of a certain type (figure, equation,...) and some label context. Selecting a label inserts a \ref{label} macro into the original buffer.
3. Citations
   Typing C-c [ (reftex-citation) will let you specify a regular expression to search in current BibTeX database files (as specified in the \bibliography command) and pull out a list of matches for you to choose from. The list is formatted and sorted. The selected article is referenced as ‘\cite{key}’ (see the variable reftex-cite-format if you want to insert different macros).
4. Index Support
   RefTeX helps to enter index entries. It also compiles all entries into an alphabetically sorted *Index* buffer which you can use to check and edit the entries. RefTeX knows about the standard index macros and can be configured to recognize any additional macros you have defined (reftex-index-macros). Multiple indices are supported.
   • Creating Index Entries
     To index the current selection or the word at point, type C-c / (reftex-index-selection-or-word). The default macro reftex-index-default-macro will be used. For a more complex entry type C-c < (reftex-index), select any of the index macros and enter the arguments with completion.
   • The Index Phrases File (Delayed Indexing)
     Type C-c \ (reftex-index-phrase-selection-or-word) to add the current word or selection to a special index phrase file. RefTeX can later search the document for occurrences of these phrases and let you interactively index the matches.
   • Displaying and Editing the Index
     To display the compiled index in a special buffer, type C-c > (reftex-display-index). From that buffer you can check and edit all entries.
5. Viewing Cross-References
   When point is on the key argument of a cross-referencing macro (\label, \ref, \cite, \bibitem, \index, and variations) or inside a BibTeX database entry, you can press C-c & (reftex-view-crossref) to display corresponding locations in the document and associated BibTeX database files.
   When the enclosing macro is \cite or \ref and no other message occupies the echo area, information about the citation or label will automatically be displayed in the echo area.
6. Multifile Documents
   Multifile Documents are fully supported. The included files must have a file variable TeX-master or tex-main-file pointing to the master file. RefTeX provides cross-referencing information from all parts of the document, and across document borders (xr.sty).
7. Document Parsing
   RefTeX needs to parse the document in order to find labels and other information. It does it automatically once and updates its list internally when reftex-label and reftex-index are used. To enforce reparsing, call any of the commands described above with a raw C-u prefix, or press the r key in the label selection buffer, the table of contents buffer, or the index buffer.
8. AUCTeX
   If your major LaTeX mode is AUCTeX, RefTeX can cooperate with it (see variable reftex-plug-into-AUCTeX). AUCTeX contains style files which trigger appropriate settings in RefTeX, so that for many of the popular LaTeX packages no additional customizations will be necessary.
9. Useful Settings
   To integrate RefTeX with AUCTeX, use

   (setq reftex-plug-into-AUCTeX t)
   

   To make your own LaTeX macro definitions known to RefTeX, customize the variables

   reftex-label-alist          (for label macros/environments)
   reftex-section-levels       (for sectioning commands)
   reftex-cite-format          (for \cite-like macros)
   reftex-index-macros         (for \index-like macros)
   reftex-index-default-macro  (to set the default macro)
   

   If you have a large number of macros defined, you may want to write an AUCTeX style file to support them with both AUCTeX and RefTeX.

10. Where Next?
    Go ahead and use RefTeX. Use its menus until you have picked up the key bindings. For an overview of what you can do in each of the different special buffers, press ?. Read the manual if you get stuck, or if you are curious what else might be available. The first part of the manual explains in a tutorial way how to use and customize RefTeX. The second part is a command and variable reference.

3.1 Creating Labels ¶

In order to create a label in a LaTeX document, press C-c ( (reftex-label). Just like LaTeX, RefTeX is context sensitive and will figure out the environment it currently is in and adapt the label to that environment. A label usually consists of a short prefix indicating the type of the label and a unique mark. RefTeX has three different modes to create this mark.

1. A label can be derived from context. This means, RefTeX takes the context of the label definition and constructs a label from that¹. This works best for section labels, where the section heading is used to construct a label. In fact, RefTeX’s default settings use this method only for section labels. You will be asked to confirm the derived label, or edit it.
2. We may also use a simple unique number to identify a label. This is mostly useful for labels where it is difficult to come up with a very good descriptive name. RefTeX’s default settings use this method for equations, enumerate items and footnotes. The author of RefTeX tends to write documents with many equations and finds it impossible to come up with good names for each of them. These simple labels are inserted without query, and are therefore very fast. Good descriptive names are not really necessary as RefTeX will provide context to reference a label (see Referencing Labels).
3. The third method is to ask the user for a label. This is most useful for things which are easy to describe briefly and do not turn up too frequently in a document. RefTeX uses this for figures and tables. Of course, one can enter the label directly by typing the full ‘\label{mark}’. The advantage of using reftex-label anyway is that RefTeX will know that a new label has been defined. It will then not be necessary to rescan the document in order to access this label later.

If you want to change the way certain labels are created, check out the variable reftex-insert-label-flags (see Creating Labels).

If you are using AUCTeX to write your LaTeX documents, you can set it up to delegate the creation of labels to RefTeX. See AUCTeX, for more information.

3.2 Referencing Labels ¶

RefTeX scans the document in order to find all labels. To make referencing labels easier, it assigns to each label a category, the label type (for example section, table, figure, equation, etc.). In order to determine the label type, RefTeX parses around each label to see in what kind of environments it is located. You can speed up the parsing by using type-specific prefixes for labels and configuring the variable reftex-trust-label-prefix.

Referencing Labels is really at the heart of RefTeX. Press C-c ) in order to reference a label (reftex-reference). This will start a selection process and finally insert the complete ‘\ref{label}’ into the buffer.

First, you can select which reference macro you want to use, e.g., ‘\ref’ or ‘\pageref’. Later in the process you have another chance to make this selection and you can therefore disable this step by customizing reftex-ref-macro-prompt if you find it too intrusive. See Reference Styles.

Then, RefTeX will determine the label category which is required. Often that can be figured out from context. For example, if you write ‘As shown in eq.’ and then press C-c ), RefTeX knows that an equation label is going to be referenced. If it cannot figure out what label category is needed, it will query for one.

You will then be presented with a label selection menu. This is a special buffer which contains an outline of the document along with all labels of the given label category. In addition, next to the label there will be one line of context of the label definition, which is some text in the buffer near the label definition. Usually this is sufficient to identify the label. If you are unsure about a certain label, pressing SPC will show the label definition point in another window.

In order to reference a label, move the cursor to the correct label and press RET. You can also reference several labels with a single call to reftex-reference by marking entries with the m key (see below).

Here is a list of special commands in the selection buffer. A summary of this information is always available from the selection process by pressing ?.

General

?

Show a summary of available commands.

0-9,-

Prefix argument.

Moving around

n

Go to next label.

p

Go to previous label.

b

Jump back to the position where you last left the selection buffer. Normally this should get you back to the last referenced label.

C-c C-n

Goto next section heading.

C-c C-p

Goto previous section heading.

N z

Jump to section N, using the prefix arg. For example 3 z jumps to section 3.

Displaying Context

SPC

Show the surroundings of the definition of the current label in another window. See also the f key.

f ¶

Toggle follow mode. When follow mode is active, the other window will always display the full context of the current label. This is similar to pressing SPC after each cursor motion. Note that only context in files already visited is shown. RefTeX will not visit a file just for follow mode. See, however, the variable reftex-revisit-to-follow.

.

Show insertion point in another window. This is the point from where you called reftex-reference.

Selecting a label and creating the reference

RET

Insert a reference to the label at point into the buffer from which the selection process was started. When entries have been marked, RET references all marked labels.

mouse-2 ¶

Clicking with mouse button 2 on a label will accept it like RET would. See also variable reftex-highlight-selection, Miscellaneous.

m - + , ¶

Mark the current entry. When several entries have been marked, pressing RET will accept all of them and place them into several \ref macros. The special markers ‘,-+’ also store a separator to be inserted before the corresponding reference. So marking six entries with the keys ‘m , , - , +’ will give a reference list like this (see the variable reftex-multiref-punctuation)

In eqs. (1), (2), (3)--(4), (5) and (6)

u

Unmark a marked entry.

a ¶

Accept the marked entries and put all labels as a comma-separated list into one single \ref macro. Some packages like saferef.sty support multiple references in this way.

l

Use the last referenced label(s) again. This is equivalent to moving to that label and pressing RET.

TAB

Enter a label with completion. This may also be a label which does not yet exist in the document.

v

Cycle forward through active reference macros. The selected macro is displayed by the ‘S<...>’ indicator in the mode line of the selection buffer. This mechanism comes in handy if you are using LaTeX packages like varioref or fancyref and want to use the special referencing macros they provide (e.g., \vref or \fref) instead of \ref.

V

Cycle backward through active reference macros.

Exiting

q

Exit the selection process without inserting any reference into the buffer.

Controlling what gets displayed ¶

The defaults for the following flags can be configured with the variable reftex-label-menu-flags (see Referencing Labels).

c

Toggle the display of the one-line label definition context in the selection buffer.

F

Toggle the display of the file borders of a multifile document in the selection buffer.

t

Toggle the display of the table of contents in the selection buffer. With prefix arg, change the maximum level of toc entries displayed to arg. Chapters are level 1, sections are level 2.

#

Toggle the display of a label counter in the selection buffer.

%

Toggle the display of labels hidden in comments in the selection buffers. Sometimes, you may have commented out parts of your document. If these parts contain label definitions, RefTeX can still display and reference these labels.

Updating the buffer

g

Update the menu. This will rebuilt the menu from the internal label list, but not reparse the document (see r).

r ¶

Reparse the document to update the information on all labels and rebuild the menu. If the variable reftex-enable-partial-scans is non-nil and your document is a multifile document, this will reparse only a part of the document (the file in which the label at point was defined).

C-u r

Reparse the entire document.

s

Switch the label category. After prompting for another label category, a menu for that category will be shown.

x

Reference a label from an external document. With the LaTeX package xr it is possible to reference labels defined in another document. This key will switch to the label menu of an external document and let you select a label from there (see xr).

In order to define additional commands for the selection process, the keymap reftex-select-label-mode-map may be used.

3.3 Builtin Label Environments ¶

RefTeX needs to be aware of the environments which can be referenced with a label (i.e., which carry their own counters). By default, RefTeX recognizes all labeled environments and macros discussed in The LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley 1994.. These are:

• figure, figure*, table, table*, equation, eqnarray, enumerate, the \footnote macro (this is the LaTeX core stuff)
• align, gather, multline, flalign, alignat, xalignat, xxalignat, subequations (from AMS-LaTeX’s amsmath.sty package)
• the \endnote macro (from endnotes.sty)
• Beqnarray (fancybox.sty)
• floatingfig (floatfig.sty)
• longtable (longtable.sty)
• figwindow, tabwindow (picinpar.sty)
• SCfigure, SCtable (sidecap.sty)
• sidewaysfigure, sidewaystable (rotating.sty)
• subfigure, subfigure*, the \subfigure macro (subfigure.sty)
• supertabular (supertab.sty)
• wrapfigure (wrapfig.sty)

If you want to use other labeled environments, defined with \newtheorem, RefTeX needs to be configured to recognize them (see Defining Label Environments).

3.4 Defining Label Environments ¶

RefTeX can be configured to recognize additional labeled environments and macros. This is done with the variable reftex-label-alist (see Defining Label Environments). If you are not familiar with Lisp, you can use the custom library to configure this rather complex variable. To do this, use

M-x customize-variable RET reftex-label-alist RET

Here we will discuss a few examples, in order to make things clearer. It can also be instructive to look at the constant reftex-label-alist-builtin which contains the entries for all the builtin environments and macros (see Builtin Label Environments).

• Theorem and Axiom Environments
• Quick Equation Macro
• Figure Wrapping Macro
• Adding Magic Words
• Using \eqref
• Non-standard Environments
• Putting it all together

\newtheorem{axiom}{Axiom}
\newtheorem{theorem}{Theorem}

\begin{axiom}
\label{ax:first}
  ....
\end{axiom}

(setq reftex-label-alist
   '(("axiom"   ?a "ax:"  "~\\ref{%s}" nil ("axiom"   "ax.") -2)
     ("theorem" ?h "thr:" "~\\ref{%s}" t   ("theorem" "th.") -3)))

(add-hook 'LaTeX-mode-hook
   (lambda ()
     (LaTeX-add-environments
       '("axiom" LaTeX-env-label)
       '("theorem" LaTeX-env-label))))

Reftex Label Alist: [Hide]
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: axiom
            Type specification    : [Value Menu] Char  : a
            Label prefix string   : [Value Menu] String: ax:
            Label reference format: [Value Menu] String: ~\ref{%s}
            Context method        : [Value Menu] After label
            Magic words:
              [INS] [DEL] String: axiom
              [INS] [DEL] String: ax.
              [INS]
            [X] Make TOC entry    : [Value Menu] Level: -2
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: theorem
            Type specification    : [Value Menu] Char  : h
            Label prefix string   : [Value Menu] String: thr:
            Label reference format: [Value Menu] String: ~\ref{%s}
            Context method        : [Value Menu] Default position
            Magic words:
              [INS] [DEL] String: theorem
              [INS] [DEL] String: theor.
              [INS] [DEL] String: th.
              [INS]
            [X] Make TOC entry    : [Value Menu] Level: -3

\newcommand{\quickeq}[1]{\begin{equation} #1 \end{equation}}

Einstein's equation is \quickeq{E=mc^2 \label{eq:einstein}}.

(setq reftex-label-alist '(("\\quickeq{}" ?e nil nil 1 nil)))

Reftex Label Alist: [Hide]
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: \quickeq{}
            Type specification    : [Value Menu] Char  : e
            Label prefix string   : [Value Menu] Default
            Label reference format: [Value Menu] Default
            Context method        : [Value Menu] Macro arg nr: 1
            Magic words:
              [INS]
            [ ] Make TOC entry    : [Value Menu] No entry

\newcommand{\myfig}[5][tbp]{%
  \begin{figure}[#1]
    \epsimp[#5]{#2}
    \caption{#3}
    \label{#4}
  \end{figure}}

\myfig[htp]{filename}{caption text}{label}{1}

(setq reftex-label-alist
      '(("\\myfig[]{}{}{*}{}" ?f nil nil 3)))

[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: \myfig[]{}{}{*}{}
            Type specification    : [Value Menu] Char  : f
            Label prefix string   : [Value Menu] Default
            Label reference format: [Value Menu] Default
            Context method        : [Value Menu] Macro arg nr: 3
            Magic words:
              [INS]
            [ ] Make TOC entry    : [Value Menu] No entry

(setq reftex-label-alist
  '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
    (nil ?e nil nil nil ("Gleichung" "Gl."))
    (nil ?t nil nil nil ("Tabelle"))
    (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
    (nil ?n nil nil nil ("Anmerkung" "Anm."))
    (nil ?i nil nil nil ("Punkt"))))

(setq reftex-label-alist '((nil ?e nil "~\\eqref{%s}" nil nil)))

(setq reftex-label-alist '(AMSTeX))

;; Setup entry in reftex-label-alist, using all defaults for equations
(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))

(defun detect-be-ee (bound)
  ;; Search backward for the macros or an empty line
  (if (re-search-backward
       "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
      (if (match-beginning 2)
          (match-beginning 2)  ; Return start of environment
        nil)                   ; Return nil because env is closed
    nil))                      ; Return nil for not found

\ex.  \label{ex:12} Some text in an exotic language ...
      \a. \label{ex:13} more stuff
      \b. \label{ex:14} still more stuff
          \a. List on a deeper level
          \b. Another item
          \b. and the third one
      \z.
      \b. Third item on this level.

... text after the empty line terminating all lists

(setq reftex-label-alist
      '((detect-linguex ?x "ex:" "~\\ref{%s}" nil ("Example" "Ex."))))

(defun detect-linguex (bound)
  (let ((cnt 0))
    (catch 'exit
      (while
          ;; Search backward for all possible delimiters
          (re-search-backward
           (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
                   "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
           nil t)
        ;; Check which delimiter was matched.
        (cond
         ((match-beginning 1)
          ;; empty line terminates all - return nil
          (throw 'exit nil))
         ((match-beginning 2)
          ;; \z. terminates one list level - decrease nesting count
          (decf cnt))
         ((match-beginning 3)
          ;; \ex. : return match unless there was a \z. on this level
          (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
         ((match-beginning 4)
          ;; \a. : return match when on level 0, otherwise
          ;;       increment nesting count
          (if (>= cnt 0)
              (throw 'exit (match-beginning 4))
            (incf cnt))))))))

(setq reftex-label-alist
  '(("axiom"   ?a "ax:"  "~\\ref{%s}" nil ("axiom"   "ax.") -2)
    ("theorem" ?h "thr:" "~\\ref{%s}" t   ("theorem" "theor." "th.") -3)
    ("\\quickeq{}" ?e nil nil 1 nil)
    AMSTeX
    ("\\myfig[]{}{}{*}{}" ?f nil nil 3)
    (detect-linguex ?x "ex:" "~\\ref{%s}" nil ("Example" "Ex."))))

3.5 Reference Info ¶

When point is idle for more than reftex-idle-time seconds on the argument of a \ref macro, the echo area will display some information about the label referenced there. Note that the information is only displayed if the echo area is not occupied by a different message.

RefTeX can also display the label definition corresponding to a \ref macro, or all reference locations corresponding to a \label macro. See Viewing Cross-References, for more information.

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

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.

3.7 xr: Cross-Document References ¶

The LaTeX package xr makes it possible to create references to labels defined in external documents. The preamble of a document using xr will contain something like this:

\usepackage{xr}
\externaldocument[V1-]{volume1}
\externaldocument[V3-]{volume3}

and we can make references to any labels defined in these external documents by using the prefixes ‘V1-’ and ‘V3-’, respectively.

RefTeX can be used to create such references as well. Start the referencing process normally, by pressing C-c ). Select a label type if necessary. When you see the label selection buffer, pressing x will switch to the label selection buffer of one of the external documents. You may then select a label as before and RefTeX will insert it along with the required prefix.

For this kind of inter-document cross-references, saving of parsing information and the use of multiple selection buffers can mean a large speed-up (see Optimizations).

4.1 Creating Citations ¶

In order to create a citation, press C-c [. RefTeX then prompts for a regular expression which will be used to search through the database and present the list of matches to choose from in a selection process similar to that for selecting labels (see Referencing Labels).

The regular expression uses an extended syntax: ‘&&’ defines a logic and for regular expressions. For example ‘Einstein&&Bose’ will match all articles which mention Bose-Einstein condensation, or which are co-authored by Bose and Einstein. When entering the regular expression, you can complete on known citation keys. RefTeX also offers a default when prompting for a regular expression. This default is the word before the cursor or the word before the current ‘\cite’ command. Sometimes this may be a good search key.

RefTeX prefers to use BibTeX database files specified with a \bibliography macro to collect its information. Just like BibTeX, it will search for the specified files in the current directory and along the path given in the environment variable BIBINPUTS. If you do not use BibTeX, but the document contains an explicit thebibliography environment, RefTeX will collect its information from there. Note that in this case the information presented in the selection buffer will just be a copy of relevant \bibitem entries, not the structured listing available with BibTeX database files.

In the selection buffer, the following keys provide special commands. A summary of this information is always available from the selection process by pressing ?.

General

?

Show a summary of available commands.

0-9,-

Prefix argument.

Moving around

n

Go to next article.

p

Go to previous article.

Access to full database entries

SPC

Show the database entry corresponding to the article at point, in another window. See also the f key.

f

Toggle follow mode. When follow mode is active, the other window will always display the full database entry of the current article. This is equivalent to pressing SPC after each cursor motion. With BibTeX entries, follow mode can be rather slow.

Selecting entries and creating the citation

RET

Insert a citation referencing the article at point into the buffer from which the selection process was started.

mouse-2 ¶

Clicking with mouse button 2 on a citation will accept it like RET would. See also variable reftex-highlight-selection, Miscellaneous.

m

Mark the current entry. When one or several entries are marked, pressing a or A accepts all marked entries. Also, RET behaves like the a key.

u

Unmark a marked entry.

a

Accept all (marked) entries in the selection buffer and create a single \cite macro referring to them.

A

Accept all (marked) entries in the selection buffer and create a separate \cite macro for each of it.

e

Create a new BibTeX database file which contains all marked entries in the selection buffer. If no entries are marked, all entries are selected.

E

Create a new BibTeX database file which contains all unmarked entries in the selection buffer. If no entries are marked, all entries are selected.

TAB

Enter a citation key with completion. This may also be a key which does not yet exist.

.

Show insertion point in another window. This is the point from where you called reftex-citation.

Exiting

q

Exit the selection process without inserting a citation into the buffer.

Updating the buffer

g

Start over with a new regular expression. The full database will be rescanned with the new expression (see also r).

r

Refine the current selection with another regular expression. This will not rescan the entire database, but just the already selected entries.

In order to define additional commands for this selection process, the keymap reftex-select-bib-mode-map may be used.

Note that if you do not use Emacs to edit the BibTeX database files, RefTeX will ask if the related buffers should be updated once it detects that the files were changed externally. If you do not want to be bothered by such queries, you can activate Auto Revert mode for these buffers by adding the following expression to your init file:

(add-hook 'bibtex-mode-hook 'turn-on-auto-revert-mode)

4.2 Citation Styles ¶

The standard LaTeX macro \cite works well with numeric or simple key citations. To deal with the more complex task of author-year citations as used in many natural sciences, a variety of packages has been developed which define derived forms of the \cite macro. RefTeX can be configured to produce these citation macros as well by setting the variable reftex-cite-format. For the most commonly used LaTeX packages (natbib, harvard, chicago, jurabib) and for ConTeXt this may be done from the menu, under Ref->Citation Styles. Since there are usually several macros to create the citations, executing reftex-citation (C-c [) starts by prompting for the correct macro. For the Natbib style, this looks like this:

SELECT A CITATION FORMAT

[^M]   \cite{%l}
[t]    \citet{%l}
[T]    \citet*{%l}
[p]    \citep{%l}
[P]    \citep*{%l}
[e]    \citep[e.g.][]{%l}
[s]    \citep[see][]{%l}
[a]    \citeauthor{%l}
[A]    \citeauthor*{%l}
[y]    \citeyear{%l}

If citation formats contain empty pairs of square brackets, RefTeX will prompt for values of these optional arguments if you call the reftex-citation command with a C-u prefix. Following the most generic of these packages, natbib, the builtin citation packages always accept the t key for a textual citation (like: Jones et al. (1997) have shown...) as well as the p key for a parenthetical citation (like: As shown earlier (Jones et al, 1997)).

To make one of these styles the default, customize the variable reftex-cite-format or put into .emacs:

(setq reftex-cite-format 'natbib)

You can also use AUCTeX style files to automatically set the citation style based on the usepackage commands in a given document. See Style Files, for information on how to set up the style files correctly.

4.3 Citation Info ¶

When point is idle for more than reftex-idle-time seconds on the argument of a \cite macro, the echo area will display some information about the article cited there. Note that the information is only displayed if the echo area is not occupied by a different message.

RefTeX can also display the \bibitem or BibTeX database entry corresponding to a \cite macro, or all citation locations corresponding to a \bibitem or BibTeX database entry. See Viewing Cross-References.

4.4 Chapterbib and Bibunits ¶

chapterbib and bibunits are two LaTeX packages which produce multiple bibliographies in a document. This is no problem for RefTeX as long as all bibliographies use the same BibTeX database files. If they do not, it is best to have each document part in a separate file (as it is required for chapterbib anyway). Then RefTeX will still scan the locally relevant databases correctly. If you have multiple bibliographies within a single file, this may or may not be the case.

4.5 Citations outside LaTeX ¶

The command reftex-citation can also be executed outside a LaTeX buffer. This can be useful to reference articles in the mail buffer and other documents. You should not enter reftex-mode for this, just execute the command. The list of BibTeX files will in this case be taken from the variable reftex-default-bibliography. Setting the variable reftex-cite-format to the symbol locally does a decent job of putting all relevant information about a citation directly into the buffer. Here is the lisp code to add the C-c [ binding to the mail buffer. It also provides a local binding for reftex-cite-format.

(add-hook 'mail-setup-hook
          (lambda () (define-key mail-mode-map "\C-c["
                       (lambda ()
                         (interactive)
                         (let ((reftex-cite-format 'locally))
                           (reftex-citation))))))

4.6 Database Subsets ¶

RefTeX offers two ways to create a new BibTeX database file.

The first option produces a file which contains only the entries actually referenced in the current document. This can be useful if the database is only meant for a single document and you want to clean it of old and unused ballast. It can also be useful while writing a document together with collaborators, in order to avoid sending around the entire (possibly very large) database. To create the file, use M-x reftex-create-bibtex-file, also available from the menu under Ref->Global Actions->Create Bibtex File. The command will prompt for a BibTeX file name and write the extracted entries to that file.

The second option makes use of the selection process started by the command C-c [ (see Creating Citations). This command uses a regular expression to select entries, and lists them in a formatted selection buffer. After pressing the e key (mnemonics: Export), the command will prompt for the name of a new BibTeX file and write the selected entries to that file. You can also first mark some entries in the selection buffer with the m key and then export either the marked entries (with the e key) or the unmarked entries (with the E key).

5.1 Creating Index Entries ¶

In order to index the current selection or the word at the cursor press C-c / (reftex-index-selection-or-word). This causes the selection or word ‘word’ to be replaced with ‘\index{word}word’. The macro which is used (\index by default) can be configured with the variable reftex-index-default-macro. When the command is called with a prefix argument (C-u C-c /), you get a chance to edit the generated index entry. Use this to change the case of the word or to make the entry a subentry, for example by entering ‘main!sub!word’. When called with two raw C-u prefixes (C-u C-u C-c /), you will be asked for the index macro as well. When there is nothing selected and no word at point, this command will just call reftex-index, described below.

In order to create a general index entry, press C-c < (reftex-index). RefTeX will prompt for one of the available index macros and for its arguments. Completion will be available for the index entry and, if applicable, the index tag. The index tag is a string identifying one of multiple indices. With the multind and index packages, this tag is the first argument to the redefined \index macro.

5.2 The Index Phrases File ¶

RefTeX maintains a file in which phrases can be collected for later indexing. The file is located in the same directory as the master file of the document and has the extension .rip (Reftex Index Phrases). You can create or visit the file with C-c | (reftex-index-visit-phrases-buffer). If the file is empty it is initialized by inserting a file header which contains the definition of the available index macros. This list is initialized from reftex-index-macros (see Defining Index Macros). You can edit the header as needed, but if you define new LaTeX indexing macros, don’t forget to add them to reftex-index-macros as well. Here is a phrase file header example:

% -*- mode: reftex-index-phrases -*-
%                           Key   Macro Format       Repeat
%----------------------------------------------------------
>>>INDEX_MACRO_DEFINITION:   i    \index{%s}          t
>>>INDEX_MACRO_DEFINITION:   I    \index*{%s}         nil
>>>INDEX_MACRO_DEFINITION:   g    \glossary{%s}       t
>>>INDEX_MACRO_DEFINITION:   n    \index*[name]{%s}   nil
%----------------------------------------------------------

The macro definition lines consist of a unique letter identifying a macro, a format string and the repeat flag, all separated by TAB. The format string shows how the macro is to be applied, the ‘%s’ will be replaced with the index entry. The repeat flag indicates if word is indexed by the macro as ‘\index{word}’ (repeat = nil) or as ‘\index{word}word’ (repeat = t). In the above example it is assumed that the macro \index*{word} already typesets its argument in the text, so that it is unnecessary to repeat word outside the macro.

• Collecting Phrases
• Consistency Checks
• Global Indexing

[key] <TABs> phrase [<TABs> arg[&&arg]... [ || arg]...]

%--------------------------------------------------------------------
I     Sun
i     Planet         Planets
i     Vega           Stars!Vega
      Jupiter        Planets!Jupiter
i     Mars           Planets!Mars || Gods!Mars || Chocolate Bars!Mars
i     Pluto          Planets!Pluto && Kuiper Belt Objects!Pluto

5.3 Displaying and Editing the Index ¶

In order to compile and display the index, press C-c >. If the document uses multiple indices, RefTeX will ask you to select one. Then, all index entries will be sorted alphabetically and displayed in a special buffer, the *Index* buffer. From that buffer you can check and edit each entry.

The index can be restricted to the current section or the region. Then only entries in that part of the document will go into the compiled index. To restrict to the current section, use a numeric prefix ‘2’, thus press C-u 2 C-c >. To restrict to the current region, make the region active and use a numeric prefix ‘3’ (press C-u 3 C-c >). From within the *Index* buffer the restriction can be moved from one section to the next by pressing the < and > keys.

One caveat: RefTeX finds the definition point of an index entry by searching near the buffer position where it had found to macro during scanning. If you have several identical index entries in the same buffer and significant changes have shifted the entries around, you must rescan the buffer to ensure the correspondence between the *Index* buffer and the definition locations. It is therefore advisable to rescan the document (with r or C-u r) frequently while editing the index from the *Index* buffer.

Here is a list of special commands available in the *Index* buffer. A summary of this information is always available by pressing ?.

General

?

Display a summary of commands.

0-9, -

Prefix argument.

Moving around

! A..Z

Pressing any capital letter will jump to the corresponding section in the *Index* buffer. The exclamation mark is special and jumps to the first entries alphabetically sorted below ‘A’. These are usually non-alphanumeric characters.

n

Go to next entry.

p

Go to previous entry.

Access to document locations

SPC

Show the place in the document where this index entry is defined.

TAB

Go to the definition of the current index entry in another window.

RET

Go to the definition of the current index entry and hide the *Index* buffer window.

f ¶

Toggle follow mode. When follow mode is active, the other window will always show the location corresponding to the line in the *Index* buffer at point. This is similar to pressing SPC after each cursor motion. The default for this flag can be set with the variable reftex-index-follow-mode. Note that only context in files already visited is shown. RefTeX will not visit a file just for follow mode. See, however, the variable reftex-revisit-to-follow.

Entry editing

e

Edit the current index entry. In the minibuffer, you can edit the index macro which defines this entry.

C-k

Kill the index entry. Currently not implemented because I don’t know how to implement an undo function for this.

*

Edit the key part of the entry. This is the initial part of the entry which determines the location of the entry in the index.

|

Edit the attribute part of the entry. This is the part after the vertical bar. With MakeIndex, this part is an encapsulating macro. With xindy, it is called attribute and is a property of the index entry that can lead to special formatting. When called with C-u prefix, kill the entire attribute part.

@

Edit the visual part of the entry. This is the part after the ‘@’ which is used by MakeIndex to change the visual appearance of the entry in the index. When called with C-u prefix, kill the entire visual part.

(

Toggle the beginning of page range property ‘|(’ of the entry.

)

Toggle the end of page range property ‘|)’ of the entry.

_

Make the current entry a subentry. This command will prompt for the superordinate entry and insert it.

^

Remove the highest superordinate entry. If the current entry is a subitem (‘aaa!bbb!ccc’), this function moves it up the hierarchy (‘bbb!ccc’).

Exiting

q

Hide the *Index* buffer.

k

Kill the *Index* buffer.

C-c =

Switch to the Table of Contents buffer of this document.

Controlling what gets displayed

c ¶

Toggle the display of short context in the *Index* buffer. The default for this flag can be set with the variable reftex-index-include-context.

}

Restrict the index to a single document section. The corresponding section number will be displayed in the R<> indicator in the mode line and in the header of the *Index* buffer.

{

Widen the index to contain all entries of the document.

<

When the index is currently restricted, move the restriction to the previous section.

>

When the index is currently restricted, move the restriction to the next section.

Updating the buffer

g

Rebuild the *Index* buffer. This does not rescan the document. However, it sorts the entries again, so that edited entries will move to the correct position.

r ¶

Reparse the LaTeX document and rebuild the *Index* buffer. When reftex-enable-partial-scans is non-nil, rescan only the file this location is defined in, not the entire document.

C-u r

Reparse the entire LaTeX document and rebuild the *Index* buffer.

s

Switch to a different index (for documents with multiple indices).

5.4 Builtin Index Macros ¶

RefTeX by default recognizes the \index and \glossary macros which are defined in the LaTeX core. It has also builtin support for the re-implementations of \index in the multind and index packages. However, since the different definitions of the \index macro are incompatible, you will have to explicitly specify the index style used. See Creating Index Entries, for information on how to do that.

5.5 Defining Index Macros ¶

When writing a document with an index you will probably define additional macros which make entries into the index. Let’s look at an example.

\newcommand{\ix}[1]{#1\index{#1}}
\newcommand{\nindex}[1]{\textit{#1}\index[name]{#1}}
\newcommand{\astobj}[1]{\index{Astronomical Objects!#1}}

The first macro \ix typesets its argument in the text and places it into the index. The second macro \nindex typesets its argument in the text and places it into a separate index with the tag ‘name’⁶. The last macro also places its argument into the index, but as subitems under the main index entry ‘Astronomical Objects’. Here is how to make RefTeX recognize and correctly interpret these macros, first with Emacs Lisp.

(setq reftex-index-macros
      '(("\\ix{*}" "idx" ?x "" nil nil)
        ("\\nindex{*}" "name" ?n "" nil nil)
        ("\\astobj{*}" "idx" ?o "Astronomical Objects!" nil t)))

Note that the index tag is ‘idx’ for the main index, and ‘name’ for the name index. ‘idx’ and ‘glo’ are reserved for the default index and for the glossary.

The character arguments ?x, ?n, and ?o are for quick identification of these macros when RefTeX inserts new index entries with reftex-index. These codes need to be unique. ?i, ?I, and ?g are reserved for the \index, \index*, and \glossary macros, respectively.

The following string is empty unless your macro adds a superordinate entry to the index key; this is the case for the \astobj macro.

The next entry can be a hook function to exclude certain matches, it almost always can be nil.

The final element in the list indicates if the text being indexed needs to be repeated outside the macro. For the normal index macros, this should be t. Only if the macro typesets the entry in the text (like \ix and \nindex in the example do), this should be nil.

To do the same thing with customize, you need to fill in the templates like this:

Repeat:
[INS] [DEL] List:
            Macro with args: \ix{*}
            Index Tag      : [Value Menu] String: idx
            Access Key     : x
            Key Prefix     :
            Exclusion hook : nil
            Repeat Outside : [Toggle]  off (nil)
[INS] [DEL] List:
            Macro with args: \nindex{*}
            Index Tag      : [Value Menu] String: name
            Access Key     : n
            Key Prefix     :
            Exclusion hook : nil
            Repeat Outside : [Toggle]  off (nil)
[INS] [DEL] List:
            Macro with args: \astobj{*}
            Index Tag      : [Value Menu] String: idx
            Access Key     : o
            Key Prefix     : Astronomical Objects!
            Exclusion hook : nil
            Repeat Outside : [Toggle]  on (non-nil)
[INS]

With the macro \ix defined, you may want to change the default macro used for indexing a text phrase (see Creating Index Entries). This would be done like this

(setq reftex-index-default-macro '(?x "idx"))

which specifies that the macro identified with the character ?x (the \ix macro) should be used for indexing phrases and words already in the buffer with C-c / (reftex-index-selection-or-word). The index tag is "idx".

14.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⁹. 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¹⁰ 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 Referencing Labels).
• RefTeX tells AUCTeX about new labels, citation and index keys
  RefTeX will add all newly created labels to AUCTeX’s completion list.

14.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 (auctex)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¹¹ 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))))))

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

18.1 Table of Contents ¶

User Option: reftex-include-file-commands ¶

List of LaTeX commands which input another file. The file name is expected after the command, either in braces or separated by whitespace.

User Option: reftex-max-section-depth ¶

Maximum depth of section levels in document structure. Standard LaTeX needs 7, default is 12.

User Option: reftex-section-levels ¶

Commands and levels used for defining sections in the document. The car of each cons cell is the name of the section macro. The cdr is a number indicating its level. A negative level means the same as the positive value, but the section will never get a number. The cdr may also be a function which then has to return the level. This list is also used for promotion and demotion of sectioning commands. If you are using a document class which has several sets of sectioning commands, promotion only works correctly if this list is sorted first by set, then within each set by level. The promotion commands always select the nearest entry with the correct new level.

User Option: reftex-toc-max-level ¶

The maximum level of toc entries which will be included in the TOC. Section headings with a bigger level will be ignored. In RefTeX, chapters are level 1, sections level 2 etc. This variable can be changed from within the *toc* buffer with the t key.

User Option: reftex-part-resets-chapter ¶

Non-nil means, \part is like any other sectioning command. This means, part numbers will be included in the numbering of chapters, and chapter counters will be reset for each part. When nil (the default), parts are special, do not reset the chapter counter and also do not show up in chapter numbers.

User Option: reftex-auto-recenter-toc ¶

Non-nil means, turn automatic recentering of *TOC* window on. When active, the *TOC* window will always show the section you are currently working in. Recentering happens whenever Emacs is idle for more than reftex-idle-time seconds.

Value t means, turn on immediately when RefTeX gets started. Then, recentering will work for any toc window created during the session.

Value frame (the default) means, turn automatic recentering on only while the dedicated TOC frame does exist, and do the recentering only in that frame. So when creating that frame (with d key in an ordinary TOC window), the automatic recentering is turned on. When the frame gets destroyed, automatic recentering is turned off again.

This feature can be turned on and off from the menu (Ref->Options).

User Option: reftex-toc-split-windows-horizontally ¶

Non-nil means, create TOC window by splitting window horizontally. The default is to split vertically.

User Option: reftex-toc-split-windows-fraction ¶

Fraction of the width or height of the frame to be used for TOC window.

User Option: reftex-toc-keep-other-windows ¶

Non-nil means, split the selected window to display the *toc* buffer. This helps to keep the window configuration, but makes the *toc* small. When nil, all other windows except the selected one will be deleted, so that the *toc* window fills half the frame.

User Option: reftex-toc-include-file-boundaries ¶

Non-nil means, include file boundaries in *toc* buffer. This flag can be toggled from within the *toc* buffer with the i key.

User Option: reftex-toc-include-labels ¶

Non-nil means, include labels in *toc* buffer. This flag can be toggled from within the *toc* buffer with the l key.

User Option: reftex-toc-include-index-entries ¶

Non-nil means, include index entries in *toc* buffer. This flag can be toggled from within the *toc* buffer with the i key.

User Option: reftex-toc-include-context ¶

Non-nil means, include context with labels in the *toc* buffer. Context will only be shown if the labels are visible as well. This flag can be toggled from within the *toc* buffer with the c key.

User Option: reftex-toc-follow-mode ¶

Non-nil means, point in *toc* buffer (the table-of-contents buffer) will cause other window to follow. The other window will show the corresponding part of the document. This flag can be toggled from within the *toc* buffer with the f key.

Normal Hook: reftex-toc-mode-hook ¶

Normal hook which is run when a *toc* buffer is created.

Keymap: reftex-toc-mode-map ¶

The keymap which is active in the *toc* buffer. (see Table of Contents).

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.

18.3 Creating Labels ¶

User Option: reftex-insert-label-flags ¶

Flags governing label insertion. The value has the form

(derive prompt)

If derive is t, RefTeX will try to derive a sensible label from context. A section label for example will be derived from the section heading. The conversion of the context to a valid label is governed by the specifications given in reftex-derive-label-parameters. If derive is nil, the default label will consist of the prefix and a unique number, like ‘eq:23’.

If prompt is t, the user will be prompted for a label string. When prompt is nil, the default label will be inserted without query.

So the combination of derive and prompt controls label insertion. Here is a table describing all four possibilities:

derive prompt action
-----------------------------------------------------------
nil    nil    Insert simple label, like ‘eq:22’ or ‘sec:13’. No query.
nil    t      Prompt for label.
t      nil    Derive a label from context and insert. No query.
t      t      Derive a label from context, prompt for confirmation.

Each flag may be set to t, nil, or a string of label type letters indicating the label types for which it should be true. Thus, the combination may be set differently for each label type. The default settings ‘"s"’ and ‘"sft"’ mean: Derive section labels from headings (with confirmation). Prompt for figure and table labels. Use simple labels without confirmation for everything else.

The available label types are: s (section), f (figure), t (table), i (item), e (equation), n (footnote), N (endnote) plus any definitions in reftex-label-alist.

Hook: reftex-format-label-function ¶

If non-nil, should be a function which produces the string to insert as a label definition. The function will be called with two arguments, the label and the default-format (usually ‘\label{%s}’). It should return the string to insert into the buffer.

Hook: reftex-string-to-label-function ¶

Function to turn an arbitrary string into a valid label. RefTeX’s default function uses the variable reftex-derive-label-parameters.

Hook: reftex-translate-to-ascii-function ¶

Filter function which will process a context string before it is used to derive a label from it. The intended application is to convert ISO or Mule characters into something valid in labels. The default function reftex-latin1-to-ascii removes the accents from Latin-1 characters. X-Symbol (>=2.6) sets this variable to the much more general x-symbol-translate-to-ascii.

User Option: reftex-derive-label-parameters ¶

Parameters for converting a string into a label. This variable is a list of the following items:

nwords

Number of words to use.

maxchar

Maximum number of characters in a label string.

invalid

nil: Throw away any words containing characters invalid in labels.
t: Throw away only the invalid characters, not the whole word.

abbrev

nil: Never abbreviate words.
t: Always abbreviate words (see reftex-abbrev-parameters).
1: Abbreviate words if necessary to shorten label string.

separator

String separating different words in the label.

ignorewords

List of words which should not be part of labels.

downcase

t: Downcase words before putting them into the label.

User Option: reftex-label-illegal-re ¶

Regexp matching characters not valid in labels.

User Option: reftex-abbrev-parameters ¶

Parameters for abbreviation of words. A list of four parameters.

min-chars

Minimum number of characters remaining after abbreviation.

min-kill

Minimum number of characters to remove when abbreviating words.

before

Character class before abbrev point in word.

after

Character class after abbrev point in word.

18.4 Referencing Labels ¶

User Option: reftex-label-menu-flags ¶

List of flags governing the label menu makeup. The flags are:

table-of-contents

Show the labels embedded in a table of context.

section-numbers

Include section numbers (like 4.1.3) in table of contents.

counters

Show counters. This just numbers the labels in the menu.

no-context

Non-nil means do not show the short context.

follow

Follow full context in other window.

show-commented

Show labels from regions which are commented out.

match-everywhere

Obsolete flag.

show-files

Show begin and end of included files.

Each of these flags can be set to t or nil, or to a string of type letters indicating the label types for which it should be true. These strings work like character classes in regular expressions. Thus, setting one of the flags to ‘"sf"’ makes the flag true for section and figure labels, nil for everything else. Setting it to ‘"^sf"’ makes it the other way round.

The available label types are: s (section), f (figure), t (table), i (item), e (equation), n (footnote), plus any definitions in reftex-label-alist.

Most options can also be switched from the label menu itself, so if you decide here to not have a table of contents in the label menu, you can still get one interactively during selection from the label menu.

User Option: reftex-multiref-punctuation ¶

Punctuation strings for multiple references. When marking is used in the selection buffer to select several references, this variable associates the 3 marking characters ‘,-+’ with prefix strings to be inserted into the buffer before the corresponding \ref macro. This is used to string together whole reference sets, like ‘eqs. 1,2,3-5,6 and 7’ in a single call to reftex-reference.

User Option: reftex-ref-style-alist ¶

Alist of reference styles. Each element is a list of the style name, the name of the LaTeX package associated with the style or t for any package, and an alist of macros where the first entry of each item is the reference macro and the second a key for selecting the macro when the macro type is being prompted for. (See also reftex-ref-macro-prompt.) The keys, represented as characters, have to be unique.

User Option: reftex-ref-style-default-list ¶

List of reference styles to be activated by default. The order is significant and controls the order in which macros can be cycled in the buffer for selecting a label. The entries in the list have to match the respective reference style names used in the variable reftex-ref-style-alist.

User Option: reftex-ref-macro-prompt ¶

Controls if reftex-reference prompts for the reference macro.

Hook: reftex-format-ref-function ¶

If non-nil, should be a function which produces the string to insert as a reference. Note that the insertion format can also be changed with reftex-label-alist. This hook also is used by the special commands to insert, e.g., \vref and \fref references, so even if you set this, your setting will be ignored by the special commands. The function will be called with three arguments, the label, the default format which normally is ‘~\ref{%s}’ and the reference style. The function should return the string to insert into the buffer.

User Option: reftex-level-indent ¶

Number of spaces to be used for indentation per section level.

User Option: reftex-guess-label-type ¶

Non-nil means, reftex-reference will try to guess the label type. To do that, RefTeX will look at the word before the cursor and compare it with the magic words given in reftex-label-alist. When it finds a match, RefTeX will immediately offer the correct label menu; otherwise it will prompt you for a label type. If you set this variable to nil, RefTeX will always prompt for a label type.

Normal Hook: reftex-display-copied-context-hook ¶

Normal Hook which is run before context is displayed anywhere. Designed for X-Symbol, but may have other uses as well.

Hook: reftex-pre-refontification-functions ¶

X-Symbol specific hook. Probably not useful for other purposes. The functions get two arguments, the buffer from where the command started and a symbol indicating in what context the hook is called.

Normal Hook: reftex-select-label-mode-hook ¶

Normal hook which is run when a selection buffer enters reftex-select-label-mode.

Keymap: reftex-select-label-mode-map ¶

The keymap which is active in the labels selection process (see Referencing Labels).

18.5 Creating Citations ¶

User Option: reftex-bibliography-commands ¶

LaTeX commands which specify the BibTeX databases to use with the document.

User Option: reftex-bibfile-ignore-regexps ¶

List of regular expressions to exclude files in \\bibliography{..}. File names matched by any of these regexps will not be parsed. Intended for files which contain only @string macro definitions and the like, which are ignored by RefTeX anyway.

User Option: reftex-default-bibliography ¶

List of BibTeX database files which should be used if none are specified. When reftex-citation is called from a document with neither a ‘\bibliography{...}’ statement nor a thebibliography environment, RefTeX will scan these files instead. Intended for using reftex-citation in non-LaTeX files. The files will be searched along the BIBINPUTS or TEXBIB path.

User Option: reftex-sort-bibtex-matches ¶

Sorting of the entries found in BibTeX databases by reftex-citation. Possible values:

nil          Do not sort entries.
author       Sort entries by author name.
year         Sort entries by increasing year.
reverse-year Sort entries by decreasing year.

User Option: reftex-cite-format ¶

The format of citations to be inserted into the buffer. It can be a string, an alist or a symbol. In the simplest case this is just the string ‘\cite{%l}’, which is also the default. See the definition of reftex-cite-format-builtin for more complex examples.

If reftex-cite-format is a string, it will be used as the format. In the format, the following percent escapes will be expanded.

%l

The BibTeX label of the citation.

%a

List of author names, see also reftex-cite-punctuation.

%2a

Like %a, but abbreviate more than 2 authors like Jones et al.

%A

First author name only.

%e

Works like ‘%a’, but on list of editor names. (‘%2e’ and ‘%E’ work a well).

It is also possible to access all other BibTeX database fields:

%b booktitle     %c chapter        %d edition    %h howpublished
%i institution   %j journal        %k key        %m month
%n number        %o organization   %p pages      %P first page
%r address       %s school         %u publisher  %t title
%v volume        %y year
%B booktitle, abbreviated          %T title, abbreviated

Usually, only ‘%l’ is needed. The other stuff is mainly for the echo area display, and for (setq reftex-comment-citations t).

‘%<’ as a special operator kills punctuation and space around it after the string has been formatted.

A pair of square brackets indicates an optional argument, and RefTeX will prompt for the values of these arguments.

Beware that all this only works with BibTeX database files. When citations are made from the \bibitems in an explicit thebibliography environment, only ‘%l’ is available.

If reftex-cite-format is an alist of characters and strings, the user will be prompted for a character to select one of the possible format strings.

In order to configure this variable, you can either set reftex-cite-format directly yourself or set it to the symbol of one of the predefined styles. The predefined symbols are those which have an association in the constant reftex-cite-format-builtin) E.g.: (setq reftex-cite-format 'natbib).

Hook: reftex-format-cite-function ¶

If non-nil, should be a function which produces the string to insert as a citation. Note that the citation format can also be changed with the variable reftex-cite-format. The function will be called with two arguments, the citation-key and the default-format (taken from reftex-cite-format). It should return the string to insert into the buffer.

User Option: reftex-cite-prompt-optional-args ¶

Non-nil means, prompt for empty optional arguments in cite macros. When an entry in reftex-cite-format is given with square brackets to indicate optional arguments (for example ‘\\cite[][]{%l}’), RefTeX can prompt for values. Possible values are:

nil     Never prompt for optional arguments
t       Always prompt
maybe   Prompt only if reftex-citation was called with C-u prefix arg

Unnecessary empty optional arguments are removed before insertion into the buffer. See reftex-cite-cleanup-optional-args.

User Option: reftex-cite-cleanup-optional-args ¶

Non-nil means, remove empty optional arguments from cite macros if possible.

User Option: reftex-comment-citations ¶

Non-nil means add a comment for each citation describing the full entry. The comment is formatted according to reftex-cite-comment-format.

User Option: reftex-cite-comment-format ¶

Citation format used for commented citations. Must not contain ‘%l’. See the variable reftex-cite-format for possible percent escapes.

User Option: reftex-cite-punctuation ¶

Punctuation for formatting of name lists in citations. This is a list of 3 strings.

1. normal names separator, like ‘, ’ in Jones, Brown and Miller
2. final names separator, like ‘ and ’ in Jones, Brown and Miller
3. The ‘et al.’ string, like ‘ {\it et al.}’ in Jones {\it et al.}

Normal Hook: reftex-select-bib-mode-hook ¶

Normal hook which is run when a selection buffer enters reftex-select-bib-mode.

Keymap: reftex-select-bib-mode-map ¶

The keymap which is active in the citation-key selection process (see Creating Citations).

User Option: reftex-cite-key-separator ¶

String used to separate several keys in a single ‘\\cite’ macro. Per default this is ‘","’ but if you often have to deal with a lot of entries and need to break the macro across several lines you might want to change it to ‘", "’.

User Option: reftex-create-bibtex-header ¶

Header to insert in BibTeX files generated by reftex-create-bibtex-file.

User Option: reftex-create-bibtex-footer ¶

Footer to insert in BibTeX files generated by reftex-create-bibtex-file.

18.6 Index Support ¶

User Option: reftex-support-index ¶

Non-nil means, index entries are parsed as well. Index support is resource intensive and the internal structure holding the parsed information can become quite big. Therefore it can be turned off. When this is nil and you execute a command which requires index support, you will be asked for confirmation to turn it on and rescan the document.

User Option: reftex-index-special-chars ¶

List of special characters in index entries, given as strings. These correspond to the MakeIndex keywords (level encap actual quote escape).

User Option: reftex-index-macros ¶

List of macros which define index entries. The structure of each entry is

(macro index-tag key prefix exclude repeat)

macro is the macro. Arguments should be denoted by empty braces, as for example in ‘\index[]{*}’. Use square brackets to denote optional arguments. The star marks where the index key is.

index-tag is a short name of the index. ‘idx’ and ‘glo’ are reserved for the default index and the glossary. Other indices can be defined as well. If this is an integer, the Nth argument of the macro holds the index tag.

key is a character which is used to identify the macro for input with reftex-index. ‘?i’, ‘?I’, and ‘?g’ are reserved for default index and glossary.

prefix can be a prefix which is added to the key part of the index entry. If you have a macro \newcommand{\molec}[1]{#1\index{Molecules!#1}, this prefix should be ‘Molecules!’.

exclude can be a function. If this function exists and returns a non-nil value, the index entry at point is ignored. This was implemented to support the (deprecated) ‘^’ and ‘_’ shortcuts in the LaTeX2e index package.

repeat, if non-nil, means the index macro does not typeset the entry in the text, so that the text has to be repeated outside the index macro. Needed for reftex-index-selection-or-word and for indexing from the phrase buffer.

The final entry may also be a symbol. It must have an association in the variable reftex-index-macros-builtin to specify the main indexing package you are using. Valid values are currently

default         The LaTeX default; unnecessary to specify this one
multind         The multind.sty package
index           The index.sty package
index-shortcut  The index.sty packages with the ^ and _ shortcuts.
                Should not be used; only for old documents

Note that AUCTeX sets these things internally for RefTeX as well, so with a sufficiently new version of AUCTeX, you should not set the package here.

User Option: reftex-index-default-macro ¶

The default index macro for reftex-index-selection-or-word. This is a list with (macro-key default-tag).

macro-key is a character identifying an index macro; see reftex-index-macros.

default-tag is the tag to be used if the macro requires a tag argument. When this is nil and a tag is needed, RefTeX will ask for it. When this is the empty string and the TAG argument of the index macro is optional, the TAG argument will be omitted.

User Option: reftex-index-default-tag ¶

Default index tag. When working with multiple indexes, RefTeX queries for an index tag when creating index entries or displaying a specific index. This variable controls the default offered for these queries. The default can be selected with RET during selection or completion. Valid values of this variable are:

nil        Do not provide a default index
"tag"      The default index tag given as a string, e.g., "idx"
last       The last used index tag will be offered as default

User Option: reftex-index-math-format ¶

Format of index entries when copied from inside math mode. When reftex-index-selection-or-word is executed inside TeX math mode, the index key copied from the buffer is processed with this format string through the format function. This can be used to add the math delimiters (e.g., ‘$’) to the string. Requires the texmathp.el library which is part of AUCTeX.

User Option: reftex-index-phrase-file-extension ¶

File extension for the index phrase file. This extension will be added to the base name of the master file.

User Option: reftex-index-phrases-logical-and-regexp ¶

Regexp matching the ‘and’ operator for index arguments in phrases file. When several index arguments in a phrase line are separated by this operator, each part will generate an index macro. So each match of the search phrase will produce several different index entries. Make sure this does no match things which are not separators. This logical ‘and’ has higher priority than the logical ‘or’ specified in reftex-index-phrases-logical-or-regexp.

User Option: reftex-index-phrases-logical-or-regexp ¶

Regexp matching the ‘or’ operator for index arguments in phrases file. When several index arguments in a phrase line are separated by this operator, the user will be asked to select one of them at each match of the search phrase. The first index arg will be the default. A number key 1–9 must be pressed to switch to another. Make sure this does no match things which are not separators. The logical ‘and’ specified in reftex-index-phrases-logical-or-regexp has higher priority than this logical ‘or’.

User Option: reftex-index-phrases-search-whole-words ¶

Non-nil means phrases search will look for whole words, not subwords. This works by requiring word boundaries at the beginning and end of the search string. When the search phrase already has a non-word-char at one of these points, no word boundary is required there.

User Option: reftex-index-phrases-case-fold-search ¶

Non-nil means, searching for index phrases will ignore case.

User Option: reftex-index-verify-function ¶

A function which is called at each match during global indexing. If the function returns nil, the current match is skipped.

User Option: reftex-index-phrases-skip-indexed-matches ¶

Non-nil means, skip matches which appear to be indexed already. When doing global indexing from the phrases buffer, searches for some phrases may match at places where that phrase was already indexed. In particular when indexing an already processed document again, this will even be the norm. When this variable is non-nil, RefTeX checks if the match is an index macro argument, or if an index macro is directly before or after the phrase. If that is the case, that match will be ignored.

User Option: reftex-index-phrases-wrap-long-lines ¶

Non-nil means, when indexing from the phrases buffer, wrap lines. Inserting indexing commands in a line makes the line longer, often so long that it does not fit onto the screen. When this variable is non-nil, newlines will be added as necessary before and/or after the indexing command to keep lines short. However, the matched text phrase and its index command will always end up on a single line.

User Option: reftex-index-phrases-sort-prefers-entry ¶

Non-nil means when sorting phrase lines, the explicit index entry is used. Phrase lines in the phrases buffer contain a search phrase, and sorting is normally based on these. Some phrase lines also have an explicit index argument specified. When this variable is non-nil, the index argument will be used for sorting.

User Option: reftex-index-phrases-sort-in-blocks ¶

Non-nil means, empty and comment lines separate phrase buffer into blocks. Sorting will then preserve blocks, so that lines are re-arranged only within blocks.

User Option: reftex-index-phrases-mode-map ¶

Keymap for the Index Phrases buffer.

User Option: reftex-index-phrases-mode-hook ¶

Normal hook which is run when a buffer is put into reftex-index-phrases-mode.

User Option: reftex-index-section-letters ¶

The letters which denote sections in the index. Usually these are all capital letters. Don’t use any downcase letters. Order is not significant, the index will be sorted by whatever the sort function thinks is correct. In addition to these letters, RefTeX will create a group ‘!’ which contains all entries sorted below the lowest specified letter. In the *Index* buffer, pressing any of these capital letters or ! will jump to that section.

User Option: reftex-index-include-context ¶

Non-nil means, display the index definition context in the *Index* buffer. This flag may also be toggled from the *Index* buffer with the c key.

User Option: reftex-index-follow-mode ¶

Non-nil means, point in *Index* buffer will cause other window to follow. The other window will show the corresponding part of the document. This flag can be toggled from within the *Index* buffer with the f key.

Keymap: reftex-index-mode-map ¶

The keymap which is active in the *Index* buffer (see Index Support).

18.7 Viewing Cross-References ¶

User Option: reftex-view-crossref-extra ¶

Macros which can be used for the display of cross references. This is used when reftex-view-crossref is called with point in an argument of a macro. Note that crossref viewing for citations, references (both ways) and index entries is hard-coded. This variable is only to configure additional structures for which crossreference viewing can be useful. Each entry has the structure

(macro-re search-re highlight).

macro-re is matched against the macro. search-re is the regexp used to search for cross references. ‘%s’ in this regexp is replaced with the macro argument at point. highlight is an integer indicating which subgroup of the match should be highlighted.

User Option: reftex-auto-view-crossref ¶

Non-nil means, initially turn automatic viewing of crossref info on. Automatic viewing of crossref info normally uses the echo area. Whenever point is idle for more than reftex-idle-time seconds on the argument of a \ref or \cite macro, and no other message is being displayed, the echo area will display information about that cross reference. You can also set the variable to the symbol window. In this case a small temporary window is used for the display. This feature can be turned on and off from the menu (Ref->Options).

User Option: reftex-idle-time ¶

Time (secs) Emacs has to be idle before automatic crossref display or toc recentering is done.

User Option: reftex-cite-view-format ¶

Citation format used to display citation info in the message area. See the variable reftex-cite-format for possible percent escapes.

User Option: reftex-revisit-to-echo ¶

Non-nil means, automatic citation display will revisit files if necessary. When nil, citation display in echo area will only be active for cached echo strings (see reftex-cache-cite-echo), or for BibTeX database files which are already visited by a live associated buffers.

User Option: reftex-cache-cite-echo ¶

Non-nil means, the information displayed in the echo area for cite macros (see variable reftex-auto-view-crossref) is cached and saved along with the parsing information. The cache survives document scans. In order to clear it, use M-x reftex-reset-mode.

18.8 Finding Files ¶

User Option: reftex-texpath-environment-variables ¶

List of specifications how to retrieve the search path for TeX files. Several entries are possible.

• If an element is the name of an environment variable, its content is used.
• If an element starts with an exclamation mark, it is used as a command to retrieve the path. A typical command with the kpathsearch library would be "!kpsewhich -show-path=.tex".
• Otherwise the element itself is interpreted as a path.

Multiple directories can be separated by the system dependent path-separator. Directories ending in ‘//’ or ‘!!’ will be expanded recursively. See also reftex-use-external-file-finders.

User Option: reftex-bibpath-environment-variables ¶

List of specifications how to retrieve the search path for BibTeX files. Several entries are possible.

• If an element is the name of an environment variable, its content is used.
• If an element starts with an exclamation mark, it is used as a command to retrieve the path. A typical command with the kpathsearch library would be "!kpsewhich -show-path=.bib".
• Otherwise the element itself is interpreted as a path.

Multiple directories can be separated by the system dependent path-separator. Directories ending in ‘//’ or ‘!!’ will be expanded recursively. See also reftex-use-external-file-finders.

User Option: reftex-file-extensions ¶

Association list with file extensions for different file types. This is a list of items, each item is like: (type . (def-ext other-ext ...))

type:       File type like "bib" or "tex".
def-ext:    The default extension for that file type, like ".tex" or ".bib".
other-ext:  Any number of other valid extensions for this file type.

When a files is searched and it does not have any of the valid extensions, we try the default extension first, and then the naked file name.

User Option: reftex-search-unrecursed-path-first ¶

Non-nil means, search all specified directories before trying recursion. Thus, in a path ‘.//:/tex/’, search first ‘./’, then ‘/tex/’, and then all subdirectories of ‘./’. If this option is nil, the subdirectories of ‘./’ are searched before ‘/tex/’. This is mainly for speed; most of the time the recursive path is for the system files and not for the user files. Set this to nil if the default makes RefTeX finding files with equal names in wrong sequence.

User Option: reftex-use-external-file-finders ¶

Non-nil means, use external programs to find files. Normally, RefTeX searches the paths given in the environment variables TEXINPUTS and BIBINPUTS to find TeX files and BibTeX database files. With this option turned on, it calls an external program specified in the option reftex-external-file-finders instead. As a side effect, the variables reftex-texpath-environment-variables and reftex-bibpath-environment-variables will be ignored.

User Option: reftex-external-file-finders ¶

Association list with external programs to call for finding files. Each entry is a cons cell (type . program). type is either "tex" or "bib". program is a string containing the external program to use with any arguments. %f will be replaced by the name of the file to be found. Note that these commands will be executed directly, not via a shell. Only relevant when reftex-use-external-file-finders is non-nil.

18.9 Optimizations ¶

User Option: reftex-keep-temporary-buffers ¶

Non-nil means, keep buffers created for parsing and lookup. RefTeX sometimes needs to visit files related to the current document. We distinguish files visited for

PARSING

Parts of a multifile document loaded when (re)-parsing the document.

LOOKUP

BibTeX database files and TeX files loaded to find a reference, to display label context, etc.

The created buffers can be kept for later use, or be thrown away immediately after use, depending on the value of this variable:

nil

Throw away as much as possible.

t

Keep everything.

1

Throw away buffers created for parsing, but keep the ones created for lookup.

If a buffer is to be kept, the file is visited normally (which is potentially slow but will happen only once). If a buffer is to be thrown away, the initialization of the buffer depends upon the variable reftex-initialize-temporary-buffers.

User Option: reftex-initialize-temporary-buffers ¶

Non-nil means do initializations even when visiting file temporarily. When nil, RefTeX may turn off find-file hooks and other stuff to briefly visit a file. When t, the full default initializations are done (find-file-hook etc.). Instead of t or nil, this variable may also be a list of hook functions to do a minimal initialization.

User Option: reftex-no-include-regexps ¶

List of regular expressions to exclude certain input files from parsing. If the name of a file included via \include or \input is matched by any of the regular expressions in this list, that file is not parsed by RefTeX.

User Option: reftex-enable-partial-scans ¶

Non-nil means, re-parse only 1 file when asked to re-parse. Re-parsing is normally requested with a C-u prefix to many RefTeX commands, or with the r key in menus. When this option is t in a multifile document, we will only parse the current buffer, or the file associated with the label or section heading near point in a menu. Requesting re-parsing of an entire multifile document then requires a C-u C-u prefix or the capital R key in menus.

User Option: reftex-save-parse-info ¶

Non-nil means, save information gathered with parsing in files. The file MASTER.rel in the same directory as MASTER.tex is used to save the information. When this variable is t,

• accessing the parsing information for the first time in an editing session will read that file (if available) instead of parsing the document.
• exiting Emacs or killing a buffer in reftex-mode will cause a new version of the file to be written.

User Option: reftex-parse-file-extension ¶

File extension for the file in which parser information is stored. This extension is added to the base name of the master file.

User Option: reftex-allow-automatic-rescan ¶

Non-nil means, RefTeX may rescan the document when this seems necessary. Applies (currently) only in rare cases, when a new label cannot be placed with certainty into the internal label list.

User Option: reftex-use-multiple-selection-buffers ¶

Non-nil means use a separate selection buffer for each label type. These buffers are kept from one selection to the next and need not be created for each use, so the menu generally comes up faster. The selection buffers will be erased (and therefore updated) automatically when new labels in its category are added. See the variable reftex-auto-update-selection-buffers.

User Option: reftex-auto-update-selection-buffers ¶

Non-nil means, selection buffers will be updated automatically. When a new label is defined with reftex-label, all selection buffers associated with that label category are emptied, in order to force an update upon next use. When nil, the buffers are left alone and have to be updated by hand, with the g key from the label selection process. The value of this variable will only have any effect when reftex-use-multiple-selection-buffers is non-nil.

18.10 Fontification ¶

User Option: reftex-use-fonts ¶

Non-nil means, use fonts in label menu and on-the-fly help. Font-lock must be loaded as well to actually get fontified display. After changing this option, a rescan may be necessary to activate it.

User Option: reftex-refontify-context ¶

Non-nil means, re-fontify the context in the label menu with font-lock. This slightly slows down the creation of the label menu. It is only necessary when you definitely want the context fontified.

This option may have 3 different values:

nil

Never refontify.

t

Always refontify.

1

Refontify when necessary, e.g., with old versions of the x-symbol package.

The option is ignored when reftex-use-fonts is nil.

User Option: reftex-highlight-selection ¶

Non-nil means, highlight selected text in selection and *toc* buffers. Normally, the text near the cursor is the selected text, and it is highlighted. This is the entry most keys in the selection and *toc* buffers act on. However, if you mainly use the mouse to select an item, you may find it nice to have mouse-triggered highlighting instead or as well. The variable may have one of these values:

nil      No highlighting.
cursor   Highlighting is cursor driven.
mouse    Highlighting is mouse driven.
both     Both cursor and mouse trigger highlighting.

Changing this variable requires rebuilding the selection and *toc* buffers to become effective (keys g or r).

User Option: reftex-cursor-selected-face ¶

Face name to highlight cursor selected item in toc and selection buffers. See also the variable reftex-highlight-selection.

User Option: reftex-mouse-selected-face ¶

Face name to highlight mouse selected item in toc and selection buffers. See also the variable reftex-highlight-selection.

User Option: reftex-file-boundary-face ¶

Face name for file boundaries in selection buffer.

User Option: reftex-label-face ¶

Face name for labels in selection buffer.

User Option: reftex-section-heading-face ¶

Face name for section headings in toc and selection buffers.

User Option: reftex-toc-header-face ¶

Face name for the header of a toc buffer.

User Option: reftex-bib-author-face ¶

Face name for author names in bib selection buffer.

User Option: reftex-bib-year-face ¶

Face name for year in bib selection buffer.

User Option: reftex-bib-title-face ¶

Face name for article title in bib selection buffer.

User Option: reftex-bib-extra-face ¶

Face name for bibliographic information in bib selection buffer.

User Option: reftex-select-mark-face ¶

Face name for marked entries in the selection buffers.

User Option: reftex-index-header-face ¶

Face name for the header of an index buffer.

User Option: reftex-index-section-face ¶

Face name for the start of a new letter section in the index.

User Option: reftex-index-tag-face ¶

Face name for index names (for multiple indices).

User Option: reftex-index-face ¶

Face name for index entries.

18.11 Miscellaneous ¶

User Option: reftex-extra-bindings ¶

Non-nil means, make additional key bindings on startup. These extra bindings are located in the users ‘C-c letter’ map. See Default Key Bindings.

User Option: reftex-plug-into-AUCTeX ¶

Plug-in flags for AUCTeX interface. This variable is a list of 5 boolean flags. When a flag is non-nil, RefTeX will

- supply labels in new sections and environments  (flag 1)
- supply arguments for macros like \label         (flag 2)
- supply arguments for macros like \ref           (flag 3)
- supply arguments for macros like \cite          (flag 4)
- supply arguments for macros like \index         (flag 5)

You may also set the variable itself to t or nil in order to turn all options on or off, respectively.
Supplying labels in new sections and environments applies when creating sections with C-c C-s and environments with C-c C-e.
Supplying macro arguments applies when you insert such a macro interactively with C-c RET.
See the AUCTeX documentation for more information.

User Option: reftex-revisit-to-follow ¶

Non-nil means, follow-mode will revisit files if necessary. When nil, follow-mode will be suspended for stuff in unvisited files.

User Option: reftex-allow-detached-macro-args ¶

Non-nil means, allow arguments of macros to be detached by whitespace. When this is t, the ‘aaa’ in ‘\bbb [xxx] {aaa}’ will be considered an argument of \bb. Note that this will be the case even if \bb is defined with zero or one argument.

18.12 Keymaps and Hooks ¶

RefTeX has the usual general keymap, load hook and mode hook.

Keymap: reftex-mode-map ¶

The keymap for RefTeX mode.

Normal Hook: reftex-mode-hook ¶

Normal hook which is being run when turning on RefTeX mode.

Furthermore, the four modes used for referencing labels, creating citations, the table of contents buffer and the phrases buffer have their own keymaps and mode hooks. See the respective sections. There are many more hooks which are described in the relevant sections about options for a specific part of RefTeX.