This is Info file ../info/reftex, produced by Makeinfo version 1.68
from the input file reftex.texi.

INFO-DIR-SECTION Editors
START-INFO-DIR-ENTRY
* reftex: (reftex).	Support for LaTeX labels, references, and citations
                          with Emacs.
END-INFO-DIR-ENTRY

   This file documents RefTeX, a package to do labels, references and
citations for LaTeX documents with Emacs.

   This is edition 3.43 of the RefTeX User Manual for RefTeX 3.43

   Copyright (c) 1997, 1998 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derive work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: reftex,  Node: Faces,  Next: AUCTeX,  Prev: Keybindings,  Up: Top

Faces
=====

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


File: reftex,  Node: Multifile Documents,  Next: Language Support,  Prev: AUCTeX,  Up: Top

Multifile Documents
===================

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

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

   * All files belonging to a multifile document should have a File
     Variable (`TeX-master' for AUCTeX or `tex-main-file' for the
     standard Emacs LaTeX mode) set to the name of the master file.
     See the documentation of your (La)TeX mode and *Note File
     Variables: (emacs)File Variables.

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


File: reftex,  Node: Language Support,  Next: Finding Files,  Prev: Multifile Documents,  Up: Top

Language Support
================

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

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

   * Also, when a label is derived from context, RefTeX clears the
     context string from non-ASCII characters in order to make a legal
     label.  If you are using a special version of TeX which allows
     extended characters *in labels*, then you should look at the
     variables `reftex-translate-to-ascii-function' and
     `reftex-label-illegal-re'.

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


File: reftex,  Node: Finding Files,  Next: Optimizations,  Prev: Language Support,  Up: Top

Finding Files
=============

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

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

   * Most TeX system have a default search path for both TeX files and
     BibTeX files which is defined in some setup file.  Usually this
     default path is for system files which RefTeX does not need to
     see.  But if your document needs TeX files or BibTeX database
     files in a directory only given in the default search path, RefTeX
     will fail to find them.

   * Some TeX systems do not use environment variables at all in order
     to specify the search path.  Both default and user search path are
     then defined in setup files.

There are three ways to solve this problem:

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

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

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

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

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

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


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.  AUCTeX is part of the XEmacs distribution.  It is
also available 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


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, customize this variable 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' and `TeX-arg-cite' to prompt for
     arguments which are labels and citation keys.  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 and citations keys
     RefTeX will add all newly created labels to AUCTeX's completion
     list.

   ---------- Footnotes ----------

   (1) RefTeX 3.23 and AUCTeX 9.9c 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. Support for RefTeX in such a style file is useful when the
LaTeX style defines macros or environments connected with labels and
citations.  Some 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.")))))))

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

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

   * Command abbreviations
     Some people define abbreviations for environments, like `\be' for
     `\begin{equation}', and `\ee' for `\end{equation}'.  RefTeX cannot
     be configured to see these--you will have to used the full
     `\begin' and `\end' statements.

   * 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', and `reftex-add-section-levels'.
     Settings made with these functions remain local to the current
     document. *Note AUCTeX::, for more information.

   * 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@strw.leidenuniv.nl>,
with contributions by Stephen Eglen.  RefTeX is currently maintained by

Carsten Dominik <dominik@strw.leidenuniv.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@strw.leidenuniv.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 preinstalled with Emacs since version 20.2.
It was also bundled and preinstalled 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/).

   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,
Peter Galbraith, Kai Grossjohann, Dieter Kraft, Adrian Lanz, Rory
Molinari, 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.  All commands are available
from the `Ref' menu.  For keybindings, *note Keybindings::..

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

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

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

     If the type indicator characters of two or more entries are the
     same, RefTeX will use
        - the first non-`nil' format and prefix

        - the magic words of all involved entries.

     Any list entry may also be a symbol.  If that has an association in
     `reftex-label-alist-builtin', the `cddr' of that association is
     spliced into the list.  However, builtin defaults should normally
     be set with the variable `reftex-default-label-alist-entries'.

 - User Option: reftex-section-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.

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

   ---------- Footnotes ----------

   (1) Careful:  RefTeX will add stuff to the beginning and end of
these regular expressions.


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

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

