This is ../info/reftex, produced by makeinfo version 4.0 from
reftex.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
END-INFO-DIR-ENTRY
This file documents RefTeX, a package to do labels, references,
citations and indices for LaTeX documents with Emacs.
This is edition 4.16 of the RefTeX User Manual for RefTeX 4.16
Copyright (c) 1997, 1998, 1999, 2000 2001 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled "GNU Free Documentation License" in
the Emacs manual.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
File: reftex, Node: Optimizations, Next: Problems and Work-Arounds, Prev: Finding Files, Up: Top
Optimizations
=============
Implementing the principle of least surprises, the default settings
of RefTeX ensure a safe ride for beginners and casual users. However,
when using RefTeX for a large project and/or on a small computer, there
are ways to improve speed or memory usage.
* Removing Lookup Buffers
RefTeX will load other parts of a multifile document as well as
BibTeX database files for lookup purposes. These buffers are
kept, so that subsequent use of the same files is fast. If you
can't afford keeping these buffers around, and if you can live
with a speed penalty, try
(setq reftex-keep-temporary-buffers nil)
* Partial Document Scans
A `C-u' prefix on the major RefTeX commands `reftex-label' (`C-u
C-c ('), `reftex-reference' (`C-u C-c )'), `reftex-citation' (`C-u
C-c ['), `reftex-toc' (`C-u C-c ='), and `reftex-view-crossref'
(`C-u C-c &') initiates re-parsing of the entire document in order
to update the parsing information. For a large document this can
be unnecessary, in particular if only one file has changed.
RefTeX can be configured to do partial scans instead of full ones.
`C-u' re-parsing then does apply only to the current buffer and
files included from it. Likewise, the `r' key in both the label
selection buffer and the table-of-contents buffer will only prompt
scanning of the file in which the label or section macro near the
cursor was defined. Re-parsing of the entire document is still
available by using `C-u C-u' as a prefix, or the capital `R' key
in the menus. To use this feature, try
(setq reftex-enable-partial-scans t)
* Saving Parser Information
Even with partial scans enabled, RefTeX still has to make one full
scan, when you start working with a document. To avoid this,
parsing information can be stored in a file. The file
`MASTER.rel' is used for storing information about a document with
master file `MASTER.tex'. It is written automatically when you
kill a buffer in `reftex-mode' or when you exit Emacs. The
information is restored when you begin working with a document in
a new editing session. To use this feature, put into `.emacs':
(setq reftex-save-parse-info t)
* Automatic Document Scans
At rare occasions, RefTeX will automatically rescan a part of the
document. If this gets into your way, it can be turned off with
(setq reftex-allow-automatic-rescan nil)
RefTeX will then occasionally annotate new labels in the selection
buffer, saying that their position in the label list in uncertain.
A manual document scan will fix this.
* Multiple Selection Buffers
Normally, the selection buffer `*RefTeX Select*' is re-created for
every selection process. In documents with very many labels this
can take several seconds. RefTeX provides an option to create a
separate selection buffer for each label type and to keep this
buffer from one selection to the next. These buffers are updated
automatically only when a new label has been added in the buffers
category with `reftex-label'. Updating the buffer takes as long
as recreating it - so the time saving is limited to cases where no
new labels of that category have been added. To turn on this
feature, use
(setq reftex-use-multiple-selection-buffers t)
You can also inhibit the automatic updating entirely. Then the
selection buffer will always pop up very fast, but may not contain
the most recently defined labels. You can always update the
buffer by hand, with the `g' key. To get this behavior, use
instead
(setq reftex-use-multiple-selection-buffers t
reftex-auto-update-selection-buffers nil)
As a summary, here are the settings I recommend for heavy use of RefTeX
with large documents:
(setq reftex-enable-partial-scans t
reftex-save-parse-info t
reftex-use-multiple-selection-buffers t)
File: reftex, Node: AUCTeX, Next: Multifile Documents, Prev: Faces, Up: Top
AUC TeX
=======
AUCTeX is without doubt the best major mode for editing TeX and LaTeX
files with Emacs (*note AUCTeX: (auctex)Top.). If AUCTeX is not part
of you Emacs distribution, you can get it(1) by ftp from the AUCTeX
distribution site (http://www.sunsite.auc.dk/auctex/).
* Menu:
* AUCTeX-RefTeX Interface:: How both packages work together
* Style Files:: AUCTeX's style files can support RefTeX
* Bib-Cite:: Hypertext reading of a document
---------- Footnotes ----------
(1) XEmacs 21.x users may want to install the corresponding XEmacs
package.
File: reftex, Node: AUCTeX-RefTeX Interface, Next: Style Files, Up: AUCTeX
The AUCTeX-RefTeX Interface
---------------------------
RefTeX contains code to interface with AUCTeX. When this interface
is turned on, both packages will interact closely. Instead of using
RefTeX's commands directly, you can then also use them indirectly as
part of the AUCTeX environment(1). The interface is turned on with
(setq reftex-plug-into-AUCTeX t)
If you need finer control about which parts of the interface are used
and which not, read the docstring of the variable
`reftex-plug-into-AUCTeX' or customize it with `M-x customize-variable
<RET> reftex-plug-into-AUCTeX <RET>'.
The following list describes the individual parts of the interface.
* AUCTeX calls `reftex-label' to insert labels
When a new section is created with `C-c C-s', or a new environment
is inserted with `C-c C-e', AUCTeX normally prompts for a label to
go with it. With the interface, `reftex-label' is called instead.
For example, if you type `C-c C-e equation <RET>', AUCTeX and
RefTeX will insert
\begin{equation}
\label{eq:1}
\end{equation}
without further prompts.
Similarly, when you type `C-c C-s section <RET>', RefTeX will
offer its default label which is derived from the section title.
* AUCTeX tells RefTeX about new sections
When creating a new section with `C-c C-s', RefTeX will not have
to rescan the buffer in order to see it.
* RefTeX supplies macro arguments
When you insert a macro interactively with `C-c <RET>', AUCTeX
normally prompts for macro arguments. Internally, it uses the
functions `TeX-arg-label', `TeX-arg-cite', and `TeX-arg-index' to
prompt for arguments which are labels, citation keys and index
entries. The interface takes over these functions(2) 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 (*note Referencing Labels::).
* RefTeX tells AUCTeX about new labels, citation- and index keys
RefTeX will add all newly created labels to AUCTeX's completion
list.
---------- Footnotes ----------
(1) RefTeX 4.0 and AUCTeX 9.10c will be needed for all of this to
work. Parts of it work also with earlier versions.
(2) `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.
File: reftex, Node: Style Files, Next: Bib-Cite, Prev: AUCTeX-RefTeX Interface, Up: AUCTeX
Style Files
-----------
Style files are Emacs Lisp files which are evaluated by AUCTeX in
association with the `\documentclass' and `\usepackage' commands of a
document (*note Style Files: (auctex)Style Files.). Support for RefTeX
in such a style file is useful when the LaTeX style defines macros or
environments connected with labels, citations, or the index. Many
style files (e.g. `amsmath.el' or `natbib.el') distributed with AUCTeX
already support RefTeX in this way.
Before calling a RefTeX function, the style hook should always test
for the availability of the function, so that the style file will also
work for people who do not use RefTeX.
Additions made with style files in the way described below remain
local to the current document. For example, if one package uses
AMSTeX, the style file will make RefTeX switch over to `\eqref', but
this will not affect other documents.
A style hook may contain calls to `reftex-add-label-environments'(1)
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))))))
---------- Footnotes ----------
(1) This used to be the function `reftex-add-to-label-alist' which
is still available as an alias for compatibility.
File: reftex, Node: Bib-Cite, Prev: Style Files, Up: AUCTeX
Bib-Cite
--------
Once you have written a document with labels, references and
citations, it can be nice to read it like a hypertext document. RefTeX
has support for that: `reftex-view-crossref' (bound to `C-c &'),
`reftex-mouse-view-crossref' (bound to `S-mouse-2'), and
`reftex-search-document'. A somewhat fancier interface with mouse
highlighting is provided (among other things) by Peter S. Galbraith's
`bib-cite.el'. There is some overlap in the functionalities of
Bib-cite and RefTeX. Bib-cite.el comes bundled with AUCTeX.
Bib-cite version 3.06 and later can be configured so that bib-cite's
mouse functions use RefTeX for displaying references and citations.
This can be useful in particular when working with the LaTeX `xr'
package or with an explicit `thebibliography' environment (rather than
BibTeX). Bib-cite cannot handle those, but RefTeX does. To make use
of this feature, try
(setq bib-cite-use-reftex-view-crossref t)
File: reftex, Node: Problems and Work-Arounds, Next: Imprint, Prev: Optimizations, Up: Top
Problems and Work-arounds
=========================
* LaTeX commands
`\input', `\include', `\bibliography' and `\section' (etc.)
statements have to be first on a line (except for white space).
* Commented regions
RefTeX sees also labels in regions commented out and will refuse to
make duplicates of such labels. This is considered to be a
feature.
* Wrong section numbers
When using partial scans (`reftex-enable-partial-scans'), the
section numbers in the table of contents may eventually become
wrong. A full scan will fix this.
* Local settings
The label environment definitions in `reftex-label-alist' are
global and apply to all documents. If you need to make definitions
local to a document, because they would interfere with settings in
other documents, you should use AUCTeX and set up style files with
calls to `reftex-add-label-environments', `reftex-set-cite-format',
`reftex-add-index-macros', and `reftex-add-section-levels'.
Settings made with these functions remain local to the current
document. *Note AUCTeX::.
* Funny display in selection buffer
When using packages which make the buffer representation of a file
different from its disk representation (e.g. x-symbol, isotex,
iso-cvt) you may find that RefTeX's parsing information sometimes
reflects the disk state of a file. This happens only in
_unvisited_ parts of a multifile document, because RefTeX visits
these files literally for speed reasons. Then both short context
and section headings may look different from what you usually see
on your screen. In rare cases `reftex-toc' may have problems to
jump to an affected section heading. There are three possible
ways to deal with this:
- `(setq reftex-keep-temporary-buffers t)'
This implies that RefTeX will load all parts of a multifile
document into Emacs (i.e. there won't be any temporary
buffers).
- `(setq reftex-initialize-temporary-buffers t)'
This means full initialization of temporary buffers. It
involves a penalty when the same unvisited file is used for
lookup often.
- Set `reftex-initialize-temporary-buffers' to a list of hook
functions doing a minimal initialization.
See also the variable `reftex-refontify-context'.
* Labels as arguments to \begin
Some packages use an additional argument to a `\begin' macro to
specify a label. E.g. Lamport's `pf.sty' uses both
\step{LABEL}{CLAIM} and \begin{step+}{LABEL}
CLAIM
\end{step+}
We need to trick RefTeX into swallowing this:
;; Configuration for Lamport's pf.sty
(setq reftex-label-alist
'(("\\step{*}{}" ?p "st:" "~\\stepref{%s}" 2 ("Step" "St."))
("\\begin{step+}{*}" ?p "st:" "~\\stepref{%s}" 1000)))
The first line is just a normal configuration for a macro. For the
`step+' environment we actually tell RefTeX to look for the
_macro_ `\begin{step+}' and interpret the _first_ argument (which
really is a second argument to the macro `\begin') as a label of
type `?p'. Argument count for this macro starts only after the
`{step+}', also when specifying how to get context.
* Idle timers in XEmacs
In XEmacs, idle timer restart does not work reliably after fast
keystrokes. Therefore RefTeX currently uses the post command hook
to start the timer used for automatic crossref information. When
this bug gets fixed, a real idle timer can be requested with
(setq reftex-use-itimer-in-xemacs t)
* Viper mode
With Viper mode prior to Vipers version 3.01, you need to protect
RefTeX's keymaps with
(viper-harness-minor-mode "reftex")
File: reftex, Node: Imprint, Next: Commands, Prev: Problems and Work-Arounds, Up: Top
Imprint
=======
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
(mailto:dominik@astro.uva.nl). 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
(http://www.strw.leidenuniv.nl/~dominik/Tools/). 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).
File: reftex, Node: Commands, Next: Options, Prev: Imprint, Up: Top
Commands
********
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 *Note Key Bindings::.
- Command: reftex-toc
Show the table of contents for the current document. When called
with one ore two `C-u' prefixes, rescan the document first.
- Command: reftex-label
Insert a unique label. With one or two `C-u' prefixes, enforce
document rescan first.
- Command: reftex-reference
Start a selection process to select a label, and insert a
reference to it. With one or two `C-u' prefixes, enforce document
rescan first.
- Command: reftex-citation
Make a citation using BibTeX database files. After prompting for
a regular expression, scans the buffers with BibTeX entries (taken
from the `\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.
When called with one or two `C-u' prefixes, first rescans the
document. When called with a numeric prefix, make that many
citations. When called with point inside the braces of a `\cite'
command, it will add another key, ignoring the value of
`reftex-cite-format'.
The regular expression uses an expanded syntax: `&&' is interpreted
as `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.
- Command: reftex-index
Query for an index macro and insert it along with its arguments.
The index macros available are those defined in
`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.
- Command: reftex-index-selection-or-word
Put current selection or the word near point into the default index
macro. This uses the information in `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.
- Command: reftex-index-phrase-selection-or-word
Add current selection or the word at point to the phrases buffer.
When you are in transient-mark-mode and the region is active, the
selection will be used - otherwise the word at point. You get a
chance to edit the entry in the phrases buffer - to save the
buffer and return to the LaTeX document, finish with `C-c C-c'.
- Command: reftex-index-visit-phrases-buffer
Switch to the phrases buffer, initialize if empty.
- Command: reftex-index-phrases-apply-to-region
Index all index phrases in the current region. This works exactly
like global indexing from the index phrases buffer, but operation
is restricted to the current region.
- Command: reftex-display-index
Display a buffer with an index compiled from the current document.
When the document has multiple indices, first prompts for the
correct one. When index support is turned off, offer to turn it
on. With one or two `C-u' prefixes, rescan document first. With
prefix 2, restrict index to current document section. With prefix
3, restrict index to active region.
- Command: reftex-view-crossref
View cross reference of macro at point. Point must be on the KEY
argument. Works with the macros `\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.
- Command: reftex-view-crossref-from-bibtex
View location in a LaTeX document which cites the BibTeX entry at
point. Since BibTeX files can be used by many LaTeX documents,
this function prompts upon first use for a buffer in RefTeX mode.
To reset this link to a document, call the function with with a
prefix arg. Calling this function several times find successive
citation locations.
- Command: reftex-create-tags-file
Create TAGS file by running `etags' on the current document. The
TAGS file is also immediately visited with `visit-tags-table'.
- Command: reftex-grep-document
Run grep query through all files related to this document. With
prefix arg, force to rescan document. No active TAGS table is
required.
- Command: reftex-search-document
Regexp search through all files of the current document. Starts
always in the master file. Stops when a match is found. No
active TAGS table is required.
- Command: reftex-query-replace-document
Run a query-replace-regexp of FROM with TO over the entire
document. With prefix arg, replace only word-delimited matches.
No active TAGS table is required.
- Command: reftex-change-label
Query replace FROM with TO in all `\label' and `\ref' commands.
Works on the entire multifile document. No active TAGS table is
required.
- Command: reftex-renumber-simple-labels
Renumber all simple labels in the document to make them
sequentially. Simple labels are the ones created by RefTeX,
consisting only of the prefix and a number. After the command
completes, all these labels will have sequential numbers
throughout the document. Any references to the labels will be
changed as well. For this, RefTeX looks at the arguments of any
macros which either start or end with the string `ref'. This
command should be used with care, in particular in multifile
documents. You should not use it if another document refers to
this one with the `xr' package.
- Command: reftex-find-duplicate-labels
Produce a list of all duplicate labels in the document.
- Command: reftex-customize
Run the customize browser on the RefTeX group.
- Command: reftex-show-commentary
Show the commentary section from `reftex.el'.
- Command: reftex-info
Run info on the top RefTeX node.
- Command: reftex-parse-document
Parse the entire document in order to update the parsing
information.
- Command: reftex-reset-mode
Enforce rebuilding of several internal lists and variables. Also
removes the parse file associated with the current document.
File: reftex, Node: Options, Next: Keymaps and Hooks, Prev: Commands, Up: Top
Options, Keymaps, Hooks
***********************
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.
* Menu:
* Options (Table of Contents)::
* Options (Defining Label Environments)::
* Options (Creating Labels)::
* Options (Referencing Labels)::
* Options (Creating Citations)::
* Options (Index Support)::
* Options (Viewing Cross-References)::
* Options (Finding Files)::
* Options (Optimizations)::
* Options (Fontification)::
* Options (Misc)::
File: reftex, Node: Options (Table of Contents), Next: Options (Defining Label Environments), Up: Options
Table of Contents
=================
- User Option: reftex-toc-max-level
The maximum level of toc entries which will be included in the TOC.
Section headings with a bigger level will be ignored. In RefTeX,
chapters are level 1, sections level 2 etc. This variable can be
changed from within the `*toc*' buffer with the `t' key.
- User Option: reftex-toc-keep-other-windows
Non-`nil' means, split the selected window to display the `*toc*'
buffer. This helps to keep the window configuration, but makes
the `*toc*' small. When `nil', all other windows except the
selected one will be deleted, so that the `*toc*' window fills
half the frame.
- User Option: reftex-toc-include-file-boundaries
Non-`nil' means, include file boundaries in `*toc*' buffer. This
flag can be toggled from within the `*toc*' buffer with the `i'
key.
- User Option: reftex-toc-include-labels
Non-`nil' means, include labels in `*toc*' buffer. This flag can
be toggled from within the `*toc*' buffer with the `l' key.
- User Option: reftex-toc-include-index-entries
Non-`nil' means, include index entries in `*toc*' buffer. This
flag can be toggled from within the `*toc*' buffer with the `i'
key.
- User Option: reftex-toc-include-context
Non-`nil' means, include context with labels in the `*toc*'
buffer. Context will only be shown if the labels are visible as
well. This flag can be toggled from within the `*toc*' buffer
with the `c' key.
- User Option: reftex-toc-follow-mode
Non-`nil' means, point in `*toc*' buffer (the table-of-contents
buffer) will cause other window to follow. The other window will
show the corresponding part of the document. This flag can be
toggled from within the `*toc*' buffer with the `f' key.
- Normal Hook: reftex-toc-mode-hook
Normal hook which is run when a `*toc*' buffer is created.
- Keymap: reftex-toc-map
The keymap which is active in the `*toc*' buffer. (*note Table of
Contents::).
File: reftex, Node: Options (Defining Label Environments), Next: Options (Creating Labels), Prev: Options (Table of Contents), Up: Options
Defining Label Environments
===========================
- User Option: reftex-default-label-alist-entries
Default label alist specifications. It is a list of symbols with
associations in the constant `reftex-label-alist-builtin'.
`LaTeX' should always be the last entry.
- User Option: reftex-label-alist
Set this variable to define additions and changes to the defaults
in `reftex-default-label-alist-entries'. The only things you
_must not_ change is that `?s' is the type indicator for section
labels, and <SPC> for the `any' label type. These are hard-coded
at other places in the code.
The value of the variable must be a list of items. Each item is a
list itself and has the following structure:
(ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT
CONTEXT-METHOD (MAGIC-WORD ... ) TOC-LEVEL)
Each list entry describes either an environment carrying a counter
for use with `\label' and `\ref', or a LaTeX macro defining a
label as (or inside) one of its arguments. The elements of each
list entry are:
ENV-OR-MACRO
Name of the environment (like `table') or macro (like
`\myfig'). For macros, indicate the arguments, as in
`\myfig[]{}{}{*}{}'. Use square brackets for optional
arguments, a star to mark the label argument, if any. The
macro does not have to have a label argument - you could also
use `\label{...}' inside one of its arguments.
Special names: `section' for section labels, `any' to define a
group which contains all labels.
This may also be a function to do local parsing and identify
point to be in a a non-standard label environment. The
function must take an argument BOUND and limit backward
searches to this value. It should return either nil or a
cons cell `(FUNCTION . POSITION)' with the function symbol
and the position where the special environment starts. See
the Info documentation for an example.
Finally this may also be `nil' if the entry is only meant to
change some settings associated with the type indicator
character (see below).
TYPE-KEY
Type indicator character, like `?t', must be a printable ASCII
character. The type indicator is a single character which
defines a label type. Any label inside the environment or
macro is assumed to belong to this type. The same character
may occur several times in this list, to cover cases in which
different environments carry the same label type (like
`equation' and `eqnarray'). If the type indicator is `nil'
and the macro has a label argument `{*}', the macro defines
neutral labels just like `\label'. In this case the reminder
of this entry is ignored.
LABEL-PREFIX
Label prefix string, like `tab:'. The prefix is a short
string used as the start of a label. It may be the empty
string. The prefix may contain the following `%' escapes:
%f Current file name, directory and extension stripped.
%F Current file name relative to master file directory.
%u User login name, on systems which support this.
%S A section prefix derived with variable `reftex-section-prefixes'.
Example: In a file `intro.tex', `eq:%f:' will become
`eq:intro:'.
REFERENCE-FORMAT
Format string for reference insert in buffer. `%s' will be
replaced by the label. When the format starts with `~', this
`~' will only be inserted when the character before point is
_not_ a whitespace.
CONTEXT-METHOD
Indication on how to find the short context.
- If `nil', use the text following the `\label{...}' macro.
- If `t', use
- the section heading for section labels.
- text following the `\begin{...}' statement of
environments (not a good choice for environments
like eqnarray or enumerate, where one has several
labels in a single environment).
- text after the macro name (starting with the first
arg) for macros.
- If an integer, use the nth argument of the macro. As a
special case, 1000 means to get text after the last
macro argument.
- If a string, use as regexp to search _backward_ from the
label. Context is then the text following the end of
the match. E.g. putting this to `\\caption[[{]' will
use the caption in a figure or table environment.
`\\begin{eqnarray}\|\\\\' works for eqnarrays.
- If any of `caption', `item', `eqnarray-like',
`alignat-like', this symbol will internally be
translated into an appropriate regexp (see also the
variable `reftex-default-context-regexps').
- If a function, call this function with the name of the
environment/macro as argument. On call, point will be
just after the `\label' macro. The function is expected
to return a suitable context string. It should throw an
exception (error) when failing to find context. As an
example, here is a function returning the 10 chars
following the label macro as context:
(defun my-context-function (env-or-mac)
(if (> (point-max) (+ 10 (point)))
(buffer-substring (point) (+ 10 (point)))
(error "Buffer too small")))
Label context is used in two ways by RefTeX: For display in
the label menu, and to derive a label string. If you want to
use a different method for each of these, specify them as a
dotted pair. E.g. `(nil . t)' uses the text after the label
(`nil') for display, and text from the default position (`t')
to derive a label string. This is actually used for section
labels.
MAGIC-WORD-LIST
List of magic words which identify a reference to be of this
type. If the word before point is equal to one of these
words when calling `reftex-reference', the label list offered
will be automatically restricted to labels of the correct
type. If the first element of this word-list is the symbol
`regexp', the strings are interpreted as regular expressions.
TOC-LEVEL
The integer level at which this environment should be added
to the table of contents. See also `reftex-section-levels'.
A positive value will number the entries mixed with the
sectioning commands of the same level. A negative value will
make unnumbered entries. Useful only for theorem-like
environments which structure the document. Will be ignored
for macros. When omitted or `nil', no TOC entries will be
made.
If the type indicator characters of two or more entries are the
same, RefTeX will use
- the first non-`nil' format and prefix
- the magic words of all involved entries.
Any list entry may also be a symbol. If that has an association in
`reftex-label-alist-builtin', the `cddr' of that association is
spliced into the list. However, builtin defaults should normally
be set with the variable `reftex-default-label-alist-entries'.
- User Option: reftex-max-section-depth
Maximum depth of section levels in document structure. Standard
LaTeX needs 7, default is 12.
- User Option: reftex-section-levels
Commands and levels used for defining sections in the document.
The `car' of each cons cell is the name of the section macro. The
`cdr' is a number indicating its level. A negative level means the
same as the positive value, but the section will never get a
number. The `cdr' may also be a function which then has to return
the level.
- User Option: reftex-section-prefixes
Prefixes for section labels. When the label prefix given in an
entry in `reftex-label-alist' contains `%S', this list is used to
determine the correct prefix string depending on the current
section level. The list is an alist, with each entry of the form
`(KEY . PREFIX)'. Possible keys are sectioning macro names like
`chapter', integer section levels (as given in
`reftex-section-levels'), and `t' for the default.
- User Option: reftex-default-context-regexps
Alist with default regular expressions for finding context. The
emacs lisp form `(format regexp (regexp-quote environment))' is
used to calculate the final regular expression - so `%s' will be
replaced with the environment or macro.
File: reftex, Node: Options (Creating Labels), Next: Options (Referencing Labels), Prev: Options (Defining Label Environments), Up: Options
Creating Labels
===============
- User Option: reftex-insert-label-flags
Flags governing label insertion. The value has the form
(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'.
- Hook: reftex-format-label-function
If non-`nil', should be a function which produces the string to
insert as a label definition. The function will be called with two
arguments, the LABEL and the DEFAULT-FORMAT (usually
`\label{%s}'). It should return the string to insert into the
buffer.
- Hook: reftex-string-to-label-function
Function to turn an arbitrary string into a legal label. RefTeX's
default function uses the variable
`reftex-derive-label-parameters'.
- Hook: reftex-translate-to-ascii-function
Filter function which will process a context string before it is
used to derive a label from it. The intended application is to
convert ISO or Mule characters into something legal in labels.
The default function `reftex-latin1-to-ascii' removes the accents
from Latin-1 characters. X-Symbol (>=2.6) sets this variable to
the much more general `x-symbol-translate-to-ascii'.
- User Option: reftex-derive-label-parameters
Parameters for converting a string into a label. This variable is
a list of the following items:
NWORDS
Number of words to use.
MAXCHAR
Maximum number of characters in a label string.
ILLEGAL
`nil': Throw away any words containing characters illegal in
labels.
`t': Throw away only the illegal characters, not the whole
word.
ABBREV
`nil': Never abbreviate words.
`t': Always abbreviate words (see
`reftex-abbrev-parameters').
`1': Abbreviate words if necessary to shorten label string.
SEPARATOR
String separating different words in the label.
IGNOREWORDS
List of words which should not be part of labels.
DOWNCASE
`t': Downcase words before putting them into the label.
- User Option: reftex-label-illegal-re
Regexp matching characters not legal in labels.
- User Option: reftex-abbrev-parameters
Parameters for abbreviation of words. A list of four parameters.
MIN-CHARS
Minimum number of characters remaining after abbreviation.
MIN-KILL
Minimum number of characters to remove when abbreviating
words.
BEFORE
Character class before abbrev point in word.
AFTER
Character class after abbrev point in word.
File: reftex, Node: Options (Referencing Labels), Next: Options (Creating Citations), Prev: Options (Creating Labels), Up: Options
Referencing Labels
==================
- User Option: reftex-label-menu-flags
List of flags governing the label menu makeup. The flags are:
TABLE-OF-CONTENTS
Show the labels embedded in a table of context.
SECTION-NUMBERS
Include section numbers (like 4.1.3) in table of contents.
COUNTERS
Show counters. This just numbers the labels in the menu.
NO-CONTEXT
Non-`nil' means do _not_ show the short context.
FOLLOW
Follow full context in other window.
SHOW-COMMENTED
Show labels from regions which are commented out.
MATCH-EVERYWHERE
Obsolete flag.
SHOW-FILES
Show begin and end of included files.
Each of these flags can be set to `t' or `nil', or to a string of
type letters indicating the label types for which it should be
true. These strings work like character classes in regular
expressions. Thus, setting one of the flags to `"sf"' makes the
flag true for section and figure labels, `nil' for everything
else. Setting it to `"^sf"' makes it the other way round.
The available label types are: `s' (section), `f' (figure), `t'
(table), `i' (item), `e' (equation), `n' (footnote), plus any
definitions in `reftex-label-alist'.
Most options can also be switched from the label menu itself - so
if you decide here to not have a table of contents in the label
menu, you can still get one interactively during selection from
the label menu.
- User Option: reftex-multiref-punctuation
Punctuation strings for multiple references. When marking is used
in the selection buffer to select several references, this variable
associates the 3 marking characters `,-+' with prefix strings to be
inserted into the buffer before the corresponding `\ref' macro.
This is used to string together whole reference sets, like `eqs.
1,2,3-5,6 and 7' in a single call to `reftex-reference'.
- User Option: reftex-vref-is-default
Non-`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.
- User Option: reftex-fref-is-default
Non-`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.
- Hook: reftex-format-ref-function
If non-`nil', should be a function which produces the string to
insert as a reference. Note that the insertion format can also be
changed with `reftex-label-alist'. This hook also is used by the
special commands to insert `\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.
- User Option: reftex-level-indent
Number of spaces to be used for indentation per section level.
- User Option: reftex-guess-label-type
Non-`nil' means, `reftex-reference' will try to guess the label
type. To do that, RefTeX will look at the word before the cursor
and compare it with the magic words given in `reftex-label-alist'.
When it finds a match, RefTeX will immediately offer the correct
label menu - otherwise it will prompt you for a label type. If
you set this variable to `nil', RefTeX will always prompt for a
label type.
- Normal Hook: reftex-display-copied-context-hook
Normal Hook which is run before context is displayed anywhere.
Designed for `X-Symbol', but may have other uses as well.
- Hook: reftex-pre-refontification-functions
`X-Symbol' specific hook. Probably not useful for other purposes.
The functions get two arguments, the buffer from where the command
started and a symbol indicating in what context the hook is called.
- Normal Hook: reftex-select-label-mode-hook
Normal hook which is run when a selection buffer enters
`reftex-select-label-mode'.
- Keymap: reftex-select-label-map
The keymap which is active in the labels selection process (*note
Referencing Labels::).