| [Top] | [Contents] | [Index] | [ ? ] |
RefTeX is a package for managing Labels, References, Citations and index entries with GNU Emacs.
Don't be discouraged by the size of this manual, which covers RefTeX in great depth. All you need to know to use RefTeX can be summarized on two pages (see section 1.4 RefTeX in a Nutshell). You can go back later to other parts of this document when needed.
1. Introduction Quick-Start information.
2. Table of Contents A Tool to move around quickly. 3. Labels and References Creating and referencing labels. 4. Citations Creating Citations. 5. Index Support Creating and Checking Index Entries. 6. Viewing Cross--References Who references or cites what?
6.1 RefTeX's Menu The Ref menu in the menubar. 6.2 Default Key Bindings The default key bindings. 6.3 Faces Fontification of RefTeX's buffers. 6.4 Multifile Documents Document spread over many files. 6.5 Language Support How to support other languages. 6.6 Finding Files Included TeX files and BibTeX .bib files. 6.8 AUC TeX Cooperation with AUCTeX. 6.7 Optimizations When RefTeX is too slow. 6.9 Problems and Work-arounds First Aid. 6.10 Imprint Author, Web-site, Thanks
7. Commands Which are the available commands. 8. Options, Keymaps, Hooks How to extend and configure RefTeX. 8.12 Keymaps and Hooks For customization. 9. Changes A List of recent changes to RefTeX.
The Index
Index The full index.
Introduction
1.1 Installation How to install and activate RefTeX. 1.4 RefTeX in a Nutshell A brief summary and quick guide.
Labels and References
3.1 Creating Labels 3.2 Referencing Labels 3.3 Builtin Label Environments The environments RefTeX knows about. 3.4 Defining Label Environments ... and environments it doesn't. 3.5 Reference Info View the label corresponding to a \ref. 3.6 xr: Cross-Document ReferencesReferences to external documents. 3.7 varioref: Variable Page ReferencesHow to create \vref instead of \ref. 3.8 fancyref: Fancy Cross ReferencesHow to create \fref instead of \ref.
Defining Label Environments
3.4.1 Theorem and Axiom Environments Defined with \newenvironment.3.4.2 Quick Equation Macro When a macro sets the label type. 3.4.3 Figure Wrapping Macro When a macro argument is a label. 3.4.4 Adding Magic Words Other words for other languages. 3.4.5 Using \eqrefHow to switch to this AMS-LaTeX macro. 3.4.6 Non-standard Environments Environments without \begin and \end 3.4.7 Putting it all together How to combine many entries.
Citations
4.1 Creating Citations How to create them. 4.2 Citation Styles Natbib, Harvard, Chicago and Co. 4.3 Citation Info View the corresponding database entry. 4.4 Chapterbib and Bibunits Multiple bibliographies in a Document. 4.5 Citations outside LaTeX How to make citations in Emails etc.
Index Support
5.1 Creating Index Entries Macros and completion of entries. 5.2 The Index Phrases File A special file for global indexing. 5.3 Displaying and Editing the Index The index editor. 5.4 Builtin Index Macros The index macros RefTeX knows about. 5.5 Defining Index Macros ... and macros it doesn't.
The Index Phrases File
5.2.1 Collecting Phrases Collecting from document or external. 5.2.2 Consistency Checks Check for duplicates etc. 5.2.3 Global Indexing The interactive indexing process.
AUCTeX
6.8.1 The AUCTeX-RefTeX Interface How both packages work together 6.8.2 Style Files AUCTeX's style files can support RefTeX 6.8.3 Bib-Cite Hypertext reading of a document
Options, Keymaps, Hooks
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX is a specialized package for support of labels,
references, citations, and the index in LaTeX. RefTeX wraps
itself round 4 LaTeX macros: \label, \ref, \cite,
and \index. Using these macros usually requires looking up
different parts of the document and searching through BibTeX database
files. RefTeX automates these time--consuming tasks almost
entirely. It also provides functions to display the structure of a
document and to move around in this structure quickly.
See section 6.10 Imprint, for information about who to contact for help, bug reports or suggestions.
1.1 Installation How to install and activate RefTeX. 1.4 RefTeX in a Nutshell A brief summary and quick guide.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX is bundled and pre--installed with Emacs since version 20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. XEmacs 21.x users want to install the corresponding plug-in package which is available from the XEmacs ftp site. See the XEmacs 21.x documentation on package installation for details.
Users of earlier Emacs distributions (including Emacs 19) can get a copy of the RefTeX distribution from the maintainers web-page. See section 6.10 Imprint, for more information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX needs to access all files which are part of a multifile
document, and the BibTeX database files requested by the
\bibliography command. To find these files, RefTeX will
require a search path, i.e. a list of directories to check. Normally
this list is stored in the environment variables TEXINPUTS and
BIBINPUTS which are also used by RefTeX. However, on some
systems these variables do not contain the full search path. If
RefTeX does not work for you because it cannot find some files,
read 6.6 Finding Files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To turn RefTeX Mode on and off in a particular buffer, use M-x reftex-mode. 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 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
reftex-label-alist).
reftex-label) to insert a label at point.
RefTeX will either
reftex-insert-label-flags.
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.
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).
reftex-index-macros). Multiple indices
are supported.
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.
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.
reftex-display-index). From that buffer you can check and edit
all entries.
\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.\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.
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').
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.
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.
(setq reftex-enable-partial-scans t) (setq reftex-save-parse-info t) (setq reftex-use-multiple-selection-buffers t) |
To integrate with AUCTeX, use
(setq reftex-plug-into-AUCTeX t) |
To make your own LaTeX macro definitions known to RefTeX, customize the variables
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Pressing the keys C-c = pops up a buffer showing the table of contents of the document. By default, this `*toc*' buffer shows only the sections of a document. Using the l and i keys you can display all labels and index entries defined in the document as well.
With the cursor in any of the lines denoting a location in the document, simple key strokes will display the corresponding part in another window, jump to that location, or perform other actions.
Here is a list of special commands in the `*toc*' buffer. A summary of this information is always available by pressing ?.
reftex-toc (C-c =) was
called.
reftex-highlight-selection, 8.10 Fontification.
reftex-toc-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.
reftex-toc was last called.
reftex-toc was last called.
reftex-toc was last called.
reftex-toc-max-level.
reftex-toc-include-file-boundaries.
reftex-toc-include-labels. When called with a prefix argument,
RefTeX will prompt for a label type and include only labels of
the selected type in the `*toc*' buffer. The mode line `L<>'
indicator shows which labels are included.
reftex-toc-include-index-entries. When called with a prefix
argument, RefTeX will prompt for a specific index and include
only entries in the selected index in the `*toc*' buffer. The mode
line `I<>' indicator shows which index is used.
reftex-toc-include-context.
reftex-enable-partial-scans is non-nil, rescan only the file this
location is defined in, not the entire document.
xr package (see section 3.6 xr: Cross-Document References), RefTeX will switch to one of the external
documents.
In order to define additional commands for the `*toc*' buffer, the
keymap reftex-toc-map may be used.
The section macros recognized by RefTeX are all LaTeX section
macros (from \part to \subsubparagraph) and the commands
\addchap and \addsec from the KOMA-Script classes.
Additional macros can be configured with the variable
reftex-section-levels. It is also possible to add certain LaTeX
environments to the table of contents. This is probably only useful for
theorem-like environments. See section 3.4 Defining Label Environments, for an
example.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
LaTeX provides a powerful mechanism to deal with cross--references in a document. When writing a document, any part of it can be marked with a label, like `\label{mark}'. LaTeX records the current value of a certain counter when a label is defined. Later references to this label (like `\ref{mark}') will produce the recorded value of the counter.
Labels can be used to mark sections, figures, tables, equations, footnotes, items in enumerate lists etc. LaTeX is context sensitive in doing this: A label defined in a figure environment automatically records the figure counter, not the section counter.
Several different environments can share a common counter and therefore
a common label category. E.g. labels in both equation and
eqnarray environments record the value of the same counter - the
equation counter.
3.1 Creating Labels 3.2 Referencing Labels 3.3 Builtin Label Environments The environments RefTeX knows about. 3.4 Defining Label Environments ... and environments it doesn't. 3.5 Reference Info View the label corresponding to a \ref. 3.6 xr: Cross-Document ReferencesReferences to external documents. 3.7 varioref: Variable Page ReferencesHow to create \vref instead of \ref. 3.8 fancyref: Fancy Cross ReferencesHow to create \fref instead of \ref.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
3 different modes to create this mark.
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 section 8.3 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 section 6.8 AUC TeX, for more information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, 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 the 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 to 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 ?.
reftex-revisit-to-follow.
reftex-reference.
reftex-highlight-selection, 8.11 Miscellaneous.\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) |
\ref macro. Some packages like
`saferef.sty' support multiple references in this way.
\ref and \vref macro for references. The
\vref macro is defined in the varioref LaTeX package.
With this key you can force RefTeX to insert a \vref
macro. The current state of this flag is displayed by the `S<>'
indicator in the mode line of the selection buffer.
\ref, \fref and \Fref. The
\fref and \Fref macros are defined in the fancyref
LaTeX package. With this key you can force RefTeX to insert a
\fref or \Fref macro. The current state of this flag is
displayed by the `S<>' indicator in the mode line of the
selection buffer.
reftex-label-menu-flags (see section 8.4 Referencing Labels).
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).
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 section xr).
In order to define additional commands for the selection process, the
keymap reftex-select-label-map may be used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)\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 section 3.4 Defining Label Environments).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX can be configured to recognize additional labeled
environments and macros. This is done with the variable
reftex-label-alist (see section 8.2 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 section 3.3 Builtin Label Environments).
3.4.1 Theorem and Axiom Environments Defined with \newenvironment.3.4.2 Quick Equation Macro When a macro sets the label type. 3.4.3 Figure Wrapping Macro When a macro argument is a label. 3.4.4 Adding Magic Words Other words for other languages. 3.4.5 Using \eqrefHow to switch to this AMS-LaTeX macro. 3.4.6 Non-standard Environments Environments without \begin and \end 3.4.7 Putting it all together How to combine many entries.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Suppose you are using \newtheorem in LaTeX in order to define two
new environments, theorem and axiom
\newtheorem{axiom}{Axiom}
\newtheorem{theorem}{Theorem}
|
to be used like this:
\begin{axiom}
\label{ax:first}
....
\end{axiom}
|
So we need to tell RefTeX that theorem and axiom are new
labeled environments which define their own label categories. We can
either use Lisp to do this (e.g. in `.emacs') or use the custom
library. With Lisp it would look like this
(setq reftex-label-alist
'(("axiom" ?a "ax:" "~\\ref{%s}" nil ("axiom" "ax.") -2)
("theorem" ?h "thr:" "~\\ref{%s}" t ("theorem" "th.") -3)))
|
The type indicator characters ?a and ?h are used for
prompts when RefTeX queries for a label type. ?h
was chosen for theorem since ?t is already taken by
table. Note that also ?s, ?f, ?e,
?i, ?n are already used for standard environments.
The labels for Axioms and Theorems will have the prefixes `ax:' and `thr:', respectively. See section 6.8 AUC TeX, for information on how AUCTeX can use RefTeX to automatically create labels when a new environment is inserted into a buffer.
The `~\ref{%s}' is a format string indicating how to insert references to these labels.
The next item indicates how to grab context of the label definition.
t means to get it from a default location (from the beginning of
a \macro or after the \begin statement). t is
not a good choice for eqnarray and similar environments.nil means to use the text right after the label definition.reftex-label-alist (8.2 Defining Label Environments).The following list of strings is used to guess the correct label type from the word before point when creating a reference. E.g. if you write: `As we have shown in Theorem' and then press C-c ), RefTeX will know that you are looking for a theorem label and restrict the menu to only these labels without even asking.
The final item in each entry is the level at which the environment
should produce entries in the table of context buffer. If the number is
positive, the environment will produce numbered entries (like
\section), if it is negative the entries will be unnumbered (like
\section*). Use this only for environments which structure the
document similar to sectioning commands. For everything else, omit the
item.
To do the same configuration with customize, you need to click on
the [INS] button twice to create two templates and fill them in
like this:
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
|
Depending on how you would like the label insertion and selection for
the new environments to work, you might want to add the letters `a'
and `h' to some of the flags in the variables
reftex-insert-label-flags (see section 8.3 Creating Labels)
and reftex-label-menu-flags (see section 8.4 Referencing Labels).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Suppose you would like to have a macro for quick equations. It could be defined like this:
\newcommand{\quickeq}[1]{\begin{equation} #1 \end{equation}}
|
and used like this:
Einstein's equation is \quickeq{E=mc^2 \label{eq:einstein}}.
|
We need to tell RefTeX that any label defined in the argument of the
\quickeq is an equation label. Here is how to do this with lisp:
(setq reftex-label-alist '(("\\quickeq{}" ?e nil nil 1 nil)))
|
The first element in this list is now the macro with empty braces as an
image of the macro arguments. ?e indicates that this is
an equation label, the different nil elements indicate to use the
default values for equations. The `1' as the fifth element
indicates that the context of the label definition should be the 1st
argument of the macro.
Here is again how this would look in the customization buffer:
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
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Suppose you want to make figures not directly with the figure environment, but with a macro like
\newcommand{\myfig}[5][tbp]{%
\begin{figure}[#1]
\epsimp[#5]{#2}
\caption{#3}
\label{#4}
\end{figure}}
|
which would be called like
\myfig[htp]{filename}{caption text}{label}{1}
|
Now we need to tell RefTeX that the 4th argument of the
\myfig macro is itself a figure label, and where to find
the context.
(setq reftex-label-alist
'(("\\myfig[]{}{}{*}{}" ?f nil nil 3)))
|
The empty pairs of brackets indicate the different arguments of the
\myfig macro. The `*' marks the label argument. ?f
indicates that this is a figure label which will be listed together with
labels from normal figure environments. The nil entries for
prefix and reference format mean to use the defaults for figure labels.
The `3' for the context method means to grab the 3rd macro argument
- the caption.
As a side effect of this configuration, reftex-label will now
insert the required naked label (without the \label macro) when
point is directly after the opening parenthesis of a \myfig macro
argument.
Again, here the configuration in the customization buffer:
[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
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes you don't want to define a new label environment or macro, but
just change the information associated with a label category. Maybe you
want to add some magic words, for another language. Changing only the
information associated with a label category is done by giving
nil for the environment name and then specify the items you want
to define. Here is an example which adds German magic words to all
predefined label categories.
(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"))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
\eqref
Another case where one only wants to change the information associated
with the label category is to change the macro which is used for
referencing the label. When working with the AMS-LaTeX stuff, you might
prefer \eqref for doing equation references. Here is how to
do this:
(setq reftex-label-alist '((nil ?e nil "~\\eqref{%s}" nil nil)))
|
RefTeX has also a predefined symbol for this special purpose. The following is equivalent to the line above.
(setq reftex-label-alist '(AMSTeX)) |
Note that this is automatically done by the `amsmath.el' style file of AUCTeX (see section 6.8.2 Style Files) - so if you use AUCTeX, this configuration will not be necessary.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some LaTeX packages define environment-like structures without using the
standard `\begin..\end' structure. RefTeX cannot parse
these directly, but you can write your own special-purpose parser and
use it instead of the name of an environment in an entry for
reftex-label-alist. The function should check if point is
currently in the special environment it was written to detect. If so,
it must return a buffer position indicating the start of this
environment. The return value must be nil on failure to detect
the environment. The function is called with one argument bound.
If non-nil, bound is a boundary for backwards searches
which should be observed. We will discuss two examples.
Some people define abbreviations for
environments, like \be for \begin{equation}, and
\ee for \end{equation}. The parser function would have
to search backward for these macros. When the first match is
\ee, point is not in this environment. When the first match is
\be, point is in this environment and the function must return
the beginning of the match. To avoid scanning too far, we can also look
for empty lines which cannot occure inside an equation environment.
Here is the setup:
;; 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
|
A more complex example is the `linguex.sty' package which defines list macros `\ex.', `\a.', `\b.' etc. for lists which are terminated by `\z.' or by an empty line.
\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
|
The difficulty is that the `\a.' lists can nest and that an empty line terminates all list levels in one go. So we have to count nesting levels between `\a.' and `\z.'. Here is the implementation for RefTeX.
(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))))))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When you have to put several entries into reftex-label-alist, just
put them after each other in a list, or create that many templates in
the customization buffer. Here is a lisp example which uses several of
the entries described above:
(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."))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When point is idle 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 section 6. Viewing Cross--References, for more
information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 6.7 Optimizations).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
varioref: Variable Page References varioref is a frequently used LaTeX package to create
cross--references with page information. When you want to make a
reference with the \vref macro, just press the v key in the
selection buffer to toggle between \ref and \vref
(see section 3.2 Referencing Labels). The mode line of the selection buffer
shows the current status of this switch. If you find that you almost
always use \vref, you may want to make it the default by
customizing the variable reftex-vref-is-default. If this
toggling seems too inconvenient, you can also use the command
reftex-varioref-vref(2).
Or use AUCTeX to create your macros (see section 6.8 AUC TeX).| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
fancyref: Fancy Cross References fancyref is a LaTeX 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. When you want to make a reference
with the \fref macro, just press the V key in the selection
buffer to cycle between \ref, \fref and \Fref
(see section 3.2 Referencing Labels). The mode line of the selection buffer
shows the current status of this switch. If this cycling seems
inconvenient, you can also use the commands reftex-fancyref-fref
and reftex-fancyref-Fref(3). Or use AUCTeX to create your macros
(see section 6.8 AUC TeX).| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Citations in LaTeX are done with the \cite macro or variations of
it. The argument of the macro is a citation key which identifies an
article or book in either a BibTeX database file or in an explicit
thebibliography environment in the document. RefTeX's
support for citations helps to select the correct key quickly.
4.1 Creating Citations How to create them. 4.2 Citation Styles Natbib, Harvard, Chicago and Co. 4.3 Citation Info View the corresponding database entry. 4.4 Chapterbib and Bibunits Multiple bibliographies in a Document. 4.5 Citations outside LaTeX How to make citations in Emails etc.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 3.2 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 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 ?.
reftex-highlight-selection, 8.11 Miscellaneous.
\cite macro referring to them.
\cite macro for each of it.
reftex-citation.
In order to define additional commands for this selection process, the
keymap reftex-select-bib-map may be used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 packages (natbib, harvard, chicago) 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}
|
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 section 6.8.2 Style Files, for information on how to set up the style
files correctly.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When point is idle 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 section 6. Viewing Cross--References.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)
(require 'reftex)
(let ((reftex-cite-format 'locally))
(reftex-citation))))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
LaTeX has builtin support for creating an Index. The LaTeX core supports two different indices, the standard index and a glossary. With the help of special LaTeX packages (`multind.sty' or `index.sty'), any number of indices can be supported.
Index entries are created with the \index{entry} macro.
All entries defined in a document are written out to the `.aux'
file. A separate tool must be used to convert this information into a
nicely formatted index. Tools used with LaTeX include MakeIndex
and xindy.
Indexing is a very difficult task. It must follow strict conventions to make the index consistent and complete. There are basically two approaches one can follow, and both have their merits.
Before you start, you need to make sure that RefTeX knows about
the index style being used in the current document. RefTeX has
builtin support for the default \index and \glossary
macros. Other LaTeX packages, like the `multind' or `index'
package, redefine the \index macro to have an additional
argument, and RefTeX needs to be configured for those. A
sufficiently new version of AUCTeX (9.10c or later) will do this
automatically. If you really don't use AUCTeX (you should!), this
configuration needs to be done by hand with the menu (Ref->Index
Style), or globally for all your documents with
(setq reftex-index-macros '(multind)) or (setq reftex-index-macros '(index)) |
5.1 Creating Index Entries Macros and completion of entries. 5.2 The Index Phrases File A special file for global indexing. 5.3 Displaying and Editing the Index The index editor. 5.4 Builtin Index Macros The index macros RefTeX knows about. 5.5 Defining Index Macros ... and macros it doesn't.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 5.5 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.
5.2.1 Collecting Phrases Collecting from document or external. 5.2.2 Consistency Checks Check for duplicates etc. 5.2.3 Global Indexing The interactive indexing process.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Phrases for indexing can be collected while writing the document. The
command C-c \ (reftex-index-phrase-selection-or-word)
copies the current selection (if active) or the word near point into the
phrases buffer. It then selects this buffer, so that the phrase line
can be edited. To return to the LaTeX document, press C-c C-c
(reftex-index-phrases-save-and-return).
You can also prepare the list of index phrases in a different way and copy it into the phrases file. For example you might want to start from a word list of the document and remove all words which should not be indexed.
The phrase lines in the phrase buffer must have a specific format. RefTeX will use font-lock to indicate if a line has the proper format. A phrase line looks like this:
[key] <TABs> phrase [<TABs> arg[&&arg]... [ || arg]...] |
<TABs> stands for white space containing at least one TAB.
key must be at the start of the line and is the character
identifying one of the macros defined in the file header. It is
optional - when omitted, the first macro definition line in the file
will be used for this phrase. The phrase is the phrase to be
searched for when indexing. It may contain several words separated by
spaces. By default the search phrase is also the text entered as
argument of the index macro. If you want the index entry to be
different from the search phrase, enter another TAB and the index
argument arg. If you want to have each match produce several
index entries, separate the different index arguments with ` &&
'(4). If you want to be
able to choose at each match between several different index arguments,
separate them with ` || '(5). Here is an
example:
%--------------------------------------------------------------------
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
|
So `Sun' will be indexed directly as `\index*{Sun}', while `Planet' will be indexed as `\index{Planets}Planet'. `Vega' will be indexed as a subitem of `Stars'. The `Jupiter' line will also use the `i' macro as it was the first macro definition in the file header (see above example). At each occurrence of `Mars' you will be able choose between indexing it as a subitem of `Planets', `Gods' or `Chocolate Bars'. Finally, every occurrence of `Pluto' will be indexed as `\index{Planets!Pluto}\index{Kuiper Belt Objects!Pluto}Pluto' and will therefore create two different index entries.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Before indexing the phrases in the phrases buffer, they should be
checked carefully for consistency. A first step is to sort the phrases
alphabetically - this is done with the command C-c C-s
(reftex-index-sort-phrases). It will sort all phrases in the
buffer alphabetically by search phrase. If you want to group certain
phrases and only sort within the groups, insert empty lines between the
groups. Sorting will only change the sequence of phrases within each
group (see the variable reftex-index-phrases-sort-in-blocks).
A useful command is C-c C-i (reftex-index-phrases-info)
which lists information about the phrase at point, including an example
of how the index entry will look like and the number of expected matches
in the document.
Another important check is to find out if there are double or
overlapping entries in the buffer. For example if you are first
searching and indexing `Mars' and then `Planet Mars', the
second phrase will not match because of the index macro inserted before
`Mars' earlier. The command C-c C-t
(reftex-index-find-next-conflict-phrase) finds the next phrase in
the buffer which is either duplicate or a subphrase of another phrase.
In order to check the whole buffer like this, start at the beginning and
execute this command repeatedly.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once the index phrases have been collected and organized, you are set for global indexing. I recommend to do this only on an otherwise finished document. Global indexing starts from the phrases buffer. There are several commands which start indexing: C-c C-x acts on the current phrase line, C-c C-r on all lines in the current region and C-c C-a on all phrase lines in the buffer. It is probably good to do indexing in small chunks since your concentration may not last long enough to do everything in one go.
RefTeX will start at the first phrase line and search the phrase globally in the whole document. At each match it will stop, compute the replacement string and offer you the following choices(6):
The `Find and Index in Document' menu in the phrases buffer also lists a few options for the indexing process. The options have associated customization variables to set the defaults (see section 8.6 Index Support). Here is a short explanation of what the options do:
reftex-index-macros. Intended for
re-indexing a documents after changes have been made.
Even though indexing should be the last thing you do to a document, you
are bound to make changes afterwards. Indexing then has to be applied
to the changed regions. The command
reftex-index-phrases-apply-to-region is designed for this
purpose. When called from a LaTeX document with active region, it will
apply reftex-index-all-phrases to the current region.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [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 ?.
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.
undo function for this.
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.
MakeIndex to change the visual
appearance of the entry in the index. When called with C-u
prefix, kill the entire visual part.
reftex-index-include-context.
R<> indicator in the
mode line and in the header of the `*Index*' buffer.
reftex-enable-partial-scans is non-nil, rescan only the file this
location is defined in, not the entire document.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 5.1 Creating Index Entries, for information on how to do that.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'(7). 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 section 5.1 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".
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX can display cross--referencing information. This means,
if two document locations are linked, RefTeX can display the
matching location(s) in another window. The \label and \ref
macros are one way of establishing such a link. Also, a \cite
macro is linked to the corresponding \bibitem macro or a BibTeX
database entry.
The feature is invoked by pressing C-c &
(reftex-view-crossref) while point is on the key argument
of a macro involved in cross--referencing. You can also click with
S-mouse-2 on the macro argument. Here is what will happen for
individual classes of macros:
\ref
\ref macro are active for
cross--reference display. This works also for labels defined in an
external document when the current document refers to them through the
xr interface (see section 3.6 xr: Cross-Document References).
\label
\label macro but also other macros
with label arguments (as configured with reftex-label-alist) are
active for cross--reference display.
\cite
\bibitem.
All usual variants(9) of the \cite macro are active for cross--reference
display.
\bibitem
\index
\index
and \glossary macros, all macros configured in
reftex-index-macros will be recognized.
While the display of cross referencing information for the above
mentioned macros is hard--coded, you can configure additional relations
in the variable reftex-view-crossref-extra.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX installs a Ref menu in the menu bar on systems
which support this. From this menu you can access all of
RefTeX's commands and a few of its options. There is also a
Customize submenu which can be used to access RefTeX's
entire set of options.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a summary of the available key bindings.
C-c = |
Note that the S-mouse-2 binding is only provided if this key is not already used by some other package. RefTeX will not override an existing binding to S-mouse-2.
Personally, I also bind some functions in the users C-c map for easier access.
C-c t |
These keys are reserved for the user, so I cannot bind them by default. If you want to have these key bindings available, set in your `.emacs' file:
(setq reftex-extra-bindings t) |
Changing and adding to RefTeX's key bindings is best done in the hook
reftex-load-hook. For information on the keymaps
which should be used to add keys, see 8.12 Keymaps and Hooks.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX uses faces when available to structure the selection and
table of contents buffers. It does not create its own faces, but uses
the ones defined in `font-lock.el'. Therefore, RefTeX will
use faces only when font-lock is loaded. This seems to be
reasonable because people who like faces will very likely have it
loaded. If you wish to turn off fontification or change the involved
faces, see 8.10 Fontification.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following is relevant when working with documents spread over many files:
grep, search and
query-replace on all files which are part of a multifile
document.
TeX-master for AUCTeX or tex-main-file for the
standard Emacs LaTeX mode) containing the name of the master file. For
example, to set the file variable TeX-master, include something
like the following at the end of each TeX file:
%%% Local Variables: *** %%% mode:latex *** %%% TeX-master: "thesis.tex" *** %%% End: *** |
AUCTeX with the setting
(setq-default TeX-master nil) |
will actually ask you for each new file about the master file and insert this comment automatically. For more details see the documentation of the AUCTeX (see section `Multifile' in The AUC TeX User Manual), the documentation about the Emacs (La)TeX mode (see section `TeX Print' in The GNU Emacs Manual) and the Emacs documentation on File Variables (see section `File Variables' in The GNU Emacs Manual).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some parts of RefTeX are language dependent. The default settings work well for English. If you are writing in a different language, the following hints may be useful:
reftex-derive-label-parameters and reftex-abbrev-parameters.
reftex-translate-to-ascii-function and
reftex-label-illegal-re.
reftex-multiref-punctuation and
reftex-cite-punctuation.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In order to find files included in a document via \input or
\include, RefTeX searches all directories specified in the
environment variable TEXINPUTS. Similarly, it will search the
path specified in the variables BIBINPUTS and TEXBIB for
BibTeX database files.
When searching, RefTeX will also expand recursive path definitions (directories ending in `//' or `!!'). But it will only search and expand directories explicitly given in these variables. This may cause problems under the following circumstances:
There are three ways to solve this problem:
TEXINPUTS and BIBINPUTS, define your own
variables and configure RefTeX to use them instead:
(setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
(setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
|
(setq reftex-texpath-environment-variables
'("./inp:/home/cd/tex//:/usr/local/tex//"))
(setq reftex-bibpath-environment-variables
'("/home/cd/tex/lit/"))
|
teTeX uses the
kpathsearch library which provides the command kpsewhich
to search for files. RefTeX can be configured to use this
program. Note that the exact syntax of the kpsewhich
command depends upon the version of that program.
(setq reftex-use-external-file-finders t)
(setq reftex-external-file-finders
'(("tex" . "kpsewhich -format=.tex %f")
("bib" . "kpsewhich -format=.bib %f")))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Implementing the principle of least surprises, the default settings of RefTeX ensure a safe ride for beginners and casual users. However, when using RefTeX for a large project and/or on a small computer, there are ways to improve speed or memory usage.
(setq reftex-keep-temporary-buffers nil) |
reftex-label
(C-u C-c (), reftex-reference (C-u C-c )),
reftex-citation (C-u C-c [), reftex-toc (C-u C-c
=), and reftex-view-crossref (C-u C-c &) initiates
re-parsing of the entire document in order to update the parsing
information. For a large document this can be unnecessary, in
particular if only one file has changed. RefTeX can be configured
to do partial scans instead of full ones. C-u re-parsing then
does apply only to the current buffer and files included from it.
Likewise, the r key in both the label selection buffer and the
table-of-contents buffer will only prompt scanning of the file in which
the label or section macro near the cursor was defined. Re-parsing of
the entire document is still available by using C-u C-u as a
prefix, or the capital R key in the menus. To use this feature,
try(setq reftex-enable-partial-scans t) |
reftex-mode or when you exit Emacs. The information is
restored when you begin working with a document in a new editing
session. To use this feature, put into `.emacs':(setq reftex-save-parse-info t) |
(setq reftex-allow-automatic-rescan nil) |
RefTeX will then occasionally annotate new labels in the selection buffer, saying that their position in the label list in uncertain. A manual document scan will fix this.
reftex-label. Updating the buffer takes as long as recreating it
- so the time saving is limited to cases where no new labels of that
category have been added. To turn on this feature, use(setq reftex-use-multiple-selection-buffers t) |
You can also inhibit the automatic updating entirely. Then the selection buffer will always pop up very fast, but may not contain the most recently defined labels. You can always update the buffer by hand, with the g key. To get this behavior, use instead
(setq reftex-use-multiple-selection-buffers t
reftex-auto-update-selection-buffers nil)
|
As a summary, here are the settings I recommend for heavy use of RefTeX with large documents:
(setq reftex-enable-partial-scans t
reftex-save-parse-info t
reftex-use-multiple-selection-buffers t)
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
AUCTeX is without doubt the best major mode for editing TeX and LaTeX files with Emacs (see section `Top' in The AUCTeX User Manual). If AUCTeX is not part of you Emacs distribution, you can get it(10) by ftp from the AUCTeX distribution site.
6.8.1 The AUCTeX-RefTeX Interface How both packages work together 6.8.2 Style Files AUCTeX's style files can support RefTeX 6.8.3 Bib-Cite Hypertext reading of a document
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX contains code to interface with AUCTeX. When this interface is turned on, both packages will interact closely. Instead of using RefTeX's commands directly, you can then also use them indirectly as part of the AUCTeX environment(11). The interface is turned on with
(setq reftex-plug-into-AUCTeX t) |
If you need finer control about which parts of the interface are used
and which not, read the docstring of the variable
reftex-plug-into-AUCTeX or customize it with M-x
customize-variable RET reftex-plug-into-AUCTeX RET.
The following list describes the individual parts of the interface.
reftex-label to insert labelsreftex-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.
TeX-arg-label, TeX-arg-cite, and TeX-arg-index to
prompt for arguments which are labels, citation keys and index entries.
The interface takes over these functions(12) and
supplies the macro arguments with RefTeX's mechanisms. For
example, when you type C-c RET ref RET, RefTeX
will supply its label selection process (see section 3.2 Referencing Labels).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
\documentclass and \usepackage
commands of a document (see section 6.8.2 Style Files). Support for
RefTeX in such a style file is useful when the LaTeX style
defines macros or environments connected with labels, citations, or the
index. Many style files (e.g. `amsmath.el' or `natbib.el')
distributed with AUCTeX already support RefTeX in this
way.Before calling a RefTeX function, the style hook should always test for the availability of the function, so that the style file will also work for people who do not use RefTeX.
Additions made with style files in the way described below remain local
to the current document. For example, if one package uses AMSTeX, the
style file will make RefTeX switch over to \eqref, but
this will not affect other documents.
A style hook may contain calls to
reftex-add-label-environments(13) which defines additions to
reftex-label-alist. The argument taken by this function must have
the same format as reftex-label-alist. The `amsmath.el'
style file of AUCTeX for example contains the following:
(TeX-add-style-hook "amsmath"
(lambda ()
(if (fboundp 'reftex-add-label-environments)
(reftex-add-label-environments '(AMSTeX)))))
|
while a package myprop defining a proposition environment
with \newtheorem might use
(TeX-add-style-hook "myprop"
(lambda ()
(LaTeX-add-environments '("proposition" LaTeX-env-label))
(if (fboundp 'reftex-add-label-environments)
(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))))))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once you have written a document with labels, references and citations,
it can be nice to read it like a hypertext document. RefTeX has
support for that: reftex-view-crossref (bound to C-c
&), reftex-mouse-view-crossref (bound to S-mouse-2), and
reftex-search-document. A somewhat fancier interface with mouse
highlighting is provided (among other things) by Peter S. Galbraith's
`bib-cite.el'. There is some overlap in the functionalities of
Bib-cite and RefTeX. Bib-cite.el comes bundled with
AUCTeX.
Bib-cite version 3.06 and later can be configured so that bib-cite's
mouse functions use RefTeX for displaying references and citations.
This can be useful in particular when working with the LaTeX xr
package or with an explicit thebibliography environment (rather
than BibTeX). Bib-cite cannot handle those, but RefTeX does. To
make use of this feature, try
(setq bib-cite-use-reftex-view-crossref t) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
\input, \include, \bibliography and \section
(etc.) statements have to be first on a line (except for white space).
reftex-enable-partial-scans), the section
numbers in the table of contents may eventually become wrong. A full
scan will fix this.
reftex-label-alist are
global and apply to all documents. If you need to make definitions
local to a document, because they would interfere with settings in other
documents, you should use AUCTeX and set up style files with calls to
reftex-add-label-environments, reftex-set-cite-format,
reftex-add-index-macros, and reftex-add-section-levels.
Settings made with these functions remain local to the current
document. See section 6.8 AUC TeX.
reftex-toc may have problems to jump to an affected
section heading. There are three possible ways to deal with
this:(setq reftex-keep-temporary-buffers t)(setq reftex-initialize-temporary-buffers t)reftex-initialize-temporary-buffers to a list of hook
functions doing a minimal initialization.reftex-refontify-context.
\begin macro
to specify a label. E.g. Lamport's `pf.sty' uses both
\step{label}{claim} and \begin{step+}{label}
claim
\end{step+}
|
We need to trick RefTeX into swallowing this:
;; Configuration for Lamport's pf.sty
(setq reftex-label-alist
'(("\\step{*}{}" ?p "st:" "~\\stepref{%s}" 2 ("Step" "St."))
("\\begin{step+}{*}" ?p "st:" "~\\stepref{%s}" 1000)))
|
The first line is just a normal configuration for a macro. For the
step+ environment we actually tell RefTeX to look for the
macro `\begin{step+}' and interpret the first
argument (which really is a second argument to the macro \begin)
as a label of type ?p. Argument count for this macro starts only
after the `{step+}', also when specifying how to get
context.
(setq reftex-use-itimer-in-xemacs t) |
(viper-harness-minor-mode "reftex") |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX was written by Carsten Dominik dominik@astro.uva.nl, with contributions by Stephen Eglen. RefTeX is currently maintained by
Carsten Dominik dominik@astro.uva.nl
If you have questions about RefTeX, there are several Usenet
groups which have competent readers: comp.emacs,
gnu.emacs.help, comp.emacs.xemacs, comp.text.tex.
You can also write directly to the maintainer.
If you find a bug in RefTeX or its documentation, or if you want to contribute code or ideas, please contact the maintainer. Remember to provide all necessary information such as version numbers of Emacs and RefTeX, and the relevant part of your configuration in `.emacs'. When reporting a bug which throws an exception, please include a backtrace if you know how to produce one.
RefTeX is bundled and pre-installed with Emacs since version 20.2.
It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
21.x users want to install the corresponding plugin package which is
available from the XEmacs ftp site. See the XEmacs 21.x
documentation on package installation for details.
Users of earlier Emacs distributions (including Emacs 19) can get a RefTeX distribution from the maintainers webpage. Note that the Emacs 19 version supports many but not all features described in this manual.
Thanks to the people on the Net who have used RefTeX and helped developing it with their reports. In particular thanks to Fran Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl Eichwalder, Erik Frik, Peter Galbraith, Kai Grossjohann, Frank Harrell, Dieter Kraft, Adrian Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat, Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan Williams.
The view-crossref feature was inspired by Peter Galbraith's
`bib-cite.el'.
Finally thanks to Uwe Bolick who first got me (some years ago) into supporting LaTeX labels and references with an editor (which was MicroEmacs at the time).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a summary of RefTeX's commands which can be executed from
LaTeX files. Command which are executed from the special buffers are
not described here. All commands are available from the Ref
menu. See See section 6.2 Default Key Bindings.
\bibliography command or a thebibliography environment)
and offers the matching entries for selection. The selected entry is
formated according to reftex-cite-format and inserted into the
buffer.\cite command, it
will add another key, ignoring the value of
reftex-cite-format.and. Thus, `aaaa&&bbb' matches entries which contain
both `aaaa' and `bbb'. While entering the regexp, completion
on knows citation keys is possible. `=' is a good regular
expression to match all entries in all files.reftex-index-macro or
by a call to reftex-add-index-macros, typically from an AUCTeX
style file. RefTeX provides completion for the index tag and the
index key, and will prompt for other arguments.reftex-index-default-macro
to make an index entry. The phrase indexed is the current selection or
the word near point. When called with one C-u prefix, let the
user have a chance to edit the index entry. When called with 2
C-u as prefix, also ask for the index macro and other stuff. When
called inside TeX math mode as determined by the `texmathp.el'
library which is part of AUCTeX, the string is first processed with the
reftex-index-math-format, which see.\label, \ref,
\cite, \bibitem, \index and many derivatives of
these. Where it makes sense, subsequent calls show additional
locations. See also the variable reftex-view-crossref-extra and
the command reftex-view-crossref-from-bibtex. With one or two
C-u prefixes, enforce rescanning of the document. With argument
2, select the window showing the cross reference.
etags on the current document. The
TAGS file is also immediately visited with
visit-tags-table.\label and
\ref commands. Works on the entire multifile document. No
active TAGS table is required.xr package.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a complete list of RefTeX's configuration variables. All
variables have customize support - so if you are not familiar with Emacs
Lisp (and even if you are) you might find it more comfortable to use
customize to look at and change these variables. M-x
reftex-customize will get you there.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.nil means, include file boundaries in `*toc*' buffer.
This flag can be toggled from within the `*toc*' buffer with the
i key.nil means, include labels in `*toc*' buffer. This flag
can be toggled from within the `*toc*' buffer with the l
key.nil means, include index entries in `*toc*' buffer.
This flag can be toggled from within the `*toc*' buffer with the
i key.
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.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.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
reftex-label-alist-builtin.
LaTeX should always be the last entry.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:
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 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).
?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 reminder of this entry is ignored.
%f Current file name, directory and extension stripped.
%F Current file name relative to master file directory.
%u User login name, on systems which support this.
%S A section prefix derived with variable |
Example: In a file `intro.tex', `eq:%f:' will become `eq:intro:'.
nil, use the text following the `\label{...}' macro.t, use
caption, item, eqnarray-like,
alignat-like, this symbol will internally be translated into an
appropriate regexp (see also the variable
reftex-default-context-regexps).\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.
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.
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
nil format and prefix
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.
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.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.
(format regexp (regexp-quote environment)) is used
to calculate the final regular expression - so `%s' will be
replaced with the environment or macro.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(derive prompt) |
If deriveis 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 legal 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.
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.reftex-derive-label-parameters.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.nil: Throw away any words containing characters illegal in labels.t: Throw away only the illegal characters, not the whole word.
nil: Never abbreviate words.t: Always abbreviate words (see reftex-abbrev-parameters).1: Abbreviate words if necessary to shorten label string.
t: Downcase words before putting them into the label.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
nil means do not show the short context.
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.
\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.nil means, the varioref macro \vref is used as
default. In the selection buffer, the v key toggles the reference
macro between \ref and \vref. The value of this variable
determines the default which is active when entering the selection
process. Instead of nil or t, this may also be a string
of type letters indicating the label types for which it should be
true.nil means, the fancyref macro \fref is used as
default. In the selection buffer, the V key toggles the reference
macro between \ref, \fref and \Fref. The value of
this variable determines the default which is active when entering the
selection process. Instead of nil or t, this may also be
a string of type letters indicating the label types for which it should
be true.
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 \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 two arguments, the
label and the default-format (usually `~\ref{%s}').
It should return the string to insert into the buffer.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.X-Symbol, but may have other uses as well.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.reftex-select-label-mode.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
\\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.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.nil Do not sort entries. author Sort entries by author name. year Sort entries by increasing year. reverse-year Sort entries by decreasing year. |
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
%a
reftex-cite-punctuation.
%2a
%A
%e
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.
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).
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.
nil means add a comment for each citation describing the full
entry. The comment is formatted according to
reftex-cite-comment-format.reftex-cite-format for possible
percent escapes.reftex-select-bib-mode.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.MakeIndex keywords
(level encap actual quote escape).
(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. Legal 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
|
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.
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 |
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.reftex-index-phrases-logical-or-regexp.reftex-index-phrases-logical-or-regexp
has higher priority than this logical `or'.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.
nil means, searching for index phrases will ignore
case.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.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.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.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.
reftex-index-phrases-mode.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.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(macro-re search-re highlight). |
nil means, initially turn automatic viewing of crossref info
on. Automatic viewing of crossref info normally uses the echo area.
Whenever point is 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 of
from the menu (Ref->Options).reftex-cite-format for possible percent
escapes.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.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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
"!kpsewhich -show-path=.tex".
path-separator. Directories ending in `//' or `!!' will
be expanded recursively. See also reftex-use-external-file-finders.
"!kpsewhich -show-path=.bib".
path-separator. Directories ending in `//' or `!!' will
be expanded recursively. See also reftex-use-external-file-finders.
(type . (def-ext other-ext ...))
type: File type like |
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.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.
(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.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
nil
t
1
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.
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.\include or \input is
matched by any of the regular expressions in this list, that file is not
parsed by RefTeX.
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.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,
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.
nil means use a separate selection buffer for each label
type. These buffers are kept from one selection to the next and need
not to 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.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.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.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
t
1
reftex-use-fonts is nil.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 to rebuild the selection and *toc* buffers to become effective (keys g or r).
reftex-highlight-selection.reftex-highlight-selection.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
nil means, make additional key bindings on startup. These
extra bindings are located in the users `C-c letter'
map. See section 6.2 Default Key Bindings.nil, RefTeX
will
- supply labels in new sections and environments (flag 1) - supply arguments for macros like |
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.
nil means, follow-mode will revisit files if necessary.
When nil, follow-mode will be suspended for stuff in unvisited files.
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.| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
RefTeX has the usual general keymap and load-- and mode-hook.
Furthermore, the 4 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a list of recent changes to RefTeX.
Version 4.00
\ref and \cite now allows to
select multiple items by marking entries with the m key.
reftex-index-globally to index a word in many
places in the document. Also available from the index buffer with
&.
reftex-label-alist entry may now also be a parser
function to do non-standard parsing.
reftex-auto-view-crossref no longer interferes with
pop-up-frames (patch from Stefan Monnier).
reftex-index-selection-or-word in TeX
math mode automatically get enclosing `$' to preserve math mode. See
new option reftex-index-math-format. Requires AUCTeX.
reftex-index-default-tag implements a default for queries.
reftex-section-levels can contain a function to compute the level
of a sectioning command.
thebibliography environments recognized.
reftex-toc-max-level to limit the depth of the toc.
New key binding t in the `*toc*' buffer to change this
setting.reftex-index-macros and
reftex-index-default-macro have changed their syntax slightly.
The repeat parameter has move from the latter to the former.
Also calls to reftex-add-index-macros from AUCTeX style files
need to be adapted.reftex-section-levels no longer contains the
default stuff which has been moved to a constant.reftex-setion-levels.reftex-parse-file-extension and
reftex-index-phrase-file-extension.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| Jump to: | *
?
\
A B C D E F G H I K L M N O P Q R S T V W X |
|---|
| Jump to: | *
?
\
A B C D E F G H I K L M N O P Q R S T V W X |
|---|
| [Top] | [Contents] | [Index] | [ ? ] |
Note that the context may contain constructs which are
illegal in labels. RefTeX will therefore strip the accent from
accented Latin-1 characters and remove everything else which is not
legal in labels. This mechanism is safe, but may not be satisfactory
for non-western languages. Check the following variables if you need to
change things: reftex-translate-to-ascii-function,
reftex-derive-label-parameters, reftex-label-illegal-re,
reftex-abbrev-parameters.
bind it to C-c v.
bind them to C-c f and C-c F.
`&&' with optional spaces, see
reftex-index-phrases-logical-and-regexp.
`||' with optional spaces,
see reftex-index-phrases-logical-or-regexp.
Windows users: Restrict yourself to the described keys during indexing. Pressing Help at the indexing prompt can apparently hang Emacs.
We are using the syntax of the `index' package here.
all macros that start with `ref' or end with `ref' or `refrange'
all macros that either start or end with `cite'
XEmacs 21.x users may want to install the corresponding XEmacs package.
RefTeX 4.0 and AUCTeX 9.10c will be needed for all of this to work. Parts of it work also with earlier versions.
fset is used to
do this, which is not reversible. However, RefTeX implements the
old functionality when you later decide to turn off the interface.
This used to be the
function reftex-add-to-label-alist which is still available as an
alias for compatibility.
| [Top] | [Contents] | [Index] | [ ? ] |
\eqref
xr: Cross-Document References
varioref: Variable Page References
fancyref: Fancy Cross References
| [Top] | [Contents] | [Index] | [ ? ] |
1. Introduction
2. Table of Contents
3. Labels and References
4. Citations
5. Index Support
6. Viewing Cross--References
7. Commands
8. Options, Keymaps, Hooks
9. Changes
Index
| [Top] | [Contents] | [Index] | [ ? ] |
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
| [ < ] | Back | previous section in reading order | 1.2.2 |
| [ > ] | Forward | next section in reading order | 1.2.4 |
| [ << ] | FastBack | previous or up-and-previous section | 1.1 |
| [ Up ] | Up | up section | 1.2 |
| [ >> ] | FastForward | next or up-and-next section | 1.3 |
| [Top] | Top | cover (top) of document | |
| [Contents] | Contents | table of contents | |
| [Index] | Index | concept index | |
| [ ? ] | About | this page |