Move here from ../../man

1 files changed, 5898 insertions, 0 deletions

diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi
new file mode 100644
index 00000000000..a2c0a9689b2
--- /dev/null
+++ b/doc/misc/reftex.texi
@@ -0,0 +1,5898 @@
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/reftex
+@settitle RefTeX User Manual
+@synindex ky cp
+@syncodeindex vr cp
+@syncodeindex fn cp
+
+@c Version and Contact Info
+@set VERSION 4.31
+@set EDITION 4.31
+@set DATE February 2006
+@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site}
+@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page}
+@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers}
+@set MAINTAINER the AUC@TeX{} project
+@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org})
+@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org})
+@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org})
+@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}
+@c %**end of header
+
+@copying
+This file documents @b{Ref@TeX{}}, a package to do labels, references,
+citations and indices for LaTeX documents with Emacs.
+
+This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
+@b{Ref@TeX{}} @value{VERSION}
+
+Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007  Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 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.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* RefTeX: (reftex).     Emacs support for LaTeX cross-references and citations.
+@end direntry
+
+@finalout
+
+@c Macro definitions
+
+@c Subheadings inside a table.  Need a difference between info and the rest.
+@macro tablesubheading{text}
+@ifinfo
+@subsubheading \text\
+@end ifinfo
+@ifnotinfo
+@item @b{\text\}
+@end ifnotinfo
+@end macro
+
+@titlepage
+@title Ref@TeX{} User Manual
+@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
+@subtitle Edition @value{EDITION}, @value{DATE}
+
+@author by Carsten Dominik
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top,,,(dir)
+
+@b{Ref@TeX{}} 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
+@b{Ref@TeX{}} in great depth.  All you need to know to use
+@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
+Nutshell}).  You can go back later to other parts of this document when
+needed.
+
+@menu
+* Introduction::                     Quick-Start information.
+
+* Table of Contents::                A Tool to move around quickly.
+* Labels and References::            Creating and referencing labels.
+* Citations::                        Creating Citations.
+* Index Support::                    Creating and Checking Index Entries.
+* Viewing Cross-References::         Who references or cites what?
+
+* RefTeXs Menu::                     The Ref menu in the menubar.
+* Key Bindings::                      The default key bindings.
+* Faces::                            Fontification of RefTeX's buffers.
+* Multifile Documents::              Document spread over many files.
+* Language Support::                 How to support other languages.
+* Finding Files::                    Included TeX files and BibTeX .bib files.
+* AUCTeX::                           Cooperation with AUCTeX.
+* Optimizations::                    When RefTeX is too slow.
+* Problems and Work-Arounds::        First Aid.
+* Imprint::                          Author, Web-site, Thanks
+
+* Commands::                         Which are the available commands.
+* Options::                          How to extend and configure RefTeX.
+* Keymaps and Hooks::                For customization.
+* Changes::                          A List of recent changes to RefTeX.
+* GNU Free Documentation License::   The license for this documentation.
+
+The Index
+
+* Index::                            The full index.
+
+@detailmenu
+
+Introduction
+
+* Installation::                     How to install and activate RefTeX.
+* RefTeX in a Nutshell::             A brief summary and quick guide.
+
+Labels and References
+
+* Creating Labels::
+* Referencing Labels::
+* Builtin Label Environments::       The environments RefTeX knows about.
+* Defining Label Environments::        ... and environments it doesn't.
+* Reference Info::                   View the label corresponding to a \ref.
+* xr (LaTeX package)::               References to external documents.
+* varioref (LaTeX package)::         How to create \vref instead of \ref.
+* fancyref (LaTeX package)::         How to create \fref instead of \ref.
+
+Defining Label Environments
+
+* Theorem and Axiom::                Defined with @code{\newenvironment}.
+* Quick Equation::                   When a macro sets the label type.
+* Figure Wrapper::                   When a macro argument is a label.
+* Adding Magic Words::               Other words for other languages.
+* Using \eqref::                     How to switch to this AMS-LaTeX macro.
+* Non-Standard Environments::        Environments without \begin and \end
+* Putting it Together::              How to combine many entries.
+
+Citations
+
+* Creating Citations::               How to create them.
+* Citation Styles::                  Natbib, Harvard, Chicago and Co.
+* Citation Info::                    View the corresponding database entry.
+* Chapterbib and Bibunits::          Multiple bibliographies in a Document.
+* Citations Outside LaTeX::          How to make citations in Emails etc.
+* BibTeX Database Subsets::          Extract parts of a big database. 
+
+Index Support
+
+* Creating Index Entries::           Macros and completion of entries.
+* The Index Phrases File::           A special file for global indexing.
+* Displaying and Editing the Index:: The index editor.
+* Builtin Index Macros::             The index macros RefTeX knows about.
+* Defining Index Macros::                ... and macros it  doesn't.
+
+The Index Phrases File
+
+* Collecting Phrases::               Collecting from document or external.
+* Consistency Checks::               Check for duplicates etc.
+* Global Indexing::                  The interactive indexing process.
+
+AUCTeX
+
+* AUCTeX-RefTeX Interface::          How both packages work together
+* Style Files::                      AUCTeX's style files can support RefTeX
+* Bib-Cite::                         Hypertext reading of a document
+
+Options, Keymaps, Hooks
+
+* 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)::
+
+@end detailmenu
+@end menu
+
+@end ifnottex
+
+@node Introduction, Table of Contents, , Top
+@chapter Introduction
+@cindex Introduction
+
+@b{Ref@TeX{}} is a specialized package for support of labels,
+references, citations, and the index in LaTeX.  @b{Ref@TeX{}} wraps
+itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
+and @code{\index}.  Using these macros usually requires looking up
+different parts of the document and searching through BibTeX database
+files.  @b{Ref@TeX{}} 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.
+
+@iftex
+Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
+in great depth.  All you need to know to use @b{Ref@TeX{}} can be
+summarized on two pages (@pxref{RefTeX in a Nutshell}).  You can go
+back later to other parts of this document when needed.
+@end iftex
+
+@xref{Imprint}, for information about who to contact for help, bug
+reports or suggestions.
+
+@menu
+* Installation::                     How to install and activate RefTeX.
+* RefTeX in a Nutshell::             A brief summary and quick guide.
+@end menu
+
+@node Installation, RefTeX in a Nutshell, , Introduction
+@section Installation
+@cindex Installation
+
+@b{Ref@TeX{}} 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 @value{XEMACSFTP}.  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 @b{Ref@TeX{}} distribution from the maintainers web-page.
+@xref{Imprint}, for more information.
+
+@section Environment
+@cindex Finding files
+@cindex BibTeX database files, not found
+@cindex TeX files, not found
+@cindex @code{TEXINPUTS}, environment variable
+@cindex @code{BIBINPUTS}, environment variable
+
+@b{Ref@TeX{}} needs to access all files which are part of a multifile
+document, and the BibTeX database files requested by the
+@code{\bibliography} command.  To find these files, @b{Ref@TeX{}} will
+require a search path, i.e. a list of directories to check.  Normally
+this list is stored in the environment variables @code{TEXINPUTS} and
+@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}.  However, on some
+systems these variables do not contain the full search path.  If
+@b{Ref@TeX{}} does not work for you because it cannot find some files,
+read @ref{Finding Files}.
+
+@section Entering @b{Ref@TeX{}} Mode
+
+@findex turn-on-reftex
+@findex reftex-mode
+@vindex LaTeX-mode-hook
+@vindex latex-mode-hook
+To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
+@kbd{M-x reftex-mode}.  To turn on @b{Ref@TeX{}} Mode for all LaTeX
+files, add the following lines to your @file{.emacs} file:
+
+@example
+(add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
+(add-hook 'latex-mode-hook 'turn-on-reftex)   ; with Emacs latex mode
+@end example
+
+@page
+@node RefTeX in a Nutshell, , Installation, Introduction
+@section @b{Ref@TeX{}} in a Nutshell
+@cindex Quick-Start
+@cindex Getting Started
+@cindex RefTeX in a Nutshell
+@cindex Nutshell, RefTeX in a
+
+@enumerate
+@item
+@b{Table of Contents}@* Typing @kbd{C-c =} (@code{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 @kbd{?} to get
+help.
+
+@item
+@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
+and to find the correct key for references quickly.  It distinguishes
+labels for different environments, knows about all standard
+environments (and many others), and can be configured to recognize any
+additional labeled environments you have defined yourself (variable
+@code{reftex-label-alist}).
+
+@itemize @bullet
+@item
+@b{Creating Labels}@*
+Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
+@b{Ref@TeX{}} will either
+@itemize @minus
+@item
+derive a label from context (default for section labels)
+@item
+prompt for a label string (default for figures and tables) or
+@item
+insert a simple label made of a prefix and a number (all other
+environments)
+@end itemize
+@noindent
+Which labels are created how is configurable with the variable
+@code{reftex-insert-label-flags}.
+
+@item
+@b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
+(@code{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 @code{\ref@{@var{label}@}} macro
+into the original buffer.
+@end itemize
+
+@item
+@b{Citations}@*
+Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
+regular expression to search in current BibTeX database files (as
+specified in the @code{\bibliography} command) and pull out a list of
+matches for you to choose from.  The list is @emph{formatted} and
+sorted.  The selected article is referenced as @samp{\cite@{@var{key}@}}
+(see the variable @code{reftex-cite-format} if you want to insert
+different macros).
+
+@item
+@b{Index Support}@*
+@b{Ref@TeX{}} helps to enter index entries.  It also compiles all
+entries into an alphabetically sorted @file{*Index*} buffer which you
+can use to check and edit the entries.  @b{Ref@TeX{}} knows about the
+standard index macros and can be configured to recognize any additional
+macros you have defined (@code{reftex-index-macros}).  Multiple indices
+are supported.
+
+@itemize @bullet
+@item
+@b{Creating Index Entries}@*
+To index the current selection or the word at point, type @kbd{C-c /}
+(@code{reftex-index-selection-or-word}).  The default macro
+@code{reftex-index-default-macro} will be used.  For a more complex entry
+type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
+and enter the arguments with completion.
+
+@item
+@b{The Index Phrases File (Delayed Indexing)}@*
+Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
+the current word or selection to a special @emph{index phrase file}.
+@b{Ref@TeX{}} can later search the document for occurrences of these
+phrases and let you interactively index the matches.
+
+@item
+@b{Displaying and Editing the Index}@*
+To display the compiled index in a special buffer, type @kbd{C-c >}
+(@code{reftex-display-index}).  From that buffer you can check and edit
+all entries.
+@end itemize
+
+@page
+@item @b{Viewing Cross-References}@*
+When point is on the @var{key} argument of a cross--referencing macro
+(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\index}, and variations) or inside a BibTeX database entry, you
+can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
+corresponding locations in the document and associated BibTeX database
+files. @*
+When the enclosing macro is @code{\cite} or @code{\ref} and no other
+message occupies the echo area, information about the citation or label
+will automatically be displayed in the echo area.
+
+@item
+@b{Multifile Documents}@*
+Multifile Documents are fully supported.  The included files must have a
+file variable @code{TeX-master} or @code{tex-main-file} pointing to the
+master file.  @b{Ref@TeX{}} provides cross-referencing information from
+all parts of the document, and across document borders
+(@file{xr.sty}).
+
+@item
+@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
+order to find labels and other information.  It does it automatically
+once and updates its list internally when @code{reftex-label} and
+@code{reftex-index} are used.  To enforce reparsing, call any of the
+commands described above with a raw @kbd{C-u} prefix, or press the
+@kbd{r} key in the label selection buffer, the table of contents
+buffer, or the index buffer.
+
+@item
+@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
+cooperate with it (see variable @code{reftex-plug-into-AUCTeX}).  AUCTeX
+contains style files which trigger appropriate settings in
+@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
+additional customizations will be necessary.
+
+@item
+@b{Useful Settings}@*
+To integrate RefTeX with AUCTeX, use
+@lisp
+(setq reftex-plug-into-AUCTeX t)
+@end lisp
+
+To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
+customize the variables
+@example
+@code{reftex-label-alist}          @r{(for label macros/environments)}
+@code{reftex-section-levels}       @r{(for sectioning commands)}
+@code{reftex-cite-format}          @r{(for @code{\cite}-like macros)}
+@code{reftex-index-macros}         @r{(for @code{\index}-like macros)}
+@code{reftex-index-default-macro}  @r{(to set the default macro)}
+@end example
+If you have a large number of macros defined, you may want to write
+an AUCTeX style file to support them with both AUCTeX and
+@b{Ref@TeX{}}.
+
+@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}.  Use its menus
+until you have picked up the key bindings.  For an overview of what you
+can do in each of the different special buffers, press @kbd{?}.  Read
+the manual if you get stuck, of if you are curious what else might be
+available.  The first part of the manual explains in
+a tutorial way how to use and customize @b{Ref@TeX{}}.  The second
+part is a command and variable reference.
+@end enumerate
+
+@node Table of Contents, Labels and References, Introduction, Top
+@chapter Table of Contents
+@cindex @file{*toc*} buffer
+@cindex Structure editing
+@cindex Table of contents buffer
+@findex reftex-toc
+@kindex C-c =
+
+Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
+contents of the document.  By default, this @file{*toc*} buffer shows
+only the sections of a document.  Using the @kbd{l} and @kbd{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.
+
+@kindex ?
+Here is a list of special commands in the @file{*toc*} buffer.  A
+summary of this information is always available by pressing
+@kbd{?}.
+
+@table @kbd
+
+@tablesubheading{General}
+@item ?
+Display a summary of commands.
+
+@item 0-9, -
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Goto next entry in the table of context.
+
+@item p
+Goto previous entry in the table of context.
+
+@item C-c C-n
+Goto next section heading.  Useful when many labels and index entries
+separate section headings.
+
+@item C-c C-p
+Goto previous section heading.
+
+@item N z
+Jump to section N, using the prefix arg.  For example, @kbd{3 z} jumps
+to section 3.
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the corresponding location in another window.  This command does
+@emph{not} select that other window.
+
+@item @key{TAB}
+Goto the location in another window.
+
+@item @key{RET}
+Go to the location and hide the @file{*toc*} buffer.  This will restore
+the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
+called.
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a line has the same effect as @key{RET}.
+See also variable @code{reftex-highlight-selection}, @ref{Options
+(Fontification)}.
+
+@item f
+@vindex reftex-toc-follow-mode
+@vindex reftex-revisit-to-follow
+Toggle follow mode.  When follow mode is active, the other window will
+always show the location corresponding to the line at point in the
+@file{*toc*} buffer.  This is similar to pressing @key{SPC} after each
+cursor motion.  The default for this flag can be set with the variable
+@code{reftex-toc-follow-mode}.  Note that only context in files already
+visited is shown.  @b{Ref@TeX{}} will not visit a file just for follow
+mode.  See, however, the variable
+@code{reftex-revisit-to-follow}.
+
+@item .
+Show calling point in another window.  This is the point from where
+@code{reftex-toc} was last called.
+
+@page
+@tablesubheading{Promotion and Demotion}
+
+@item <
+Promote the current section.  This will convert @code{\section} to
+@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
+an active region, all sections in the region will be promoted, including
+the one at point.  To avoid mistakes, @b{Ref@TeX{}} requires a fresh
+document scan before executing this command - if necessary, it will
+automatically do this scan and ask the user to repeat the promotion
+command.
+
+@item >
+Demote the current section.  This is the opposite of promotion.  It will
+convert @code{\chapter} to @code{\section} etc.  If there is an active
+region, all sections in the region will be demoted, including the one at
+point.
+
+@item M-%
+Rename the label at point.  While generally not recommended, this can be
+useful when a package like @file{fancyref} is used where the label
+prefix determines the wording of a reference.  After a
+promotion/demotion it may be necessary to change a few labels from
+@samp{sec:xyz} to @samp{cha:xyz} or vice versa.  This command can be
+used to do this - it launches a query replace to rename the definition
+and all references of a label.
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.
+
+@item k
+Kill the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.
+
+@item C-c >
+Switch to the @file{*Index*} buffer of this document.  With prefix
+@samp{2}, restrict the index to the section at point in the @file{*toc*}
+buffer.
+
+@tablesubheading{Controlling what gets displayed}
+
+@item t
+@vindex reftex-toc-max-level
+Change the maximum level of toc entries displayed in the @file{*toc*}
+buffer.  Without prefix arg, all levels will be included.  With prefix
+arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
+@var{arg} (3 in this case).  Chapters are level 1, sections are level 2.
+The mode line @samp{T<>} indicator shows the current value.  The default
+depth can be configured with the variable
+@code{reftex-toc-max-level}.
+
+@item F
+@vindex reftex-toc-include-file-boundaries
+Toggle the display of the file borders of a multifile document in the
+@file{*toc*} buffer.  The default for this flag can be set with the
+variable @code{reftex-toc-include-file-boundaries}.
+
+@item l
+@vindex reftex-toc-include-labels
+Toggle the display of labels in the @file{*toc*} buffer.  The default
+for this flag can be set with the variable
+@code{reftex-toc-include-labels}.  When called with a prefix argument,
+@b{Ref@TeX{}} will prompt for a label type and include only labels of
+the selected type in the @file{*toc*} buffer.  The mode line @samp{L<>}
+indicator shows which labels are included.
+
+@item i
+@vindex reftex-toc-include-index-entries
+Toggle the display of index entries in the @file{*toc*} buffer.  The
+default for this flag can be set with the variable
+@code{reftex-toc-include-index-entries}.  When called with a prefix
+argument, @b{Ref@TeX{}} will prompt for a specific index and include
+only entries in the selected index in the @file{*toc*} buffer.  The mode
+line @samp{I<>} indicator shows which index is used.
+
+@item c
+@vindex reftex-toc-include-context
+Toggle the display of label and index context in the @file{*toc*}
+buffer.  The default for this flag can be set with the variable
+@code{reftex-toc-include-context}.
+
+@tablesubheading{Updating the buffer}
+
+@item g
+Rebuild the @file{*toc*} buffer.  This does @emph{not} rescan the
+document.
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the LaTeX document and rebuild the @file{*toc*} buffer.  When
+@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
+location is defined in, not the entire document.
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
+buffer.
+
+@item x
+Switch to the @file{*toc*} buffer of an external document.  When the
+current document is using the @code{xr} package (@pxref{xr (LaTeX
+package)}), @b{Ref@TeX{}} will switch to one of the external
+documents.
+
+
+@tablesubheading{Automatic recentering}
+
+@item d
+Toggle the display of a dedicated frame displaying just the @file{*toc*}
+buffer.  Follow mode and visiting locations will not work that frame,
+but automatic recentering will make this frame always show your current
+editing location in the document (see below).
+
+@item a
+Toggle the automatic recentering of the @file{*toc*} buffer.  When this
+option is on, moving around in the document will cause the @file{*toc*}
+to always highlight the current section.  By default, this option is
+active while the dedicated @file{*TOC*} frame exists.  See also the
+variable @code{reftex-auto-recenter-toc}.
+
+@end table
+
+@vindex reftex-toc-map
+In order to define additional commands for the @file{*toc*} buffer, the
+keymap @code{reftex-toc-map} may be used.
+
+@findex reftex-toc-recenter
+@vindex reftex-auto-recenter-toc
+@vindex reftex-idle-time
+@cindex @file{*toc*} buffer, recentering
+@cindex Table of contents buffer, recentering
+@kindex C-c -
+If you call @code{reftex-toc} while the @file{*toc*} buffer already
+exists, the cursor will immediately jump to the right place, i.e. the
+section from which @code{reftex-toc} was called will be highlighted.
+The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
+the @file{*toc*} buffer and highlight the correct line without actually
+selecting the @file{*toc*} window.  This can be useful to quickly find
+out where in the document you currently are.  You can also automate this
+by asking RefTeX to keep track of your current editing position in the
+TOC.  The TOC window will then be updated whenever you stop typing for
+more than @code{reftex-idle-time} seconds.  By default this works only
+with the dedicated @file{*TOC*} frame.  But you can also force automatic
+recentering of the TOC window on the current frame with
+@lisp
+(setq reftex-auto-recenter-toc t)
+@end lisp
+
+
+@cindex Sectioning commands
+@cindex KOMA-Script, LaTeX classes
+@cindex LaTeX classes, KOMA-Script
+@cindex TOC entries for environments
+@vindex reftex-section-levels
+The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
+macros (from @code{\part} to @code{\subsubparagraph}) and the commands
+@code{\addchap} and @code{\addsec} from the KOMA-Script classes.
+Additional macros can be configured with the variable
+@code{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. @xref{Defining Label Environments}, for an
+example.
+
+@node Labels and References, Citations, Table of Contents, Top
+@chapter Labels and References
+@cindex Labels in LaTeX
+@cindex References in LaTeX
+@cindex Label category
+@cindex Label environment
+@cindex @code{\label}
+
+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 @samp{\label@{mark@}}.  LaTeX records the current value of a
+certain counter when a label is defined.  Later references to this label
+(like @samp{\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 @code{equation} and
+@code{eqnarray} environments record the value of the same counter - the
+equation counter.
+
+@menu
+* Creating Labels::
+* Referencing Labels::
+* Builtin Label Environments::       The environments RefTeX knows about.
+* Defining Label Environments::        ... and environments it doesn't.
+* Reference Info::                   View the label corresponding to a \ref.
+* xr (LaTeX package)::               References to external documents.
+* varioref (LaTeX package)::         How to create \vref instead of \ref.
+* fancyref (LaTeX package)::         How to create \fref instead of \ref.
+@end menu
+
+@node Creating Labels, Referencing Labels, , Labels and References
+@section Creating Labels
+@cindex Creating labels
+@cindex Labels, creating
+@cindex Labels, deriving from context
+@kindex C-c (
+@findex reftex-label
+
+In order to create a label in a LaTeX document, press @kbd{C-c (}
+(@code{reftex-label}).  Just like LaTeX, @b{Ref@TeX{}} 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.  @b{Ref@TeX{}} has
+3 different modes to create this mark.
+
+@enumerate
+@item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-derive-label-parameters
+@vindex reftex-label-illegal-re
+@vindex reftex-abbrev-parameters
+A label can be derived from context.  This means, @b{Ref@TeX{}} takes
+the context of the label definition and constructs a label from
+that@footnote{Note that the context may contain constructs which are
+invalid in labels.  @b{Ref@TeX{}} will therefore strip the accent from
+accented Latin-1 characters and remove everything else which is not
+valid 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: @code{reftex-translate-to-ascii-function},
+@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
+@code{reftex-abbrev-parameters}.}.  This works best for section labels,
+where the section heading is used to construct a label.  In fact,
+@b{Ref@TeX{}}'s default settings use this method only for section
+labels.  You will be asked to confirm the derived label, or edit
+it.
+
+@item
+We may also use a simple unique number to identify a label.  This is
+mostly useful for labels where it is difficult to come up with a very
+good descriptive name.  @b{Ref@TeX{}}'s default settings use this method
+for equations, enumerate items and footnotes.  The author of @b{Ref@TeX{}}
+tends to write documents with many equations and finds it impossible
+to come up with good names for each of them.  These simple labels are
+inserted without query, and are therefore very fast.  Good descriptive
+names are not really necessary as @b{Ref@TeX{}} will provide context to
+reference a label (@pxref{Referencing Labels}).
+
+@item
+The third method is to ask the user for a label.  This is most
+useful for things which are easy to describe briefly and do not turn up
+too frequently in a document.  @b{Ref@TeX{}} uses this for figures and
+tables.  Of course, one can enter the label directly by typing the full
+@samp{\label@{mark@}}.  The advantage of using @code{reftex-label}
+anyway is that @b{Ref@TeX{}} 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.
+@end enumerate
+
+@vindex reftex-insert-label-flags
+If you want to change the way certain labels are created, check out the
+variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
+Labels)}).
+
+If you are using AUCTeX to write your LaTeX documents, you can
+set it up to delegate the creation of labels to
+@b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
+
+@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
+@section Referencing Labels
+@cindex Referencing labels
+@cindex Labels, referencing
+@cindex Selection buffer, labels
+@cindex Selection process
+@cindex @code{\ref}
+@kindex C-c )
+@findex reftex-reference
+
+@vindex reftex-trust-label-prefix
+@b{Ref@TeX{}} scans the document in order to find all labels.  To make
+referencing labels easier, it assigns to each label a category, the
+@emph{label type} (for example section, table, figure, equation, etc.).
+In order to determine the label type, RefTeX parses around each label
+to see in what kind of environments it is located.  You can speed up
+the parsing by using type-specific prefixes for labels and configuring
+the variable @code{reftex-trust-label-prefix}.
+
+Referencing Labels is really at the heart of @b{Ref@TeX{}}.  Press @kbd{C-c
+)} in order to reference a label (reftex-reference).  This will start a
+selection process and finally insert the complete @samp{\ref@{label@}}
+into the buffer.
+
+First, @b{Ref@TeX{}} will determine the label category which is required.
+Often that can be figured out from context.  For example, if you
+write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} 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 @key{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 @key{RET}.  You can also reference several labels with a single
+call to @code{reftex-reference} by marking entries with the @kbd{m}
+key (see below).
+
+@kindex ?
+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 @kbd{?}.
+
+
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Show a summary of available commands.
+
+@item 0-9,-
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Go to next label.
+
+@item p
+Go to previous label.
+
+@item b
+Jump back to the position where you last left the selection buffer.
+Normally this should get you back to the last referenced label.
+
+@item C-c C-n
+Goto next section heading.
+
+@item C-c C-p
+Goto previous section heading.
+
+@item N z
+Jump to section N, using the prefix arg.  For example @kbd{3 z} jumps to
+section 3.
+
+@tablesubheading{Displaying Context}
+@item @key{SPC}
+Show the surroundings of the definition of the current label in another
+window.  See also the @kbd{f} key.
+
+@item f
+@vindex reftex-revisit-to-follow
+Toggle follow mode.  When follow mode is active, the other window will
+always display the full context of the current label.  This is similar
+to pressing @key{SPC} after each cursor motion.  Note that only context
+in files already visited is shown.  @b{RefTeX} will not visit a file
+just for follow mode.  See, however, the variable
+@code{reftex-revisit-to-follow}.
+
+@item .
+Show insertion point in another window.  This is the point from where you
+called @code{reftex-reference}.
+
+@tablesubheading{Selecting a label and creating the reference}
+@item @key{RET}
+Insert a reference to the label at point into the buffer from which the
+selection process was started.  When entries have been marked, @key{RET}
+references all marked labels.
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a label will accept it like @key{RET}
+would. See also variable @code{reftex-highlight-selection}, @ref{Options
+(Misc)}.
+
+@vindex reftex-multiref-punctuation
+@item m - + ,
+Mark the current entry.  When several entries have been marked, pressing
+@kbd{RET} will accept all of them and place them into several
+@code{\ref} macros.  The special markers @samp{,-+} also store a
+separator to be inserted before the corresponding reference.  So marking
+six entries with the keys @samp{m , , - , +} will give a reference list
+like this (see the variable @code{reftex-multiref-punctuation})
+@example
+In eqs. (1), (2), (3)--(4), (5) and (6)
+@end example
+
+@item u
+Unmark a marked entry.
+
+@c FIXME: Do we need `A' as well for consistency?
+@cindex LaTeX packages, @code{saferef}
+@cindex @code{saferef}, LaTeX package
+@item a
+Accept the marked entries and put all labels as a comma-separated list
+into one @emph{single} @code{\ref} macro.  Some packages like
+@file{saferef.sty} support multiple references in this way.
+
+@item l
+Use the last referenced label(s) again.  This is equivalent to moving to
+that label and pressing @key{RET}.
+
+@item @key{TAB}
+Enter a label with completion.  This may also be a label which does not
+yet exist in the document.
+
+@item v
+@cindex @code{varioref}, LaTeX package
+@cindex @code{\vref}
+@cindex LaTeX packages, @code{varioref}
+Toggle between @code{\ref} and @code{\vref} macro for references.  The
+@code{\vref} macro is defined in the @code{varioref} LaTeX package.
+With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
+macro.  The current state of this flag is displayed by the @samp{S<>}
+indicator in the mode line of the selection buffer.
+
+@item V
+@cindex @code{fancyref}, LaTeX package
+@cindex @code{\fref}
+@cindex @code{\Fref}
+@cindex LaTeX packages, @code{fancyref}
+Cycle between @code{\ref}, @code{\fref} and @code{\Fref}.  The
+@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
+LaTeX package.  With this key you can force @b{Ref@TeX{}} to insert a
+@code{\fref} or @code{\Fref} macro.  The current state of this flag is
+displayed by the @samp{S<>} indicator in the mode line of the
+selection buffer.
+
+@tablesubheading{Exiting}
+
+@item q
+Exit the selection process without inserting any reference into the
+buffer.
+
+@tablesubheading{Controlling what gets displayed}
+@vindex reftex-label-menu-flags
+The defaults for the following flags can be configured with the variable
+@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
+
+@item c
+Toggle the display of the one-line label definition context in the
+selection buffer.
+
+@item F
+Toggle the display of the file borders of a multifile document in the
+selection buffer.
+
+@item t
+Toggle the display of the table of contents in the selection buffer.
+With prefix @var{arg}, change the maximum level of toc entries displayed
+to @var{arg}.  Chapters are level 1, section are level 2.
+
+@item #
+Toggle the display of a label counter in the selection buffer.
+
+@item %
+Toggle the display of labels hidden in comments in the selection
+buffers.  Sometimes, you may have commented out parts of your document.
+If these parts contain label definitions, @b{Ref@TeX{}} can still display
+and reference these labels.
+
+@tablesubheading{Updating the buffer}
+@item g
+Update the menu.  This will rebuilt the menu from the internal label
+list, but not reparse the document (see @kbd{r}).
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the document to update the information on all labels and rebuild
+the menu.  If the variable @code{reftex-enable-partial-scans} is
+non-@code{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).
+
+@item C-u r
+Reparse the @emph{entire} document.
+
+@item s
+Switch the label category.  After prompting for another label category,
+a menu for that category will be shown.
+
+@item x
+Reference a label from an external document.  With the LaTeX package
+@code{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 (@pxref{xr (LaTeX
+package),,xr}).
+
+@end table
+
+@vindex reftex-select-label-map
+In order to define additional commands for the selection process, the
+keymap @code{reftex-select-label-map} may be used.
+
+@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
+@section Builtin Label Environments
+@cindex Builtin label environments
+@cindex Label environments, builtin
+@cindex Environments, builtin
+@vindex reftex-label-alist
+@vindex reftex-label-alist-builtin
+
+@b{Ref@TeX{}} needs to be aware of the environments which can be referenced
+with a label (i.e. which carry their own counters).  By default, @b{Ref@TeX{}}
+recognizes all labeled environments and macros discussed in @cite{The
+LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
+1994.}.  These are:
+
+@itemize @minus
+@item
+@cindex @code{figure}, LaTeX environment
+@cindex @code{figure*}, LaTeX environment
+@cindex @code{table}, LaTeX environment
+@cindex @code{table*}, LaTeX environment
+@cindex @code{equation}, LaTeX environment
+@cindex @code{eqnarray}, LaTeX environment
+@cindex @code{enumerate}, LaTeX environment
+@cindex @code{\footnote}, LaTeX macro
+@cindex LaTeX macro @code{footnote}
+@cindex LaTeX core
+@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
+@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
+the LaTeX core stuff)
+@item
+@cindex AMS-LaTeX
+@cindex @code{amsmath}, LaTeX package
+@cindex LaTeX packages, @code{amsmath}
+@cindex @code{align}, AMS-LaTeX environment
+@cindex @code{gather}, AMS-LaTeX environment
+@cindex @code{multline}, AMS-LaTeX environment
+@cindex @code{flalign}, AMS-LaTeX environment
+@cindex @code{alignat}, AMS-LaTeX environment
+@cindex @code{xalignat}, AMS-LaTeX environment
+@cindex @code{xxalignat}, AMS-LaTeX environment
+@cindex @code{subequations}, AMS-LaTeX environment
+@code{align}, @code{gather}, @code{multline}, @code{flalign},
+@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
+(from AMS-LaTeX's @file{amsmath.sty} package)
+@item
+@cindex @code{endnote}, LaTeX package
+@cindex LaTeX packages, @code{endnote}
+@cindex @code{\endnote}, LaTeX macro
+the @code{\endnote} macro (from @file{endnotes.sty})
+@item
+@cindex @code{fancybox}, LaTeX package
+@cindex LaTeX packages, @code{fancybox}
+@cindex @code{Beqnarray}, LaTeX environment
+@code{Beqnarray} (@file{fancybox.sty})
+@item
+@cindex @code{floatfig}, LaTeX package
+@cindex LaTeX packages, @code{floatfig}
+@cindex @code{floatingfig}, LaTeX environment
+@code{floatingfig} (@file{floatfig.sty})
+@item
+@cindex @code{longtable}, LaTeX package
+@cindex LaTeX packages, @code{longtable}
+@cindex @code{longtable}, LaTeX environment
+@code{longtable} (@file{longtable.sty})
+@item
+@cindex @code{picinpar}, LaTeX package
+@cindex LaTeX packages, @code{picinpar}
+@cindex @code{figwindow}, LaTeX environment
+@cindex @code{tabwindow}, LaTeX environment
+@code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
+@item
+@cindex @code{sidecap}, LaTeX package
+@cindex LaTeX packages, @code{sidecap}
+@cindex @code{SCfigure}, LaTeX environment
+@cindex @code{SCtable}, LaTeX environment
+@code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
+@item
+@cindex @code{rotating}, LaTeX package
+@cindex LaTeX packages, @code{rotating}
+@cindex @code{sidewaysfigure}, LaTeX environment
+@cindex @code{sidewaystable}, LaTeX environment
+@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
+@item
+@cindex @code{subfig}, LaTeX package
+@cindex LaTeX packages, @code{subfigure}
+@cindex @code{subfigure}, LaTeX environment
+@cindex @code{subfigure*}, LaTeX environment
+@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
+(@file{subfigure.sty})
+@item
+@cindex @code{supertab}, LaTeX package
+@cindex LaTeX packages, @code{supertab}
+@cindex @code{supertabular}, LaTeX environment
+@code{supertabular} (@file{supertab.sty})
+@item
+@cindex @code{wrapfig}, LaTeX package
+@cindex LaTeX packages, @code{wrapfig}
+@cindex @code{wrapfigure}, LaTeX environment
+@code{wrapfigure} (@file{wrapfig.sty})
+@end itemize
+
+If you want to use other labeled environments, defined with
+@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
+them (@pxref{Defining Label Environments}).
+
+@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
+@section Defining Label Environments
+@cindex Label environments, defining
+
+@vindex reftex-label-alist
+@b{Ref@TeX{}} can be configured to recognize additional labeled
+environments and macros.  This is done with the variable
+@code{reftex-label-alist} (@pxref{Options (Defining Label
+Environments)}).  If you are not familiar with Lisp, you can use the
+@code{custom} library to configure this rather complex variable.  To do
+this, use
+
+@example
+@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
+@end example
+
+@vindex reftex-label-alist-builtin
+Here we will discuss a few examples, in order to make things clearer.
+It can also be instructive to look at the constant
+@code{reftex-label-alist-builtin} which contains the entries for
+all the builtin environments and macros (@pxref{Builtin Label
+Environments}).
+
+@menu
+* Theorem and Axiom::                Defined with @code{\newenvironment}.
+* Quick Equation::                   When a macro sets the label type.
+* Figure Wrapper::                   When a macro argument is a label.
+* Adding Magic Words::               Other words for other languages.
+* Using \eqref::                     How to switch to this AMS-LaTeX macro.
+* Non-Standard Environments::        Environments without \begin and \end
+* Putting it Together::              How to combine many entries.
+@end menu
+
+@node Theorem and Axiom, Quick Equation, , Defining Label Environments
+@subsection Theorem and Axiom Environments
+@cindex @code{theorem}, newtheorem
+@cindex @code{axiom}, newtheorem
+@cindex @code{\newtheorem}
+
+Suppose you are using @code{\newtheorem} in LaTeX in order to define two
+new environments, @code{theorem} and @code{axiom}
+
+@example
+\newtheorem@{axiom@}@{Axiom@}
+\newtheorem@{theorem@}@{Theorem@}
+@end example
+
+@noindent
+to be used like this:
+
+@example
+\begin@{axiom@}
+\label@{ax:first@}
+  ....
+\end@{axiom@}
+@end example
+
+So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
+labeled environments which define their own label categories.  We can
+either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
+library.  With Lisp it would look like this
+
+@lisp
+(setq reftex-label-alist
+   '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
+     ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "th.") -3)))
+@end lisp
+
+The type indicator characters @code{?a} and @code{?h} are used for
+prompts when @b{Ref@TeX{}} queries for a label type.  @code{?h}
+was chosen for @code{theorem} since @code{?t} is already taken by
+@code{table}.  Note that also @code{?s}, @code{?f}, @code{?e},
+@code{?i}, @code{?n} are already used for standard environments.
+
+@noindent
+The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
+@samp{thr:}, respectively.  @xref{AUCTeX}, for information on how
+AUCTeX can use RefTeX to automatically create labels when a new environment
+is inserted into a buffer.  Additionally, the following needs to be
+added to one's .emacs file before AUCTeX will automatically create
+labels for the new environments.
+
+@lisp
+(add-hook 'LaTeX-mode-hook
+   (lambda ()
+     (LaTeX-add-environments
+       '("axiom" LaTeX-env-label)
+       '("theorem" LaTeX-env-label))))
+@end lisp
+
+
+@noindent
+The @samp{~\ref@{%s@}} is a format string indicating how to insert
+references to these labels.
+
+@noindent
+The next item indicates how to grab context of the label definition.
+@itemize @minus
+@item
+@code{t} means to get it from a default location (from the beginning of
+a @code{\macro} or after the @code{\begin} statement).  @code{t} is
+@emph{not} a good choice for eqnarray and similar environments.
+@item
+@code{nil} means to use the text right after the label definition.
+@item
+For more complex ways of getting context, see the variable
+@code{reftex-label-alist} (@ref{Options (Defining Label
+Environments)}).
+@end itemize
+
+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: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
+@b{Ref@TeX{}} 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
+@code{\section}), if it is negative the entries will be unnumbered (like
+@code{\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 @code{customize}, you need to click on
+the @code{[INS]} button twice to create two templates and fill them in
+like this:
+
+@example
+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
+@end example
+
+@vindex reftex-insert-label-flags
+@vindex reftex-label-menu-flags
+Depending on how you would like the label insertion and selection for
+the new environments to work, you might want to add the letters @samp{a}
+and @samp{h} to some of the flags in the variables
+@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
+and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
+Labels)}).
+
+
+@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
+@subsection Quick Equation Macro
+@cindex Quick equation macro
+@cindex Macros as environment wrappers
+
+Suppose you would like to have a macro for quick equations.  It
+could be defined like this:
+
+@example
+\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
+@end example
+
+@noindent
+and used like this:
+
+@example
+Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
+@end example
+
+We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
+@code{\quickeq} is an equation label.  Here is how to do this with lisp:
+
+@lisp
+(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
+@end lisp
+
+The first element in this list is now the macro with empty braces as an
+@emph{image} of the macro arguments.  @code{?e} indicates that this is
+an equation label, the different @code{nil} elements indicate to use the
+default values for equations.  The @samp{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:
+
+@example
+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
+@end example
+
+@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
+@subsection Figure Wrapping Macro
+@cindex Macros as environment wrappers
+@cindex Figure wrapping macro
+
+Suppose you want to make figures not directly with the figure
+environment, but with a macro like
+
+@example
+\newcommand@{\myfig@}[5][tbp]@{%
+  \begin@{figure@}[#1]
+    \epsimp[#5]@{#2@}
+    \caption@{#3@}
+    \label@{#4@}
+  \end@{figure@}@}
+@end example
+
+@noindent
+which would be called like
+
+@example
+\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
+@end example
+
+Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
+@code{\myfig} macro @emph{is itself} a figure label, and where to find
+the context.
+
+@lisp
+(setq reftex-label-alist
+      '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
+@end lisp
+
+The empty pairs of brackets indicate the different arguments of the
+@code{\myfig} macro. The @samp{*} marks the label argument.  @code{?f}
+indicates that this is a figure label which will be listed together with
+labels from normal figure environments.  The @code{nil} entries for
+prefix and reference format mean to use the defaults for figure labels.
+The @samp{3} for the context method means to grab the 3rd macro argument
+- the caption.
+
+As a side effect of this configuration, @code{reftex-label} will now
+insert the required naked label (without the @code{\label} macro) when
+point is directly after the opening parenthesis of a @code{\myfig} macro
+argument.
+
+Again, here the configuration in the customization buffer:
+
+@example
+[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
+@end example
+
+@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
+@subsection Adding Magic Words
+@cindex Magic words
+@cindex German magic words
+@cindex Label category
+
+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
+@code{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.
+
+@lisp
+(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"))))
+@end lisp
+
+@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
+@subsection Using @code{\eqref}
+@cindex @code{\eqref}, AMS-LaTeX macro
+@cindex AMS-LaTeX
+@cindex Label category
+
+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 @code{\eqref} for doing equation references.  Here is how to
+do this:
+
+@lisp
+(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
+@end lisp
+
+@b{Ref@TeX{}} has also a predefined symbol for this special purpose.  The
+following is equivalent to the line above.
+
+@lisp
+(setq reftex-label-alist '(AMSTeX))
+@end lisp
+
+Note that this is automatically done by the @file{amsmath.el} style file
+of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
+this configuration will not be necessary.
+
+@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
+@subsection Non-standard Environments
+@cindex Non-standard environments
+@cindex Environments without @code{\begin}
+@cindex Special parser functions
+@cindex Parser functions, for special environments
+
+Some LaTeX packages define environment-like structures without using the
+standard @samp{\begin..\end} structure.  @b{Ref@TeX{}} 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
+@code{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 @code{nil} on failure to detect
+the environment.  The function is called with one argument @var{bound}.
+If non-@code{nil}, @var{bound} is a boundary for backwards searches
+which should be observed.  We will discuss two examples.
+
+@cindex LaTeX commands, abbreviated
+
+Some people define abbreviations for
+environments, like @code{\be} for @code{\begin@{equation@}}, and
+@code{\ee} for @code{\end@{equation@}}.  The parser function would have
+to search backward for these macros.  When the first match is
+@code{\ee}, point is not in this environment.  When the first match is
+@code{\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 occur inside an equation environment.
+Here is the setup:
+
+@lisp
+;; 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
+@end lisp
+
+@cindex @code{linguex}, LaTeX package
+@cindex LaTeX packages, @code{linguex}
+A more complex example is the @file{linguex.sty} package which defines
+list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
+terminated by @samp{\z.} or by an empty line.
+
+@example
+\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
+@end example
+
+The difficulty is that the @samp{\a.} lists can nest and that an empty
+line terminates all list levels in one go.  So we have to count nesting
+levels between @samp{\a.} and @samp{\z.}.  Here is the implementation
+for @b{Ref@TeX{}}.
+
+@lisp
+(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))))))))
+@end lisp
+
+@node Putting it Together, , Non-Standard Environments, Defining Label Environments
+@subsection Putting it all together
+
+When you have to put several entries into @code{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:
+
+@lisp
+(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."))))
+@end lisp
+
+@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
+@section Reference Info
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+@cindex Cross-references, displaying
+@cindex Reference info
+@cindex Displaying cross-references
+@cindex Viewing cross-references
+@kindex C-c &
+@kindex S-mouse-2
+
+When point is idle for more than @code{reftex-idle-time} seconds on the
+argument of a @code{\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.
+
+@b{Ref@TeX{}} can also display the label definition corresponding to a
+@code{\ref} macro, or all reference locations corresponding to a
+@code{\label} macro.  @xref{Viewing Cross-References}, for more
+information.
+
+@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
+@section @code{xr}: Cross-Document References
+@cindex @code{xr}, LaTeX package
+@cindex LaTeX packages, @code{xr}
+@cindex @code{\externaldocument}
+@cindex External documents
+@cindex References to external documents
+@cindex Cross-document references
+
+The LaTeX package @code{xr} makes it possible to create references to
+labels defined in external documents.  The preamble of a document using
+@code{xr} will contain something like this:
+
+@example
+\usepackage@{xr@}
+\externaldocument[V1-]@{volume1@}
+\externaldocument[V3-]@{volume3@}
+@end example
+
+@noindent
+and we can make references to any labels defined in these
+external documents by using the prefixes @samp{V1-} and @samp{V3-},
+respectively.
+
+@b{Ref@TeX{}} can be used to create such references as well.  Start the
+referencing process normally, by pressing @kbd{C-c )}.  Select a label
+type if necessary.  When you see the label selection buffer, pressing
+@kbd{x} will switch to the label selection buffer of one of the external
+documents.  You may then select a label as before and @b{Ref@TeX{}} 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 (@pxref{Optimizations}).
+
+@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
+@section @code{varioref}: Variable Page References
+@cindex @code{varioref}, LaTeX package
+@cindex @code{\vref}
+@cindex LaTeX packages, @code{varioref}
+@vindex reftex-vref-is-default
+@code{varioref} is a frequently used LaTeX package to create
+cross--references with page information.  When you want to make a
+reference with the @code{\vref} macro, just press the @kbd{v} key in the
+selection buffer to toggle between @code{\ref} and @code{\vref}
+(@pxref{Referencing Labels}).  The mode line of the selection buffer
+shows the current status of this switch.  If you find that you almost
+always use @code{\vref}, you may want to make it the default by
+customizing the variable @code{reftex-vref-is-default}.  If this
+toggling seems too inconvenient, you can also use the command
+@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
+Or use AUCTeX to create your macros (@pxref{AUCTeX}).
+
+@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
+@section @code{fancyref}: Fancy Cross References
+@cindex @code{fancyref}, LaTeX package
+@cindex @code{\fref}
+@cindex @code{\Fref}
+@cindex LaTeX packages, @code{fancyref}
+@vindex reftex-fref-is-default
+@code{fancyref} is a LaTeX package where a macro call like
+@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
+the referenced counter but also the complete text around it, like
+@samp{Figure 3 on the preceding page}.  In order to make it work you
+need to use label prefixes like @samp{fig:} consistently - something
+@b{Ref@TeX{}} does automatically.  When you want to make a reference
+with the @code{\fref} macro, just press the @kbd{V} key in the selection
+buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
+(@pxref{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 @code{reftex-fancyref-fref}
+and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
+f} and @kbd{C-c F}.}.  Or use AUCTeX to create your macros
+(@pxref{AUCTeX}).
+
+@node Citations, Index Support, Labels and References, Top
+@chapter Citations
+@cindex Citations
+@cindex @code{\cite}
+
+Citations in LaTeX are done with the @code{\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
+@code{thebibliography} environment in the document.  @b{Ref@TeX{}}'s
+support for citations helps to select the correct key quickly.
+
+@menu
+* Creating Citations::               How to create them.
+* Citation Styles::                  Natbib, Harvard, Chicago and Co.
+* Citation Info::                    View the corresponding database entry.
+* Chapterbib and Bibunits::          Multiple bibliographies in a Document.
+* Citations Outside LaTeX::          How to make citations in Emails etc.
+* BibTeX Database Subsets::          Extract parts of a big database. 
+@end menu
+
+@node Creating Citations, Citation Styles, , Citations
+@section Creating Citations
+@cindex Creating citations
+@cindex Citations, creating
+@findex reftex-citation
+@kindex C-c [
+@cindex Selection buffer, citations
+@cindex Selection process
+
+In order to create a citation, press @kbd{C-c [}.  @b{Ref@TeX{}} 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
+(@pxref{Referencing Labels}).
+
+The regular expression uses an extended syntax: @samp{&&} defines a
+logic @code{and} for regular expressions. For example
+@samp{Einstein&&Bose} will match all articles which mention
+Bose-Einstein condensation, or which are co-authored by Bose and
+Einstein.  When entering the regular expression, you can complete on
+known citation keys.  RefTeX also offers a default when prompting for a
+regular expression.  This default is the word before the cursor or the
+word before the current @samp{\cite} command.  Sometimes this may be a
+good search key.
+
+@cindex @code{\bibliography}
+@cindex @code{thebibliography}, LaTeX environment
+@cindex @code{BIBINPUTS}, environment variable
+@cindex @code{TEXBIB}, environment variable
+@b{Ref@TeX{}} prefers to use BibTeX database files specified with a
+@code{\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 @code{BIBINPUTS}.
+If you do not use BibTeX, but the document contains an explicit
+@code{thebibliography} environment, @b{Ref@TeX{}} 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
+@code{\bibitem} entries, not the structured listing available with
+BibTeX database files.
+
+@kindex ?
+In the selection buffer, the following keys provide special commands.  A
+summary of this information is always available from the selection
+process by pressing @kbd{?}.
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Show a summary of available commands.
+
+@item 0-9,-
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Go to next article.
+
+@item p
+Go to previous article.
+
+@tablesubheading{Access to full database entries}
+@item @key{SPC}
+Show the database entry corresponding to the article at point, in
+another window.  See also the @kbd{f} key.
+
+@item f
+Toggle follow mode.  When follow mode is active, the other window will
+always display the full database entry of the current article.  This is
+equivalent to pressing @key{SPC} after each cursor motion.  With BibTeX
+entries, follow mode can be rather slow.
+
+@tablesubheading{Selecting entries and creating the citation}
+@item @key{RET}
+Insert a citation referencing the article at point into the buffer from
+which the selection process was started.
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a citation will accept it like @key{RET}
+would.  See also variable @code{reftex-highlight-selection}, @ref{Options
+(Misc)}.
+
+@item m
+Mark the current entry.  When one or several entries are marked,
+pressing @kbd{a} or @kbd{A} accepts all marked entries.  Also,
+@key{RET} behaves like the @kbd{a} key.
+
+@item u
+Unmark a marked entry.
+
+@item a
+Accept all (marked) entries in the selection buffer and create a single
+@code{\cite} macro referring to them.
+
+@item A
+Accept all (marked) entries in the selection buffer and create a
+separate @code{\cite} macro for each of it.
+
+@item e
+Create a new BibTeX database file which contains all @i{marked} entries
+in the selection buffer.  If no entries are marked, all entries are
+selected. 
+
+@item E
+Create a new BibTeX database file which contains all @i{unmarked}
+entries in the selection buffer.  If no entries are marked, all entries
+are selected. 
+
+@item @key{TAB}
+Enter a citation key with completion.  This may also be a key which does
+not yet exist.
+
+@item .
+Show insertion point in another window.  This is the point from where you
+called @code{reftex-citation}.
+
+@tablesubheading{Exiting}
+@item q
+Exit the selection process without inserting a citation into the
+buffer.
+
+@tablesubheading{Updating the buffer}
+
+@item g
+Start over with a new regular expression.  The full database will be
+rescanned with the new expression (see also @kbd{r}).
+
+@c FIXME: Should we use something else here? r is usually rescan!
+@item r
+Refine the current selection with another regular expression.  This will
+@emph{not} rescan the entire database, but just the already selected
+entries.
+
+@end table
+
+@vindex reftex-select-bib-map
+In order to define additional commands for this selection process, the
+keymap @code{reftex-select-bib-map} may be used.
+
+@node Citation Styles, Citation Info, Creating Citations, Citations
+@section Citation Styles
+@cindex Citation styles
+@cindex Citation styles, @code{natbib}
+@cindex Citation styles, @code{harvard}
+@cindex Citation styles, @code{chicago}
+@cindex Citation styles, @code{jurabib}
+@cindex @code{natbib}, citation style
+@cindex @code{harvard}, citation style
+@cindex @code{chicago}, citation style
+@cindex @code{jurabib}, citation style
+
+@vindex reftex-cite-format
+The standard LaTeX macro @code{\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 @code{\cite} macro.
+@b{Ref@TeX{}} can be configured to produce these citation macros as well
+by setting the variable @code{reftex-cite-format}.  For the most
+commonly used packages (@code{natbib}, @code{harvard}, @code{chicago},
+@code{jurabib}) this may be done from the menu, under
+@code{Ref->Citation Styles}.  Since there are usually several macros to
+create the citations, executing @code{reftex-citation} (@kbd{C-c [})
+starts by prompting for the correct macro.  For the Natbib style, this
+looks like this:
+
+@example
+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@}
+@end example
+
+@vindex reftex-cite-prompt-optional-args
+If cite formats contain empty paris of square brackets, RefTeX can
+will prompt for values of these optional arguments if you call the
+@code{reftex-citation} command with a @kbd{C-u} prefix.
+Following the most generic of these packages, @code{natbib}, the builtin
+citation packages always accept the @kbd{t} key for a @emph{textual}
+citation (like: @code{Jones et al. (1997) have shown...})  as well as
+the @kbd{p} key for a parenthetical citation (like: @code{As shown
+earlier (Jones et al, 1997)}).
+
+To make one of these styles the default, customize the variable
+@code{reftex-cite-format} or put into @file{.emacs}:
+
+@lisp
+(setq reftex-cite-format 'natbib)
+@end lisp
+
+You can also use AUCTeX style files to automatically set the
+citation style based on the @code{usepackage} commands in a given
+document.  @xref{Style Files}, for information on how to set up the style
+files correctly.
+
+@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
+@section Citation Info
+@cindex Displaying citations
+@cindex Citations, displaying
+@cindex Citation info
+@cindex Viewing citations
+@kindex C-c &
+@kindex S-mouse-2
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+
+When point is idle for more than @code{reftex-idle-time} seconds on the
+argument of a @code{\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.
+
+@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
+entry corresponding to a @code{\cite} macro, or all citation locations
+corresponding to a @code{\bibitem} or BibTeX database entry.
+@xref{Viewing Cross-References}.
+
+@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
+@section Chapterbib and Bibunits
+@cindex @code{chapterbib}, LaTeX package
+@cindex @code{bibunits}, LaTeX package
+@cindex Bibliographies, multiple
+
+@code{chapterbib} and @code{bibunits} are two LaTeX packages which
+produce multiple bibliographies in a document.  This is no problem for
+@b{Ref@TeX{}} 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 @code{chapterbib} anyway).  Then
+@b{Ref@TeX{}} will still scan the locally relevant databases correctly.  If
+you have multiple bibliographies within a @emph{single file}, this may
+or may not be the case.
+
+@node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations
+@section Citations outside LaTeX
+@cindex Citations outside LaTeX
+@vindex reftex-default-bibliography
+
+The command @code{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 @emph{not} enter @code{reftex-mode} for
+this, just execute the command.  The list of BibTeX files will in this
+case be taken from the variable @code{reftex-default-bibliography}.
+Setting the variable @code{reftex-cite-format} to the symbol
+@code{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 @kbd{C-c [} binding to the mail buffer.  It also provides a local
+binding for @code{reftex-cite-format}.
+
+@lisp
+(add-hook 'mail-setup-hook
+          (lambda () (define-key mail-mode-map "\C-c["
+                       (lambda ()
+                         (interactive)
+                         (let ((reftex-cite-format 'locally))
+                           (reftex-citation))))))
+@end lisp
+
+@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations
+@section Database Subsets
+@cindex BibTeX database subsets
+@findex reftex-create-bibtex-file
+
+@b{Ref@TeX{}} offers two ways to create a new BibTeX database file.
+
+The first option produces a file which contains only the entries
+actually referenced in the current document.  This can be useful if
+the database in only meant for a single document and you want to clean
+it of old and unused ballast.  It can also be useful while writing a
+document together with collaborators, in order to avoid sending around
+the entire (possibly very large) database.  To create the file, use
+@kbd{M-x reftex-create-bibtex-file}, also available from the menu
+under @code{Ref->Global Actions->Create Bibtex File}.  The command will
+prompt for a BibTeX file name and write the extracted entries to that
+file.
+
+The second option makes use of the selection process started by the
+command @kbd{C-c [} (@pxref{Creating Citations}).  This command uses a
+regular expression to select entries, and lists them in a formatted
+selection buffer.  After pressing the @kbd{e} key (mnemonics: Export),
+the command will prompt for the name of a new BibTeX file and write
+the selected entries to that file.  You can also first mark some
+entries in the selection buffer with the @kbd{m} key and then export
+either the @i{marked} entries (with the @kbd{e} key) or the
+@i{unmarked} entries (with the @kbd{E} key).
+
+@node Index Support, Viewing Cross-References, Citations, Top
+@chapter Index Support
+@cindex Index Support
+@cindex @code{\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 (@file{multind.sty} or
+@file{index.sty}), any number of indices can be supported.
+
+Index entries are created with the @code{\index@{@var{entry}@}} macro.
+All entries defined in a document are written out to the @file{.aux}
+file.  A separate tool must be used to convert this information into a
+nicely formatted index.  Tools used with LaTeX include @code{MakeIndex}
+and @code{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.
+
+@enumerate
+@item
+Part of the indexing should already be done with the markup.  The
+document structure should be reflected in the index, so when starting
+new sections, the basic topics of the section should be indexed.  If the
+document contains definitions, theorems or the like, these should all
+correspond to appropriate index entries.  This part of the index can
+very well be developed along with the document.  Often it is worthwhile
+to define special purpose macros which define an item and at the same
+time make an index entry, possibly with special formatting to make the
+reference page in the index bold or underlined.  To make @b{Ref@TeX{}}
+support for indexing possible, these special macros must be added to
+@b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}).
+
+@item
+The rest of the index is often just a collection of where in the
+document certain words or phrases are being used.  This part is
+difficult to develop along with the document, because consistent entries
+for each occurrence are needed and are best selected when the document
+is ready.  @b{Ref@TeX{}} supports this with an @emph{index phrases file}
+which collects phrases and helps indexing the phrases globally.
+@end enumerate
+
+Before you start, you need to make sure that @b{Ref@TeX{}} knows about
+the index style being used in the current document.  @b{Ref@TeX{}} has
+builtin support for the default @code{\index} and @code{\glossary}
+macros.  Other LaTeX packages, like the @file{multind} or @file{index}
+package, redefine the @code{\index} macro to have an additional
+argument, and @b{Ref@TeX{}} 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 (@code{Ref->Index
+Style}), or globally for all your documents with
+
+@lisp
+(setq reftex-index-macros '(multind))     @r{or}
+(setq reftex-index-macros '(index))
+@end lisp
+
+@menu
+* Creating Index Entries::           Macros and completion of entries.
+* The Index Phrases File::           A special file for global indexing.
+* Displaying and Editing the Index:: The index editor.
+* Builtin Index Macros::             The index macros RefTeX knows about.
+* Defining Index Macros::                ... and macros it  doesn't.
+@end menu
+
+@node Creating Index Entries, The Index Phrases File, , Index Support
+@section Creating Index Entries
+@cindex Creating index entries
+@cindex Index entries, creating
+@kindex C-c <
+@findex reftex-index
+@kindex C-c /
+@findex reftex-index-selection-or-word
+
+In order to index the current selection or the word at the cursor press
+@kbd{C-c /} (@code{reftex-index-selection-or-word}).  This causes the
+selection or word @samp{@var{word}} to be replaced with
+@samp{\index@{@var{word}@}@var{word}}.  The macro which is used
+(@code{\index} by default) can be configured with the variable
+@code{reftex-index-default-macro}.  When the command is called with a
+prefix argument (@kbd{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
+@samp{main!sub!@var{word}}.  When called with two raw @kbd{C-u} prefixes
+(@kbd{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 @code{reftex-index}, described below.
+
+In order to create a general index entry, press @kbd{C-c <}
+(@code{reftex-index}).  @b{Ref@TeX{}} 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
+@file{multind} and @file{index} packages, this tag is the first argument
+to the redefined @code{\index} macro.
+
+@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
+@section The Index Phrases File
+@cindex Index phrase file
+@cindex Phrase file
+@kindex C-c |
+@findex reftex-index-visit-phrases-buffer
+@cindex Macro definition lines, in phrase buffer
+
+@b{Ref@TeX{}} 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 @file{.rip} (@b{R}eftex
+@b{I}ndex @b{P}hrases).  You can create or visit the file with @kbd{C-c
+|} (@code{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
+@code{reftex-index-macros} (@pxref{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 @code{reftex-index-macros} as well.  Here is
+a phrase file header example:
+
+@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
+%----------------------------------------------------------
+@end example
+
+The macro definition lines consist of a unique letter identifying a
+macro, a format string and the @var{repeat} flag, all separated by
+@key{TAB}.  The format string shows how the macro is to be applied, the
+@samp{%s} will be replaced with the index entry.  The repeat flag
+indicates if @var{word} is indexed by the macro as
+@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
+@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}).  In the
+above example it is assumed that the macro @code{\index*@{@var{word}@}}
+already typesets its argument in the text, so that it is unnecessary to
+repeat @var{word} outside the macro.
+
+@menu
+* Collecting Phrases::               Collecting from document or external.
+* Consistency Checks::               Check for duplicates etc.
+* Global Indexing::                  The interactive indexing process.
+@end menu
+
+@node Collecting Phrases, Consistency Checks, , The Index Phrases File
+@subsection Collecting Phrases
+@cindex Collecting index phrases
+@cindex Index phrases, collection
+@cindex Phrases, collecting
+
+Phrases for indexing can be collected while writing the document.  The
+command @kbd{C-c \} (@code{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 @kbd{C-c C-c}
+(@code{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.
+@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
+format.  A phrase line looks like this:
+
+@example
+[@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
+@end example
+
+@code{<TABs>} stands for white space containing at least one @key{TAB}.
+@var{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 @var{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 @key{TAB} and the index
+argument @var{arg}.  If you want to have each match produce several
+index entries, separate the different index arguments with @samp{ &&
+}@footnote{@samp{&&} with optional spaces, see
+@code{reftex-index-phrases-logical-and-regexp}.}.  If you want to be
+able to choose at each match between several different index arguments,
+separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
+see @code{reftex-index-phrases-logical-or-regexp}.}.  Here is an
+example:
+
+@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
+@end example
+
+
+So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
+@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
+@samp{Vega} will be indexed as a subitem of @samp{Stars}.  The
+@samp{Jupiter} line will also use the @samp{i} macro as it was the first
+macro definition in the file header (see above example).  At each
+occurrence of @samp{Mars} you will be able choose between indexing it as
+a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
+Finally, every occurrence of @samp{Pluto} will be indexed as
+@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
+and will therefore create two different index entries.
+
+@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
+@subsection Consistency Checks
+@cindex Index phrases, consistency checks
+@cindex Phrases, consistency checks
+@cindex Consistency check for index phrases
+
+@kindex C-c C-s
+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 @kbd{C-c C-s}
+(@code{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 @code{reftex-index-phrases-sort-in-blocks}).
+
+@kindex C-c C-i
+A useful command is @kbd{C-c C-i} (@code{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.
+
+@kindex C-c C-t
+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 @samp{Mars} and then @samp{Planet Mars}, the
+second phrase will not match because of the index macro inserted before
+@samp{Mars} earlier.  The command @kbd{C-c C-t}
+(@code{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.
+
+@node Global Indexing, , Consistency Checks, The Index Phrases File
+@subsection Global Indexing
+@cindex Global indexing
+@cindex Indexing, global
+@cindex Indexing, from @file{phrases} buffer
+
+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: @kbd{C-c C-x} acts on
+the current phrase line, @kbd{C-c C-r} on all lines in the current
+region and @kbd{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.
+
+@b{Ref@TeX{}} 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@footnote{Windows
+users: Restrict yourself to the described keys during indexing.  Pressing
+@key{Help} at the indexing prompt can apparently hang Emacs.}:
+
+@table @kbd
+@item y
+Replace this match with the proposed string.
+@item n
+Skip this match.
+@item !
+Replace this and all further matches in this file.
+@item q
+Skip this match, start with next file.
+@item Q
+Skip this match, start with next phrase.
+@item o
+Select a different indexing macro for this match.
+@item 1-9
+Select one of multiple index keys (those separated with @samp{||}).
+@item e
+Edit the replacement text.
+@item C-r
+Recursive edit.  Use @kbd{C-M-c} to return to the indexing process.
+@item s
+Save this buffer and ask again about the current match.
+@item S
+Save all document buffers and ask again about the current match.
+@item C-g
+Abort the indexing process.
+@end table
+
+The @samp{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 (@pxref{Options
+(Index Support)}).  Here is a short explanation of what the options do:
+
+@table @i
+@item Match Whole Words
+When searching for index phrases, make sure whole words are matched.
+This should probably always be on.
+@item Case Sensitive Search
+Search case sensitively for phrases.  I recommend to have this setting
+off, in order to match the capitalized words at the beginning of a
+sentence, and even typos.  You can always say @emph{no} at a match you
+do not like.
+@item Wrap Long Lines
+Inserting index macros increases the line length.  Turn this option on
+to allow @b{Ref@TeX{}} to wrap long lines.
+@item Skip Indexed Matches
+When this is on, @b{Ref@TeX{}} will at each match try to figure out if
+this match is already indexed.  A match is considered indexed if it is
+either the argument of an index macro, or if an index macro is directly
+(without whitespace separation) before or after the match.  Index macros
+are those configured in @code{reftex-index-macros}.  Intended for
+re-indexing a documents after changes have been made.
+@end table
+
+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
+@code{reftex-index-phrases-apply-to-region} is designed for this
+purpose.  When called from a LaTeX document with active region, it will
+apply @code{reftex-index-all-phrases} to the current region.
+
+@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
+@section Displaying and Editing the Index
+@cindex Displaying the Index
+@cindex Editing the Index
+@cindex Index entries, creating
+@cindex Index, displaying
+@cindex Index, editing
+@kindex C-c >
+@findex reftex-display-index
+
+In order to compile and display the index, press @kbd{C-c >}.  If the
+document uses multiple indices, @b{Ref@TeX{}} will ask you to select
+one.  Then, all index entries will be sorted alphabetically and
+displayed in a special buffer, the @file{*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
+@samp{2}, thus press @kbd{C-u 2 C-c >}.  To restrict to the current
+region, make the region active and use a numeric prefix @samp{3} (press
+@kbd{C-u 3 C-c >}).  From within the @file{*Index*} buffer the
+restriction can be moved from one section to the next by pressing the
+@kbd{<} and @kbd{>} keys.
+
+One caveat: @b{Ref@TeX{}} 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
+@file{*Index*} buffer and the definition locations.  It is therefore
+advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
+frequently while editing the index from the @file{*Index*}
+buffer.
+
+@kindex ?
+Here is a list of special commands available in the @file{*Index*} buffer.  A
+summary of this information is always available by pressing
+@kbd{?}.
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Display a summary of commands.
+
+@item 0-9, -
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item ! A..Z
+Pressing any capital letter will jump to the corresponding section in
+the @file{*Index*} buffer.  The exclamation mark is special and jumps to
+the first entries alphabetically sorted below @samp{A}.  These are
+usually non-alphanumeric characters.
+@item n
+Go to next entry.
+@item p
+Go to previous entry.
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the place in the document where this index entry is defined.
+
+@item @key{TAB}
+Go to the definition of the current index entry in another
+window.
+
+@item @key{RET}
+Go to the definition of the current index entry and hide the
+@file{*Index*} buffer window.
+
+@item f
+@vindex reftex-index-follow-mode
+@vindex reftex-revisit-to-follow
+Toggle follow mode.  When follow mode is active, the other window will
+always show the location corresponding to the line in the @file{*Index*}
+buffer at point.  This is similar to pressing @key{SPC} after each
+cursor motion.  The default for this flag can be set with the variable
+@code{reftex-index-follow-mode}.  Note that only context in files
+already visited is shown.  @b{Ref@TeX{}} will not visit a file just for
+follow mode.  See, however, the variable
+@code{reftex-revisit-to-follow}.
+
+@tablesubheading{Entry editing}
+@item e
+Edit the current index entry.  In the minibuffer, you can edit the
+index macro which defines this entry.
+
+@item C-k
+Kill the index entry.  Currently not implemented because I don't know
+how to implement an @code{undo} function for this.
+
+@item *
+Edit the @var{key} part of the entry.  This is the initial part of the
+entry which determines the location of the entry in the index.
+
+@item |
+Edit the @var{attribute} part of the entry.  This is the part after the
+vertical bar.  With @code{MakeIndex}, this part is an encapsulating
+macro.  With @code{xindy}, it is called @emph{attribute} and is a
+property of the index entry that can lead to special formatting.  When
+called with @kbd{C-u} prefix, kill the entire @var{attribute}
+part.
+
+@item @@
+Edit the @var{visual} part of the entry.  This is the part after the
+@samp{@@} which is used by @code{MakeIndex} to change the visual
+appearance of the entry in the index.  When called with @kbd{C-u}
+prefix, kill the entire @var{visual} part.
+
+@item (
+Toggle the beginning of page range property @samp{|(} of the
+entry.
+
+@item )
+Toggle the end of page range property @samp{|)} of the entry.
+
+@item _
+Make the current entry a subentry.  This command will prompt for the
+superordinate entry and insert it.
+
+@item ^
+Remove the highest superordinate entry.  If the current entry is a
+subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
+(@samp{bbb!ccc}).
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*Index*} buffer.
+
+@item k
+Kill the @file{*Index*} buffer.
+
+@item C-c =
+Switch to the Table of Contents buffer of this document.
+
+@tablesubheading{Controlling what gets displayed}
+@item c
+@vindex reftex-index-include-context
+Toggle the display of short context in the @file{*Index*} buffer.  The
+default for this flag can be set with the variable
+@code{reftex-index-include-context}.
+
+@item @}
+Restrict the index to a single document section.  The corresponding
+section number will be displayed in the @code{R<>} indicator in the
+mode line and in the header of the @file{*Index*} buffer.
+
+@item @{
+Widen the index to contain all entries of the document.
+
+@item <
+When the index is currently restricted, move the restriction to the
+previous section.
+
+@item >
+When the index is currently restricted, move the restriction to the
+next section.
+
+@tablesubheading{Updating the buffer}
+@item g
+Rebuild the @file{*Index*} buffer.  This does @emph{not} rescan the
+document.  However, it sorts the entries again, so that edited entries
+will move to the correct position.
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the LaTeX document and rebuild the @file{*Index*} buffer.  When
+@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
+location is defined in, not the entire document.
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
+buffer.
+
+@item s
+Switch to a different index (for documents with multiple
+indices).
+@end table
+
+
+@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
+@section Builtin Index Macros
+@cindex Builtin index macros
+@cindex Index macros, builtin
+@vindex reftex-index-macros
+@cindex @code{multind}, LaTeX package
+@cindex @code{index}, LaTeX package
+@cindex LaTeX packages, @code{multind}
+@cindex LaTeX packages, @code{index}
+
+@b{Ref@TeX{}} by default recognizes the @code{\index} and
+@code{\glossary} macros which are defined in the LaTeX core.  It has
+also builtin support for the re-implementations of @code{\index}
+in the @file{multind} and @file{index} packages.  However, since
+the different definitions of the @code{\index} macro are incompatible,
+you will have to explicitly specify the index style used.
+@xref{Creating Index Entries}, for information on how to do that.
+
+@node Defining Index Macros, , Builtin Index Macros, Index Support
+@section Defining Index Macros
+@cindex  Defining Index Macros
+@cindex Index macros, defining
+@vindex reftex-index-macros
+
+When writing a document with an index you will probably define
+additional macros which make entries into the index.
+Let's look at an example.
+
+@example
+\newcommand@{\ix@}[1]@{#1\index@{#1@}@}
+\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
+\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
+@end example
+
+The first macro @code{\ix} typesets its argument in the text and places
+it into the index.  The second macro @code{\nindex} typesets its
+argument in the text and places it into a separate index with the tag
+@samp{name}@footnote{We are using the syntax of the @file{index} package
+here.}.  The last macro also places its argument into the index, but as
+subitems under the main index entry @samp{Astronomical Objects}.  Here
+is how to make @b{Ref@TeX{}} recognize and correctly interpret these
+macros, first with Emacs Lisp.
+
+@lisp
+(setq reftex-index-macros
+      '(("\\ix@{*@}" "idx" ?x "" nil nil)
+        ("\\nindex@{*@}" "name" ?n "" nil nil)
+        ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
+@end lisp
+
+Note that the index tag is @samp{idx} for the main index, and
+@samp{name} for the name index.  @samp{idx} and @samp{glo} are reserved
+for the default index and for the glossary.
+
+The character arguments @code{?x}, @code{?n}, and @code{?o} are for
+quick identification of these macros when @b{Ref@TeX{}} inserts new
+index entries with @code{reftex-index}.  These codes need to be
+unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
+@code{\index}, @code{\index*}, and @code{\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 @code{\astobj} macro.
+
+The next entry can be a hook function to exclude certain matches, it
+almost always can be @code{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 @code{t}.  Only if the macro typesets the entry in the text
+(like @code{\ix} and @code{\nindex} in the example do), this should be
+@code{nil}.
+
+To do the same thing with customize, you need to fill in the templates
+like this:
+
+@example
+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]
+@end example
+
+With the macro @code{\ix} defined, you may want to change the default
+macro used for indexing a text phrase (@pxref{Creating Index Entries}).
+This would be done like this
+
+@lisp
+(setq reftex-index-default-macro '(?x "idx"))
+@end lisp
+
+which specifies that the macro identified with the character @code{?x} (the
+@code{\ix} macro) should be used for indexing phrases and words already
+in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
+The index tag is "idx".
+
+@node Viewing Cross-References, RefTeXs Menu, Index Support, Top
+@chapter Viewing Cross--References
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+@kindex C-c &
+@kindex S-mouse-2
+
+@b{Ref@TeX{}} can display cross--referencing information.  This means,
+if two document locations are linked, @b{Ref@TeX{}} can display the
+matching location(s) in another window.  The @code{\label} and @code{\ref}
+macros are one way of establishing such a link.  Also, a @code{\cite}
+macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
+database entry.
+
+The feature is invoked by pressing @kbd{C-c &}
+(@code{reftex-view-crossref}) while point is on the @var{key} argument
+of a macro involved in cross--referencing.  You can also click with
+@kbd{S-mouse-2} on the macro argument.  Here is what will happen for
+individual classes of macros:
+
+@table @asis
+
+@item @code{\ref}
+@cindex @code{\ref}
+Display the corresponding label definition.  All usual
+variants@footnote{all macros that start with @samp{ref} or end with
+@samp{ref} or @samp{refrange}} of the @code{\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
+@code{xr} interface (@pxref{xr (LaTeX package)}).
+
+@item @code{\label}
+@cindex @code{\label}
+@vindex reftex-label-alist
+Display a document location which references this label.  Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations.  Not only the @code{\label} macro but also other macros
+with label arguments (as configured with @code{reftex-label-alist}) are
+active for cross--reference display.
+
+@item @code{\cite}
+@cindex @code{\cite}
+Display the corresponding BibTeX database entry or @code{\bibitem}.
+All usual variants@footnote{all macros that either start or end with
+@samp{cite}} of the @code{\cite} macro are active for cross--reference
+display.
+
+@item @code{\bibitem}
+@cindex @code{\bibitem}
+Display a document location which cites this article. Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations.
+
+@item BibTeX
+@cindex BibTeX buffer, viewing cite locations from
+@cindex Viewing cite locations from BibTeX buffer
+@kbd{C-c &} is also active in BibTeX buffers.  All locations in a
+document where the database entry at point is cited will be displayed.
+On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
+the document you want to search.  Subsequent calls will use the same
+document, until you break this link with a prefix argument to @kbd{C-c
+&}.
+
+@item @code{\index}
+@cindex @code{\index}
+Display other locations in the document which are marked by an index
+macro with the same key argument.  Along with the standard @code{\index}
+and @code{\glossary} macros, all macros configured in
+@code{reftex-index-macros} will be recognized.
+@end table
+
+@vindex reftex-view-crossref-extra
+While the display of cross referencing information for the above
+mentioned macros is hard--coded, you can configure additional relations
+in the variable @code{reftex-view-crossref-extra}.
+
+@iftex
+@chapter All the Rest
+@end iftex
+
+@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
+@section @b{Ref@TeX{}}'s Menu
+@cindex RefTeXs Menu
+@cindex Menu, in the menu bar
+
+@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
+which support this.  From this menu you can access all of
+@b{Ref@TeX{}}'s commands and a few of its options.  There is also a
+@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
+entire set of options.
+
+@node Key Bindings, Faces, RefTeXs Menu, Top
+@section Default Key Bindings
+@cindex Key Bindings, summary
+
+Here is a summary of the available key bindings.
+
+@kindex C-c =
+@kindex C-c -
+@kindex C-c (
+@kindex C-c )
+@kindex C-c [
+@kindex C-c &
+@kindex S-mouse-2
+@kindex C-c /
+@kindex C-c \
+@kindex C-c |
+@kindex C-c <
+@kindex C-c >
+@example
+@kbd{C-c =}      @code{reftex-toc}
+@kbd{C-c -}      @code{reftex-toc-recenter}
+@kbd{C-c (}      @code{reftex-label}
+@kbd{C-c )}      @code{reftex-reference}
+@kbd{C-c [}      @code{reftex-citation}
+@kbd{C-c &}      @code{reftex-view-crossref}
+@kbd{S-mouse-2}  @code{reftex-mouse-view-crossref}
+@kbd{C-c /}      @code{reftex-index-selection-or-word}
+@kbd{C-c \}      @code{reftex-index-phrase-selection-or-word}
+@kbd{C-c |}      @code{reftex-index-visit-phrases-buffer}
+@kbd{C-c <}      @code{reftex-index}
+@kbd{C-c >}      @code{reftex-display-index}
+@end example
+
+Note that the @kbd{S-mouse-2} binding is only provided if this key is
+not already used by some other package.  @b{Ref@TeX{}} will not override an
+existing binding to @kbd{S-mouse-2}.
+
+Personally, I also bind some functions in the users @kbd{C-c} map for
+easier access.
+
+@c FIXME: Do we need bindings for the Index macros here as well?
+@c C-c i   C-c I or so????
+@c How about key bindings for reftex-reset-mode and reftex-parse-document?
+@kindex C-c t
+@kindex C-c l
+@kindex C-c r
+@kindex C-c c
+@kindex C-c v
+@kindex C-c s
+@kindex C-c g
+@example
+@kbd{C-c t}    @code{reftex-toc}
+@kbd{C-c l}    @code{reftex-label}
+@kbd{C-c r}    @code{reftex-reference}
+@kbd{C-c c}    @code{reftex-citation}
+@kbd{C-c v}    @code{reftex-view-crossref}
+@kbd{C-c s}    @code{reftex-search-document}
+@kbd{C-c g}    @code{reftex-grep-document}
+@end example
+
+@noindent 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
+@file{.emacs} file:
+
+@vindex reftex-extra-bindings
+@lisp
+(setq reftex-extra-bindings t)
+@end lisp
+
+@vindex reftex-load-hook
+Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook
+@code{reftex-load-hook}.  For information on the keymaps
+which should be used to add keys, see @ref{Keymaps and Hooks}.
+
+@node Faces, AUCTeX, Key Bindings, Top
+@section Faces
+@cindex Faces
+
+@b{Ref@TeX{}} 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 @file{font-lock.el}.  Therefore, @b{Ref@TeX{}} will
+use faces only when @code{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 @ref{Options (Fontification)}.
+
+@node Multifile Documents, Language Support, AUCTeX, Top
+@section Multifile Documents
+@cindex Multifile documents
+@cindex Documents, spread over files
+
+The following is relevant when working with documents spread over many
+files:
+
+@itemize @bullet
+@item
+@b{Ref@TeX{}} has full support for multifile documents.  You can edit parts of
+several (multifile) documents at the same time without conflicts.
+@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
+@code{query-replace} on all files which are part of a multifile
+document.
+
+@item
+@vindex tex-main-file
+@vindex TeX-master
+All files belonging to a multifile document should define a File
+Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
+standard Emacs LaTeX mode) containing the name of the master file.  For
+example, to set the file variable @code{TeX-master}, include something
+like the following at the end of each TeX file:
+
+@example
+%%% Local Variables: ***
+%%% mode:latex ***
+%%% TeX-master: "thesis.tex"  ***
+%%% End: ***
+@end example
+
+AUCTeX with the setting
+
+@lisp
+(setq-default TeX-master nil)
+@end lisp
+
+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 (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
+documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
+The GNU Emacs Manual}) and the Emacs documentation on File Variables
+(@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
+
+@item
+The context of a label definition must be found in the same file as the
+label itself in order to be processed correctly by @b{Ref@TeX{}}.  The only
+exception is that section labels referring to a section statement
+outside the current file can still use that section title as
+context.
+@end itemize
+
+@node Language Support, Finding Files, Multifile Documents, Top
+@section Language Support
+@cindex Language support
+
+Some parts of @b{Ref@TeX{}} are language dependent.  The default
+settings work well for English.  If you are writing in a different
+language, the following hints may be useful:
+
+@itemize @bullet
+@item
+@vindex reftex-derive-label-parameters
+@vindex reftex-abbrev-parameters
+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
+@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
+
+@item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-label-illegal-re
+Also, when a label is derived from context, @b{Ref@TeX{}} clears the
+context string from non-ASCII characters in order to make a valid label.
+If there should ever be a version of @TeX{} which allows extended
+characters @emph{in labels}, then we will have to look at the
+variables @code{reftex-translate-to-ascii-function} and
+@code{reftex-label-illegal-re}.
+
+@item
+When a label is referenced, @b{Ref@TeX{}} looks at the word before point
+to guess which label type is required.  These @emph{magic words} are
+different in every language.  For an example of how to add magic words,
+see @ref{Adding Magic Words}.
+
+@vindex reftex-multiref-punctuation
+@vindex reftex-cite-punctuation
+@item
+@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
+for the author list in citations.  Some of this may be language
+dependent.  See the variables @code{reftex-multiref-punctuation} and
+@code{reftex-cite-punctuation}.
+@end itemize
+
+@node Finding Files, Optimizations, Language Support, Top
+@section Finding Files
+@cindex Finding files
+
+In order to find files included in a document via @code{\input} or
+@code{\include}, @b{Ref@TeX{}} searches all directories specified in the
+environment variable @code{TEXINPUTS}.  Similarly, it will search the
+path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
+BibTeX database files.
+
+When searching, @b{Ref@TeX{}} will also expand recursive path
+definitions (directories ending in @samp{//} or @samp{!!}).  But it will
+only search and expand directories @emph{explicitly} given in these
+variables. This may cause problems under the following circumstances:
+
+@itemize @bullet
+@item
+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 @b{Ref@TeX{}} 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, @b{Ref@TeX{}} will fail to find them.
+@item
+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.
+@end itemize
+
+@noindent
+There are three ways to solve this problem:
+
+@itemize @bullet
+@item
+Specify all relevant directories explicitly in the environment
+variables.  If for some reason you don't want to mess with the default
+variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
+variables and configure @b{Ref@TeX{}} to use them instead:
+
+@lisp
+(setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
+(setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
+@end lisp
+
+@item
+Specify the full search path directly in @b{Ref@TeX{}}'s variables.
+
+@lisp
+(setq reftex-texpath-environment-variables
+      '("./inp:/home/cd/tex//:/usr/local/tex//"))
+(setq reftex-bibpath-environment-variables
+      '("/home/cd/tex/lit/"))
+@end lisp
+
+@item
+Some TeX systems provide stand--alone programs to do the file search just
+like TeX and BibTeX.  E.g. Thomas Esser's @code{teTeX} uses the
+@code{kpathsearch} library which provides the command @code{kpsewhich}
+to search for files.  @b{Ref@TeX{}} can be configured to use this
+program.  Note that the exact syntax of the @code{kpsewhich}
+command depends upon the version of that program.
+
+@lisp
+(setq reftex-use-external-file-finders t)
+(setq reftex-external-file-finders
+      '(("tex" . "kpsewhich -format=.tex %f")
+        ("bib" . "kpsewhich -format=.bib %f")))
+@end lisp
+@end itemize
+
+@cindex Noweb files
+@vindex reftex-file-extensions
+@vindex TeX-file-extensions
+Some people like to use RefTeX with noweb files, which usually have the
+extension @file{.nw}.  In order to deal with such files, the new
+extension must be added to the list of valid extensions in the variable
+@code{reftex-file-extensions}.  When working with AUCTeX as major mode,
+the new extension must also be known to AUCTeX via the variable
+@code{TeX-file-extension}.  For example:
+
+@lisp
+(setq reftex-file-extensions
+      '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
+(setq TeX-file-extensions
+      '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
+@end lisp
+
+@node Optimizations, Problems and Work-Arounds, Finding Files, Top
+@section Optimizations
+@cindex Optimizations
+
+@b{Note added 2002.  Computers have gotten a lot faster, so most of the
+optimizations discussed below will not be necessary on new machines.  I
+am leaving this stuff in the manual for people who want to write thick
+books, where some of it still might be useful.}
+
+Implementing the principle of least surprises, the default settings of
+@b{Ref@TeX{}} ensure a safe ride for beginners and casual users.  However,
+when using @b{Ref@TeX{}} for a large project and/or on a small computer,
+there are ways to improve speed or memory usage.
+
+@itemize @bullet
+@item
+@b{Removing Lookup Buffers}@*
+@cindex Removing lookup buffers
+@b{Ref@TeX{}} 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
+
+@vindex reftex-keep-temporary-buffers
+@lisp
+(setq reftex-keep-temporary-buffers nil)
+@end lisp
+
+@item
+@b{Partial Document Scans}@*
+@cindex Partial documents scans
+@cindex Document scanning, partial
+A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
+(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
+@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
+=}), and @code{reftex-view-crossref} (@kbd{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.  @b{Ref@TeX{}} can be configured
+to do partial scans instead of full ones.  @kbd{C-u} re-parsing then
+does apply only to the current buffer and files included from it.
+Likewise, the @kbd{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 @kbd{C-u C-u} as a
+prefix, or the capital @kbd{R} key in the menus.  To use this feature,
+try
+
+@vindex reftex-enable-partial-scans
+@lisp
+(setq reftex-enable-partial-scans t)
+@end lisp
+
+@item
+@b{Saving Parser Information}@*
+@cindex Saving parser information
+@cindex Parse information, saving to a file
+@vindex reftex-parse-file-extension
+Even with partial scans enabled, @b{Ref@TeX{}} 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 @file{MASTER.rel} is used
+for storing information about a document with master file
+@file{MASTER.tex}.  It is written automatically when you kill a buffer
+in @code{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 @file{.emacs}:
+
+@vindex reftex-save-parse-info
+@lisp
+(setq reftex-save-parse-info t)
+@end lisp
+
+@item
+@b{Identifying label types by prefix}@*
+@cindex Parse information, saving to a file
+@vindex reftex-trust-label-prefix
+@b{Ref@TeX{}} normally parses around each label to check in which
+environment this label is located, in order to assign a label type to
+the label.  If your document contains thousands of labels, document
+parsing will take considerable time.  If you have been using label prefixes
+like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the
+label type directly from the prefix, without additional parsing.  This
+will be faster and also allow labels to end up in the correct category
+if for some reason it is not possible to derive the correct type from
+context.  For example, to enable this feature for footnote and
+equation labels, use
+
+@lisp
+(setq reftex-trust-label-prefix '("fn:" "eq:"))
+@end lisp
+
+@item
+@b{Automatic Document Scans}@*
+@cindex Automatic document scans
+@cindex Document scanning, automatic
+At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
+document.  If this gets into your way, it can be turned off with
+
+@vindex reftex-allow-automatic-rescan
+@lisp
+(setq reftex-allow-automatic-rescan nil)
+@end lisp
+
+@b{Ref@TeX{}} 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.
+
+@item
+@b{Multiple Selection Buffers}@*
+@cindex Multiple selection buffers
+@cindex Selection buffers, multiple
+Normally, the selection buffer @file{*RefTeX Select*} is re-created for
+every selection process.  In documents with very many labels this can
+take several seconds.  @b{Ref@TeX{}} 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
+@code{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
+
+@vindex reftex-use-multiple-selection-buffers
+@lisp
+(setq reftex-use-multiple-selection-buffers t)
+@end lisp
+
+@noindent
+@cindex Selection buffers, updating
+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 @kbd{g} key.  To get this behavior, use instead
+
+@vindex reftex-auto-update-selection-buffers
+@lisp
+(setq reftex-use-multiple-selection-buffers t
+      reftex-auto-update-selection-buffers nil)
+@end lisp
+@end itemize
+
+@need 2000
+@noindent
+@b{As a summary}, here are the settings I recommend for heavy use of
+@b{Ref@TeX{}} with large documents:
+
+@lisp
+@group
+(setq reftex-enable-partial-scans t
+      reftex-save-parse-info t
+      reftex-use-multiple-selection-buffers t)
+@end group
+@end lisp
+
+@node AUCTeX, Multifile Documents, Faces, Top
+@section AUC@TeX{}
+@cindex @code{AUCTeX}, Emacs package
+@cindex Emacs packages, @code{AUCTeX}
+
+AUCTeX is without doubt the best major mode for editing TeX and LaTeX
+files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
+If AUCTeX is not part of your Emacs distribution, you can get
+it@footnote{XEmacs 21.x users may want to install the corresponding
+XEmacs package.} by ftp from the @value{AUCTEXSITE}.
+
+@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
+@end menu
+
+@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
+@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
+
+@b{Ref@TeX{}} contains code to interface with AUCTeX.  When this
+interface is turned on, both packages will interact closely.  Instead of
+using @b{Ref@TeX{}}'s commands directly, you can then also use them
+indirectly as part of the AUCTeX
+environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
+needed for all of this to work.  Parts of it work also with earlier
+versions.}.  The interface is turned on with
+
+@lisp
+(setq reftex-plug-into-AUCTeX t)
+@end lisp
+
+If you need finer control about which parts of the interface are used
+and which not, read the docstring of the variable
+@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
+customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
+
+The following list describes the individual parts of the interface.
+
+@itemize @bullet
+@item
+@findex reftex-label
+@vindex LaTeX-label-function, @r{AUCTeX}
+@kindex C-c C-e
+@kindex C-c C-s
+@findex LaTeX-section, @r{AUCTeX}
+@findex TeX-insert-macro, @r{AUCTeX}
+@b{AUCTeX calls @code{reftex-label} to insert labels}@*
+When a new section is created with @kbd{C-c C-s}, or a new environment
+is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
+go with it.  With the interface, @code{reftex-label} is called instead.
+For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
+@b{Ref@TeX{}} will insert
+
+@example
+\begin@{equation@}
+\label@{eq:1@}
+
+\end@{equation@}
+@end example
+
+@noindent
+without further prompts.
+
+Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
+will offer its default label which is derived from the section title.
+
+@item
+@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
+When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
+have to rescan the buffer in order to see it.
+
+@item
+@findex reftex-arg-label
+@findex TeX-arg-label, @r{AUCTeX function}
+@findex reftex-arg-ref
+@findex TeX-arg-ref, @r{AUCTeX function}
+@findex reftex-arg-cite
+@findex TeX-arg-cite, @r{AUCTeX function}
+@findex reftex-arg-index
+@findex TeX-arg-index, @r{AUCTeX function}
+@findex TeX-insert-macro, @r{AUCTeX function}
+@kindex C-c @key{RET}
+@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
+interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
+macro arguments.  Internally, it uses the functions
+@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
+prompt for arguments which are labels, citation keys and index entries.
+The interface takes over these functions@footnote{@code{fset} is used to
+do this, which is not reversible.  However, @b{Ref@TeX{}} implements the
+old functionality when you later decide to turn off the interface.} and
+supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms.  For
+example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
+will supply its label selection process (@pxref{Referencing
+Labels}).
+
+@item
+@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
+@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
+@end itemize
+
+@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
+@subsection Style Files
+@cindex Style files, AUCTeX
+@findex TeX-add-style-hook, @r{AUCTeX}
+Style files are Emacs Lisp files which are evaluated by AUCTeX in
+association with the @code{\documentclass} and @code{\usepackage}
+commands of a document (@pxref{Style Files,,,auctex}). Support for
+@b{Ref@TeX{}} 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. @file{amsmath.el} or @file{natbib.el})
+distributed with AUCTeX already support @b{Ref@TeX{}} in this
+way.
+
+Before calling a @b{Ref@TeX{}} 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 @b{Ref@TeX{}}. 
+
+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 @b{Ref@TeX{}} switch over to @code{\eqref}, but
+this will not affect other documents.
+
+@findex reftex-add-label-environments
+@findex reftex-add-to-label-alist
+A style hook may contain calls to
+@code{reftex-add-label-environments}@footnote{This used to be the
+function @code{reftex-add-to-label-alist} which is still available as an
+alias for compatibility.}  which defines additions to
+@code{reftex-label-alist}.  The argument taken by this function must have
+the same format as @code{reftex-label-alist}.  The @file{amsmath.el}
+style file of AUCTeX for example contains the following:
+
+@lisp
+@group
+(TeX-add-style-hook "amsmath"
+   (lambda ()
+     (if (fboundp 'reftex-add-label-environments)
+         (reftex-add-label-environments '(AMSTeX)))))
+@end group
+@end lisp
+
+@noindent
+@findex LaTeX-add-environments, @r{AUCTeX}
+while a package @code{myprop} defining a @code{proposition} environment
+with @code{\newtheorem} might use
+
+@lisp
+@group
+(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))))))
+@end group
+@end lisp
+
+@findex reftex-set-cite-format
+Similarly, a style hook may contain a call to
+@code{reftex-set-cite-format} to set the citation format.  The style
+file @file{natbib.el} for the Natbib citation style does switch
+@b{Ref@TeX{}}'s citation format like this:
+
+@lisp
+(TeX-add-style-hook "natbib"
+   (lambda ()
+     (if (fboundp 'reftex-set-cite-format)
+         (reftex-set-cite-format 'natbib))))
+@end lisp
+
+@findex reftex-add-index-macros
+The hook may contain a call to @code{reftex-add-index-macros} to
+define additional @code{\index}-like macros.  The argument must have
+the same format as @code{reftex-index-macros}.  It may be a symbol, to
+trigger support for one of the builtin index packages.  For example,
+the style @file{multind.el} contains
+
+@lisp
+(TeX-add-style-hook "multind"
+  (lambda ()
+    (and (fboundp 'reftex-add-index-macros)
+         (reftex-add-index-macros '(multind)))))
+@end lisp
+
+If you have your own package @file{myindex} which defines the
+following macros to be used with the LaTeX @file{index.sty} file
+@example
+\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
+\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
+@end example
+
+you could write this in the style file @file{myindex.el}:
+
+@lisp
+(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))))))
+@end lisp
+
+@findex reftex-add-section-levels
+Finally the hook may contain a call to @code{reftex-add-section-levels}
+to define additional section statements.  For example, the FoilTeX class
+has just two headers, @code{\foilhead} and @code{\rotatefoilhead}.  Here
+is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
+
+@lisp
+(TeX-add-style-hook "foils"
+   (lambda ()
+     (if (fboundp 'reftex-add-section-levels)
+         (reftex-add-section-levels '(("foilhead" . 3)
+                                      ("rotatefoilhead" . 3))))))
+@end lisp
+
+@node Bib-Cite, , Style Files, AUCTeX
+@subsection Bib-Cite
+@cindex @code{bib-cite}, Emacs package
+@cindex Emacs packages, @code{bib-cite}
+
+Once you have written a document with labels, references and citations,
+it can be nice to read it like a hypertext document.  @b{Ref@TeX{}} has
+support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
+&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
+@code{reftex-search-document}.  A somewhat fancier interface with mouse
+highlighting is provided (among other things) by Peter S. Galbraith's
+@file{bib-cite.el}.  There is some overlap in the functionalities of
+Bib-cite and @b{Ref@TeX{}}.  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 @b{Ref@TeX{}} for displaying references and citations.
+This can be useful in particular when working with the LaTeX @code{xr}
+package or with an explicit @code{thebibliography} environment (rather
+than BibTeX).  Bib-cite cannot handle those, but @b{Ref@TeX{}} does.  To
+make use of this feature, try
+
+@vindex bib-cite-use-reftex-view-crossref
+@lisp
+(setq bib-cite-use-reftex-view-crossref t)
+@end lisp
+
+@page
+@node Problems and Work-Arounds, Imprint, Optimizations, Top
+@section Problems and Work-arounds
+@cindex Problems and work-arounds
+
+@itemize @bullet
+@item
+@b{LaTeX commands}@*
+@cindex LaTeX commands, not found
+@code{\input}, @code{\include}, and @code{\section} (etc.) statements
+have to be first on a line (except for white space).
+
+@item
+@b{Commented regions}@*
+@cindex Labels, commented out
+@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
+make duplicates of such labels.  This is considered to be a feature.
+
+@item
+@b{Wrong section numbers}@*
+@cindex Section numbers, wrong
+@vindex reftex-enable-partial-scans
+When using partial scans (@code{reftex-enable-partial-scans}), the section
+numbers in the table of contents may eventually become wrong.  A full
+scan will fix this.
+
+@item
+@b{Local settings}@*
+@cindex Settings, local
+@findex reftex-add-label-environments
+@findex reftex-set-cite-format
+@findex reftex-add-section-levels
+The label environment definitions in @code{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
+@code{reftex-add-label-environments}, @code{reftex-set-cite-format},
+@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
+Settings made with these functions remain local to the current
+document. @xref{AUCTeX}.
+
+@item
+@b{Funny display in selection buffer}@*
+@cindex @code{x-symbol}, Emacs package
+@cindex Emacs packages, @code{x-symbol}
+@cindex @code{isotex}, Emacs package
+@cindex Emacs packages, @code{isotex}
+@cindex @code{iso-cvt}, Emacs package
+@cindex Emacs packages, @code{iso-cvt}
+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 @b{Ref@TeX{}}'s parsing information sometimes
+reflects the disk state of a file.  This happens only in @emph{unvisited}
+parts of a multifile document, because @b{Ref@TeX{}} 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 @code{reftex-toc} may have problems to jump to an affected
+section heading.  There are three possible ways to deal with
+this:
+@itemize @minus
+@item
+@vindex reftex-keep-temporary-buffers
+@code{(setq reftex-keep-temporary-buffers t)}@*
+This implies that @b{Ref@TeX{}} will load all parts of a multifile
+document into Emacs (i.e. there won't be any temporary buffers).
+@item
+@vindex reftex-initialize-temporary-buffers
+@code{(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.
+@item
+Set @code{reftex-initialize-temporary-buffers} to a list of hook
+functions doing a minimal initialization.
+@end itemize
+@vindex reftex-refontify-context
+See also the variable @code{reftex-refontify-context}.
+
+@item
+@b{Labels as arguments to \begin}@*
+@cindex @code{pf}, LaTeX package
+@cindex LaTeX packages, @code{pf}
+Some packages use an additional argument to a @code{\begin} macro
+to specify a label.  E.g. Lamport's @file{pf.sty} uses both
+@example
+\step@{@var{label}@}@{@var{claim}@}   and      \begin@{step+@}@{@var{label}@}
+                                  @var{claim}
+                               \end@{step+@}
+@end example
+
+@noindent
+We need to trick @b{Ref@TeX{}} into swallowing this:
+
+@lisp
+@group
+;; 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)))
+@end group
+@end lisp
+
+@noindent
+The first line is just a normal configuration for a macro.  For the
+@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
+@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
+argument (which really is a second argument to the macro @code{\begin})
+as a label of type @code{?p}.  Argument count for this macro starts only
+after the @samp{@{step+@}}, also when specifying how to get
+context.
+
+@item
+@b{Idle timers in XEmacs}@*
+@cindex Idle timer restart
+@vindex reftex-use-itimer-in-xemacs
+In XEmacs, idle timer restart does not work reliably after fast
+keystrokes.  Therefore @b{Ref@TeX{}} 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
+@lisp
+(setq reftex-use-itimer-in-xemacs t)
+@end lisp
+
+@item
+@b{Viper mode}@*
+@cindex Viper mode
+@cindex Key bindings, problems with Viper mode
+@findex viper-harness-minor-mode
+With @i{Viper} mode prior to Vipers version 3.01, you need to protect
+@b{Ref@TeX{}}'s keymaps with
+
+@lisp
+(viper-harness-minor-mode "reftex")
+@end lisp
+
+@end itemize
+
+@page
+@node Imprint, Commands, Problems and Work-Arounds, Top
+@section Imprint
+@cindex Imprint
+@cindex Maintainer
+@cindex Acknowledgments
+@cindex Thanks
+@cindex Bug reports
+@cindex @code{http}, @b{Ref@TeX{}} home page
+@cindex @code{ftp}, @b{Ref@TeX{}} site
+
+Ref@TeX{} was written by @i{Carsten Dominik}
+@email{dominik@@science.uva.nl}, with contributions by @i{Stephen
+Eglen}.  Ref@TeX{} is currently maintained by @value{MAINTAINER}, see
+the @value{MAINTAINERSITE} for detailed information.
+
+If you have questions about Ref@TeX{}, you can send email to the
+@value{SUPPORTADDRESS}.  If you want to contribute code or ideas, write
+to the @value{DEVELADDRESS}.  And in the rare case of finding a bug,
+please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a
+bug report with useful information about your setup.  Remember to add
+essential information like a recipe for reproducing the bug, what you
+expected to happen, and what actually happened.  Send the bug report to
+the @value{BUGADDRESS}.
+
+There are also several Usenet groups which have competent readers who
+might be able to help: @code{comp.emacs}, @code{gnu.emacs.help},
+@code{comp.emacs.xemacs}, and @code{comp.text.tex}.
+
+@b{Ref@TeX{}} 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 @value{XEMACSFTP}.  See the XEmacs 21.x
+documentation on package installation for details.
+
+Users of earlier Emacs distributions (including Emacs 19) can get a
+@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}.  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 @b{Ref@TeX{}} and helped
+developing it with their reports.  In particular thanks to @i{Ralf
+Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton,
+Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai
+Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan
+Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz,
+Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan
+Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha,
+Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan
+Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}.
+
+
+The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
+@file{bib-cite.el}.
+
+Finally thanks to @i{Uwe Bolick} who first got me interested in
+supporting LaTeX labels and references with an editor (which was
+MicroEmacs at the time).
+
+@node Commands, Options, Imprint, Top
+@chapter Commands
+@cindex Commands, list of
+
+Here is a summary of @b{Ref@TeX{}}'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 @code{Ref}
+menu.  See @xref{Key Bindings}.
+
+@deffn Command reftex-toc
+Show the table of contents for the current document.  When called with
+one ore two @kbd{C-u} prefixes, rescan the document first.
+@end deffn
+
+@deffn Command reftex-label
+Insert a unique label.  With one or two @kbd{C-u} prefixes, enforce
+document rescan first.
+@end deffn
+
+@deffn Command reftex-reference
+Start a selection process to select a label, and insert a reference to
+it.  With one or two @kbd{C-u} prefixes, enforce document rescan first.
+@end deffn
+
+@deffn 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
+@code{\bibliography} command or a @code{thebibliography} environment)
+and offers the matching entries for selection.  The selected entry is
+formatted according to @code{reftex-cite-format} and inserted into the
+buffer. @*
+When called with a @kbd{C-u} prefix, prompt for optional arguments in
+cite macros.  When called with a numeric prefix, make that many citations.
+When called with point inside the braces of a @code{\cite} command, it
+will add another key, ignoring the value of
+@code{reftex-cite-format}. @*
+The regular expression uses an expanded syntax: @samp{&&} is interpreted
+as @code{and}.  Thus, @samp{aaaa&&bbb} matches entries which contain
+both @samp{aaaa} and @samp{bbb}.  While entering the regexp, completion
+on knows citation keys is possible.  @samp{=} is a good regular
+expression to match all entries in all files.
+@end deffn
+
+@deffn Command reftex-index
+Query for an index macro and insert it along with its arguments.  The
+index macros available are those defined in @code{reftex-index-macro} or
+by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
+style file.  @b{Ref@TeX{}} provides completion for the index tag and the
+index key, and will prompt for other arguments.
+@end deffn
+
+@deffn Command reftex-index-selection-or-word
+Put current selection or the word near point into the default index
+macro.  This uses the information in @code{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 @kbd{C-u} prefix, let the
+user have a chance to edit the index entry.  When called with 2
+@kbd{C-u} as prefix, also ask for the index macro and other stuff.  When
+called inside TeX math mode as determined by the @file{texmathp.el}
+library which is part of AUCTeX, the string is first processed with the
+@code{reftex-index-math-format}, which see.
+@end deffn
+
+@deffn 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 @kbd{C-c C-c}.
+@end deffn
+
+@deffn Command reftex-index-visit-phrases-buffer
+Switch to the phrases buffer, initialize if empty.
+@end deffn
+
+@deffn 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.
+@end deffn
+
+@deffn 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 @kbd{C-u} prefixes, rescan document first.
+With prefix 2, restrict index to current document section.
+With prefix 3, restrict index to active region.
+@end deffn
+
+@deffn Command reftex-view-crossref
+View cross reference of macro at point.  Point must be on the @var{key}
+argument.  Works with the macros @code{\label}, @code{\ref},
+@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
+these.  Where it makes sense, subsequent calls show additional
+locations.  See also the variable @code{reftex-view-crossref-extra} and
+the command @code{reftex-view-crossref-from-bibtex}.  With one or two
+@kbd{C-u} prefixes, enforce rescanning of the document.  With argument
+2, select the window showing the cross reference.
+@end deffn
+
+@deffn 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 @b{Ref@TeX{}} mode.  To reset this
+link to a document, call the function with a prefix arg.  Calling
+this function several times find successive citation locations.
+@end deffn
+
+@deffn Command reftex-create-tags-file
+Create TAGS file by running @code{etags} on the current document.  The
+TAGS file is also immediately visited with
+@code{visit-tags-table}.
+@end deffn
+
+@deffn 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.
+@end deffn
+
+@deffn 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.
+@end deffn
+
+@deffn Command reftex-query-replace-document
+Run a query-replace-regexp of @var{from} with @var{to} over the entire
+document.  With prefix arg, replace only word-delimited matches.  No
+active TAGS table is required.
+@end deffn
+
+@deffn Command reftex-isearch-minor-mode
+Toggle a minor mode which enables incremental search to work globally
+on the entire multifile document.  Files will be searched in th
+sequence they appear in the document.
+@end deffn
+
+@deffn Command reftex-goto-label
+Prompt for a label (with completion) and jump to the location of this
+label.  Optional prefix argument @var{other-window} goes to the label in
+another window.
+@end deffn
+
+
+@deffn Command reftex-change-label
+Query replace @var{from} with @var{to} in all @code{\label} and
+@code{\ref} commands.  Works on the entire multifile document.  No
+active TAGS table is required.
+@end deffn
+
+@deffn 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, @b{Ref@TeX{}} looks at the
+arguments of any macros which either start or end with the string
+@samp{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 @code{xr} package.
+@end deffn
+
+@deffn Command reftex-find-duplicate-labels
+Produce a list of all duplicate labels in the document.
+@end deffn
+
+@deffn Command reftex-create-bibtex-file
+Create a new BibTeX database file with all entries referenced in document.
+The command prompts for a filename and writes the collected entries to
+that file.  Only entries referenced in the current document with
+any @code{\cite}-like macros are used. 
+The sequence in the new file is the same as it was in the old database.
+@end deffn
+
+@deffn Command reftex-customize
+Run the customize browser on the @b{Ref@TeX{}} group.
+@end deffn
+@deffn Command reftex-show-commentary
+Show the commentary section from @file{reftex.el}.
+@end deffn
+@deffn Command reftex-info
+Run info on the top @b{Ref@TeX{}} node.
+@end deffn
+@deffn Command reftex-parse-document
+Parse the entire document in order to update the parsing information.
+@end deffn
+@deffn Command reftex-reset-mode
+Enforce rebuilding of several internal lists and variables.  Also
+removes the parse file associated with the current document.
+@end deffn
+
+@node Options, Keymaps and Hooks, Commands, Top
+@chapter Options, Keymaps, Hooks
+@cindex Options, list of
+
+Here is a complete list of @b{Ref@TeX{}}'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
+@code{customize} to look at and change these variables. @kbd{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)::
+@end menu
+
+@node Options (Table of Contents), Options (Defining Label Environments), ,  Options
+@section Table of Contents
+@cindex Options, table of contents
+@cindex Table of contents, options
+
+@defopt reftex-include-file-commands
+List of LaTeX commands which input another file.
+The file name is expected after the command, either in braces or separated
+by whitespace.
+@end defopt
+
+@defopt reftex-max-section-depth
+Maximum depth of section levels in document structure.
+Standard LaTeX needs 7, default is 12.
+@end defopt
+
+@defopt reftex-section-levels
+Commands and levels used for defining sections in the document.  The
+@code{car} of each cons cell is the name of the section macro.  The
+@code{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 @code{cdr} may also be a function which then has to return the
+level.  This list is also used for promotion and demotion of sectioning
+commands.  If you are using a document class which has several sets of
+sectioning commands, promotion only works correctly if this list is
+sorted first by set, then within each set by level.  The promotion
+commands always select the nearest entry with the correct new level.
+
+@end defopt
+
+@defopt 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 @file{*toc*} buffer with the @kbd{t} key.
+@end defopt
+
+@defopt reftex-part-resets-chapter
+Non-@code{nil} means, @code{\part} is like any other sectioning command.
+This means, part numbers will be included in the numbering of chapters, and
+chapter counters will be reset for each part.
+When @code{nil} (the default), parts are special, do not reset the
+chapter counter and also do not show up in chapter numbers.
+@end defopt
+
+@defopt reftex-auto-recenter-toc
+Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
+When active, the @file{*TOC*} window will always show the section you
+are currently working in.  Recentering happens whenever Emacs is idle for
+more than @code{reftex-idle-time} seconds.
+
+Value @code{t} means, turn on immediately when RefTeX gets started.  Then,
+recentering will work for any toc window created during the session.
+
+Value @code{frame} (the default) means, turn automatic recentering on
+only while the dedicated TOC frame does exist, and do the recentering
+only in that frame.  So when creating that frame (with @kbd{d} key in an
+ordinary TOC window), the automatic recentering is turned on.  When the
+frame gets destroyed, automatic recentering is turned off again.
+
+This feature can be turned on and off from the menu 
+(Ref->Options).
+@end defopt
+
+@defopt reftex-toc-split-windows-horizontally
+Non-@code{nil} means, create TOC window by splitting window
+horizontally.  The default is to split vertically.
+@end defopt
+
+@defopt reftex-toc-split-windows-fraction
+Fraction of the width or height of the frame to be used for TOC window.
+@end defopt
+
+@defopt reftex-toc-keep-other-windows
+Non-@code{nil} means, split the selected window to display the
+@file{*toc*} buffer.  This helps to keep the window configuration, but
+makes the @file{*toc*} small.  When @code{nil}, all other windows except
+the selected one will be deleted, so that the @file{*toc*} window fills
+half the frame.
+@end defopt
+
+@defopt reftex-toc-include-file-boundaries
+Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{i} key.
+@end defopt
+
+@defopt reftex-toc-include-labels
+Non-@code{nil} means, include labels in @file{*toc*} buffer.  This flag
+can be toggled from within the @file{*toc*} buffer with the @kbd{l}
+key.
+@end defopt
+
+@defopt reftex-toc-include-index-entries
+Non-@code{nil} means, include index entries in @file{*toc*} buffer.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{i} key.
+@end defopt
+
+@defopt reftex-toc-include-context
+Non-@code{nil} means, include context with labels in the @file{*toc*}
+buffer.  Context will only be shown if the labels are visible as well.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{c} key.
+@end defopt
+
+@defopt reftex-toc-follow-mode
+Non-@code{nil} means, point in @file{*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 @file{*toc*} buffer with the @kbd{f}
+key.
+@end defopt
+
+@deffn {Normal Hook} reftex-toc-mode-hook
+Normal hook which is run when a @file{*toc*} buffer is
+created.
+@end deffn
+
+@deffn Keymap reftex-toc-map
+The keymap which is active in the @file{*toc*} buffer.
+(@pxref{Table of Contents}).
+@end deffn
+
+@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
+@section Defining Label Environments
+@cindex Options, defining label environments
+@cindex Defining label environments, options
+
+@defopt reftex-default-label-alist-entries
+Default label alist specifications.  It is a list of symbols with
+associations in the constant @code{reftex-label-alist-builtin}.
+@code{LaTeX} should always be the last entry.
+@end defopt
+
+@defopt reftex-label-alist
+Set this variable to define additions and changes to the defaults in
+@code{reftex-default-label-alist-entries}.  The only things you
+@emph{must not} change is that @code{?s} is the type indicator for
+section labels, and @key{SPC} for the @code{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:
+
+@example
+ (@var{env-or-macro}  @var{type-key}  @var{label-prefix}  @var{reference-format}
+    @var{context-method}  (@var{magic-word} ... )  @var{toc-level})
+@end example
+
+Each list entry describes either an environment carrying a counter for
+use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
+label as (or inside) one of its arguments.  The elements of each list
+entry are:
+
+@table @asis
+@item @var{env-or-macro}
+Name of the environment (like @samp{table}) or macro (like
+@samp{\myfig}).  For macros, indicate the arguments, as in
+@samp{\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
+@samp{\label@{...@}} inside one of its arguments.
+
+Special names: @code{section} for section labels, @code{any} to define a
+group which contains all labels.
+
+This may also be a function to do local parsing and identify point to be
+in a non-standard label environment.  The function must take an
+argument @var{bound} and limit backward searches to this value.  It
+should return either nil or a cons cell @code{(@var{function}
+. @var{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 @code{nil} if the entry is only meant to change
+some settings associated with the type indicator character (see
+below).
+
+@item @var{type-key}
+Type indicator character, like @code{?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 @code{equation} and @code{eqnarray}).  If the type
+indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
+the macro defines neutral labels just like @code{\label}.  In this case
+the reminder of this entry is ignored.
+
+@item @var{label-prefix}
+Label prefix string, like @samp{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 @samp{%} escapes:
+
+@example
+%f Current file name, directory and extension stripped.
+%F Current file name relative to master file directory.
+%m Master file name, directory and extension stripped.
+%M Directory name (without path) where master file is located.
+%u User login name, on systems which support this.
+%S A section prefix derived with variable @code{reftex-section-prefixes}.
+@end example
+
+@noindent
+Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
+@samp{eq:intro:}.
+
+@item @var{reference-format}
+Format string for reference insert in buffer.  @samp{%s} will be
+replaced by the label.  When the format starts with @samp{~}, this
+@samp{~} will only be inserted when the character before point is
+@emph{not} a whitespace.
+
+@item @var{context-method}
+Indication on how to find the short context.
+@itemize @minus
+@item
+If @code{nil}, use the text following the @samp{\label@{...@}} macro.
+@item
+If @code{t}, use
+@itemize @minus
+@item
+the section heading for section labels.
+@item
+text following the @samp{\begin@{...@}} statement of environments (not
+a good choice for environments like eqnarray or enumerate, where one has
+several labels in a single environment).
+@item
+text after the macro name (starting with the first arg) for
+macros.
+@end itemize
+@item
+If an integer, use the nth argument of the macro.  As a special case,
+1000 means to get text after the last macro argument.
+@item
+If a string, use as regexp to search @emph{backward} from the label.
+Context is then the text following the end of the match.  E.g. putting
+this to @samp{\\caption[[@{]} will use the caption in a figure or table
+environment.  @samp{\\begin@{eqnarray@}\|\\\\} works for
+eqnarrays.
+@item
+If any of @code{caption}, @code{item}, @code{eqnarray-like},
+@code{alignat-like}, this symbol will internally be translated into an
+appropriate regexp (see also the variable
+@code{reftex-default-context-regexps}).
+@item
+If a function, call this function with the name of the environment/macro
+as argument.  On call, point will be just after the @code{\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:
+
+@example
+(defun my-context-function (env-or-mac)
+   (if (> (point-max) (+ 10 (point)))
+       (buffer-substring (point) (+ 10 (point)))
+     (error "Buffer too small")))
+@end example
+@end itemize
+
+Label context is used in two ways by @b{Ref@TeX{}}: 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. @code{(nil . t)} uses the text after the label (@code{nil}) for
+display, and text from the default position (@code{t}) to derive a label
+string.  This is actually used for section labels.
+
+@item @var{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
+@code{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.
+
+@item @var{toc-level}
+The integer level at which this environment should be added to the table
+of contents.  See also @code{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 @code{nil}, no TOC entries will be
+made.
+@end table
+
+If the type indicator characters of two or more entries are the same,
+@b{Ref@TeX{}} will use
+@itemize @minus
+@item
+the first non-@code{nil} format and prefix
+@item
+the magic words of all involved entries.
+@end itemize
+
+Any list entry may also be a symbol.  If that has an association in
+@code{reftex-label-alist-builtin}, the @code{cddr} of that association is
+spliced into the list.  However, builtin defaults should normally be set
+with the variable @code{reftex-default-label-alist-entries}.
+@end defopt
+
+@defopt reftex-section-prefixes
+Prefixes for section labels.  When the label prefix given in an entry in
+@code{reftex-label-alist} contains @samp{%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
+@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
+names like @samp{chapter}, integer section levels (as given in
+@code{reftex-section-levels}), and @code{t} for the default.
+@end defopt
+
+@defopt reftex-default-context-regexps
+Alist with default regular expressions for finding context.  The emacs
+lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
+to calculate the final regular expression - so @samp{%s} will be
+replaced with the environment or macro.
+@end defopt
+
+@defopt reftex-trust-label-prefix
+Non-@code{nil} means, trust the label prefix when determining label type.
+It is customary to use special label prefixes to distinguish different label
+types.  The label prefixes have no syntactic meaning in LaTeX (unless
+special packages like fancyref) are being used.  RefTeX can and by
+default does parse around each label to detect the correct label type,
+but this process can be slow when a document contains thousands of
+labels.  If you use label prefixes consistently, you may speed up
+document parsing by setting this variable to a non-nil value.  RefTeX
+will then compare the label prefix with the prefixes found in
+`reftex-label-alist' and derive the correct label type in this way.
+Possible values for this option are:
+
+@example
+t       @r{This means to trust any label prefixes found.}
+regexp  @r{If a regexp, only prefixes matched by the regexp are trusted.}
+list    @r{List of accepted prefixes, as strings.  The colon is part of}
+        @r{the prefix, e.g. ("fn:" "eqn:" "item:").}   
+nil     @r{Never trust a label prefix.}
+@end example
+The only disadvantage of using this feature is that the label context
+displayed in the label selection buffer along with each label is
+simply some text after the label definition.  This is no problem if you
+place labels keeping this in mind (e.g. @i{before} the equation, @i{at
+the beginning} of a fig/tab caption ...).  Anyway, it is probably best
+to use the regexp or the list value types to fine-tune this feature.
+For example, if your document contains thousands of footnotes with
+labels fn:xxx, you may want to set this variable to the value "^fn:$" or
+("fn:").  Then RefTeX will still do extensive parsing for any
+non-footnote labels.
+@end defopt
+
+@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
+@section Creating Labels
+@cindex Options, creating labels
+@cindex Creating labels, options
+
+@defopt reftex-insert-label-flags
+Flags governing label insertion.  The value has the form
+
+@example
+(@var{derive} @var{prompt})
+@end example
+
+If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
+label from context.  A section label for example will be derived from
+the section heading.  The conversion of the context to a valid label is
+governed by the specifications given in
+@code{reftex-derive-label-parameters}.  If @var{derive} is @code{nil},
+the default label will consist of the prefix and a unique number, like
+@samp{eq:23}.
+
+If @var{prompt} is @code{t}, the user will be prompted for a label
+string.  When @var{prompt} is @code{nil}, the default label will be
+inserted without query.
+
+So the combination of @var{derive} and @var{prompt} controls label
+insertion.  Here is a table describing all four possibilities:
+
+@example
+@group
+@var{derive} @var{prompt} @var{action}
+-----------------------------------------------------------
+nil    nil    @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
+nil    t      @r{Prompt for label.}
+t      nil    @r{Derive a label from context and insert. No query.}
+t      t      @r{Derive a label from context, prompt for confirmation.}
+@end group
+@end example
+
+Each flag may be set to @code{t}, @code{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 @samp{"s"} and @samp{"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: @code{s} (section), @code{f} (figure),
+@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
+(footnote), @code{N} (endnote) plus any definitions in
+@code{reftex-label-alist}.
+@end defopt
+
+@deffn Hook reftex-format-label-function
+If non-@code{nil}, should be a function which produces the string to
+insert as a label definition.  The function will be called with two
+arguments, the @var{label} and the @var{default-format} (usually
+@samp{\label@{%s@}}).  It should return the string to insert into the
+buffer.
+@end deffn
+
+@deffn Hook reftex-string-to-label-function
+Function to turn an arbitrary string into a valid label.
+@b{Ref@TeX{}}'s default function uses the variable
+@code{reftex-derive-label-parameters}.
+@end deffn
+
+@deffn Hook reftex-translate-to-ascii-function
+Filter function which will process a context string before it is used to
+derive a label from it.  The intended application is to convert ISO or
+Mule characters into something valid in labels.  The default function
+@code{reftex-latin1-to-ascii} removes the accents from Latin-1
+characters.  X-Symbol (>=2.6) sets this variable to the much more
+general @code{x-symbol-translate-to-ascii}.
+@end deffn
+
+@defopt reftex-derive-label-parameters
+Parameters for converting a string into a label.  This variable is a
+list of the following items:
+@table @asis
+@item @var{nwords}
+Number of words to use.
+@item @var{maxchar}
+Maximum number of characters in a label string.
+@item @var{invalid}
+@code{nil}: Throw away any words containing characters invalid in labels.@*
+@code{t}:   Throw away only the invalid characters, not the whole word.
+@item @var{abbrev}
+@code{nil}: Never abbreviate words.@*
+@code{t}:   Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
+@code{1}:   Abbreviate words if necessary to shorten label string.
+@item @var{separator}
+String separating different words in the label.
+@item @var{ignorewords}
+List of words which should not be part of labels.
+@item @var{downcase}
+@code{t}:   Downcase words before putting them into the label.@*
+@end table
+@end defopt
+
+@defopt reftex-label-illegal-re
+Regexp matching characters not valid in labels.
+@end defopt
+
+@defopt reftex-abbrev-parameters
+Parameters for abbreviation of words.  A list of four parameters.
+@table @asis
+@item @var{min-chars}
+Minimum number of characters remaining after abbreviation.
+@item @var{min-kill}
+Minimum number of characters to remove when abbreviating words.
+@item @var{before}
+Character class before abbrev point in word.
+@item @var{after}
+Character class after  abbrev point in word.
+@end table
+@end defopt
+
+@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
+@section Referencing Labels
+@cindex Options, referencing labels
+@cindex Referencing labels, options
+
+@defopt reftex-label-menu-flags
+List of flags governing the label menu makeup. The flags are:
+@table @asis
+@item @var{table-of-contents}
+Show the labels embedded in a table of context.
+@item @var{section-numbers}
+Include section numbers (like 4.1.3) in table of contents.
+@item @var{counters}
+Show counters.  This just numbers the labels in the menu.
+@item @var{no-context}
+Non-@code{nil} means do @emph{not} show the short context.
+@item @var{follow}
+Follow full context in other window.
+@item @var{show-commented}
+Show labels from regions which are commented out.
+@item @var{match-everywhere}
+Obsolete flag.
+@item @var{show-files}
+Show begin and end of included files.
+@end table
+
+Each of these flags can be set to @code{t} or @code{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 @samp{"sf"} makes the flag true for section
+and figure labels, @code{nil} for everything else.  Setting it to
+@samp{"^sf"} makes it the other way round.
+
+The available label types are: @code{s} (section), @code{f} (figure),
+@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
+(footnote), plus any definitions in @code{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.
+@end defopt
+
+@defopt 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 @samp{,-+} with prefix strings to be
+inserted into the buffer before the corresponding @code{\ref} macro.
+This is used to string together whole reference sets, like
+@samp{eqs. 1,2,3-5,6 and 7} in a single call to
+@code{reftex-reference}.
+@end defopt
+
+@defopt reftex-vref-is-default
+Non-@code{nil} means, the varioref macro @code{\vref} is used as
+default.  In the selection buffer, the @kbd{v} key toggles the reference
+macro between @code{\ref} and @code{\vref}.  The value of this variable
+determines the default which is active when entering the selection
+process.  Instead of @code{nil} or @code{t}, this may also be a string
+of type letters indicating the label types for which it should be
+true.
+@end defopt
+
+@defopt reftex-fref-is-default
+Non-@code{nil} means, the fancyref macro @code{\fref} is used as
+default.  In the selection buffer, the @kbd{V} key toggles the reference
+macro between @code{\ref}, @code{\fref} and @code{\Fref}.  The value of
+this variable determines the default which is active when entering the
+selection process.  Instead of @code{nil} or @code{t}, this may also be
+a string of type letters indicating the label types for which it should
+be true.
+@end defopt
+
+@deffn Hook reftex-format-ref-function
+If non-@code{nil}, should be a function which produces the string to
+insert as a reference.  Note that the insertion format can also be
+changed with @code{reftex-label-alist}.  This hook also is used by the
+special commands to insert @code{\vref} and @code{\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
+@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
+It should return the string to insert into the buffer.
+@end deffn
+
+@defopt reftex-level-indent
+Number of spaces to be used for indentation per section level.
+@end defopt
+
+@defopt reftex-guess-label-type
+Non-@code{nil} means, @code{reftex-reference} will try to guess the
+label type.  To do that, @b{Ref@TeX{}} will look at the word before the
+cursor and compare it with the magic words given in
+@code{reftex-label-alist}.  When it finds a match, @b{Ref@TeX{}} will
+immediately offer the correct label menu - otherwise it will prompt you
+for a label type.  If you set this variable to @code{nil}, @b{Ref@TeX{}}
+will always prompt for a label type.
+@end defopt
+
+@deffn {Normal Hook} reftex-display-copied-context-hook
+Normal Hook which is run before context is displayed anywhere.  Designed
+for @w{@code{X-Symbol}}, but may have other uses as well.
+@end deffn
+
+@deffn Hook reftex-pre-refontification-functions
+@code{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.
+@end deffn
+
+@deffn {Normal Hook} reftex-select-label-mode-hook
+Normal hook which is run when a selection buffer enters
+@code{reftex-select-label-mode}.
+@end deffn
+
+@deffn Keymap reftex-select-label-map
+The keymap which is active in the labels selection process
+(@pxref{Referencing Labels}).
+@end deffn
+
+@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
+@section Creating Citations
+@cindex Options, creating citations
+@cindex Creating citations, options
+
+@defopt reftex-bibliography-commands
+LaTeX commands which specify the BibTeX databases to use with the document.
+@end defopt
+
+@defopt reftex-bibfile-ignore-regexps
+List of regular expressions to exclude files in
+@code{\\bibliography@{..@}}.  File names matched by any of these regexps
+will not be parsed.  Intended for files which contain only
+@code{@@string} macro definitions and the like, which are ignored by
+@b{Ref@TeX{}} anyway.
+@end defopt
+
+@defopt reftex-default-bibliography
+List of BibTeX database files which should be used if none are specified.
+When @code{reftex-citation} is called from a document with neither
+a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
+environment, @b{Ref@TeX{}} will scan these files instead.  Intended for
+using @code{reftex-citation} in non-LaTeX files.  The files will be
+searched along the BIBINPUTS or TEXBIB path.
+@end defopt
+
+@defopt reftex-sort-bibtex-matches
+Sorting of the entries found in BibTeX databases by reftex-citation.
+Possible values:
+@example
+nil          @r{Do not sort entries.}
+author       @r{Sort entries by author name.}
+year         @r{Sort entries by increasing year.}
+reverse-year @r{Sort entries by decreasing year.}
+@end example
+@end defopt
+
+@defopt reftex-cite-format
+The format of citations to be inserted into the buffer.  It can be a
+string, an alist or a symbol.  In the simplest case this is just the string
+@samp{\cite@{%l@}}, which is also the default.  See the definition of
+@code{reftex-cite-format-builtin} for more complex examples.
+
+If @code{reftex-cite-format} is a string, it will be used as the format.
+In the format, the following percent escapes will be expanded.
+
+@table @code
+@item %l
+The BibTeX label of the citation.
+@item %a
+List of author names, see also @code{reftex-cite-punctuation}.
+@item %2a
+Like %a, but abbreviate more than 2 authors like Jones et al.
+@item %A
+First author name only.
+@item %e
+Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
+@samp{%E} work a well).
+@end table
+
+It is also possible to access all other BibTeX database fields:
+
+@example
+%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
+@end example
+
+@noindent
+Usually, only @samp{%l} is needed.  The other stuff is mainly for the
+echo area display, and for @code{(setq reftex-comment-citations t)}.
+
+@samp{%<} as a special operator kills punctuation and space around it
+after the string has been formatted.
+
+A pair of square brackets indicates an optional argument, and RefTeX
+will prompt for the values of these arguments.
+
+Beware that all this only works with BibTeX database files.  When
+citations are made from the @code{\bibitems} in an explicit
+@code{thebibliography} environment, only @samp{%l} is available.
+
+If @code{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
+@code{reftex-cite-format} directly yourself or set it to the
+@emph{symbol} of one of the predefined styles.  The predefined symbols
+are those which have an association in the constant
+@code{reftex-cite-format-builtin})  E.g.: @code{(setq reftex-cite-format
+'natbib)}.
+@end defopt
+
+@deffn Hook reftex-format-cite-function
+If non-@code{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 @code{reftex-cite-format}.  The function will be
+called with two arguments, the @var{citation-key} and the
+@var{default-format} (taken from @code{reftex-cite-format}).  It should
+return the string to insert into the buffer.
+@end deffn
+
+@defopt reftex-cite-prompt-optional-args
+Non-@code{nil} means, prompt for empty optional arguments in cite macros.
+When an entry in @code{reftex-cite-format} ist given with square brackets to
+indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
+prompt for values.  Possible values are:
+@example
+nil     @r{Never prompt for optional arguments}
+t       @r{Always prompt}
+maybe   @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example
+Unnecessary empty optional arguments are removed before insertion into
+the buffer.  See @code{reftex-cite-cleanup-optional-args}.
+@end defopt
+
+@defopt reftex-cite-cleanup-optional-args
+Non-@code{nil} means, remove empty optional arguments from cite macros
+if possible.
+@end defopt
+
+@defopt reftex-comment-citations
+Non-@code{nil} means add a comment for each citation describing the full
+entry.  The comment is formatted according to
+@code{reftex-cite-comment-format}.
+@end defopt
+
+@defopt reftex-cite-comment-format
+Citation format used for commented citations.  Must @emph{not} contain
+@samp{%l}.  See the variable @code{reftex-cite-format} for possible
+percent escapes.
+@end defopt
+
+@defopt reftex-cite-punctuation
+Punctuation for formatting of name lists in citations.  This is a list
+of 3 strings.
+@enumerate
+@item
+normal names separator, like @samp{, } in Jones, Brown and Miller
+@item
+final names separator, like @samp{ and }  in Jones, Brown and Miller
+@item
+The @samp{et al.} string, like @samp{ @{\it et al.@}} in
+Jones @{\it et al.@}
+@end enumerate
+@end defopt
+
+@deffn {Normal Hook} reftex-select-bib-mode-hook
+Normal hook which is run when a selection buffer enters
+@code{reftex-select-bib-mode}.
+@end deffn
+
+@deffn Keymap reftex-select-bib-map
+The keymap which is active in the citation-key selection process
+(@pxref{Creating Citations}).
+@end deffn
+
+@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations),  Options
+@section Index Support
+@cindex Options, Index support
+@cindex Index support, options
+
+@defopt reftex-support-index
+Non-@code{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 @code{nil} and you execute a command which requires index
+support, you will be asked for confirmation to turn it on and rescan the
+document.
+@end defopt
+
+@defopt reftex-index-special-chars
+List of special characters in index entries, given as strings.  These
+correspond to the @code{MakeIndex} keywords
+@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
+@end defopt
+
+@defopt reftex-index-macros
+List of macros which define index entries.  The structure of each entry
+is
+@lisp
+(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
+@end lisp
+
+@var{macro} is the macro.  Arguments should be denoted by empty braces,
+as for example in @samp{\index[]@{*@}}.  Use square brackets to denote
+optional arguments.  The star marks where the index key is.
+
+@var{index-tag} is a short name of the index.  @samp{idx} and @samp{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.
+
+@var{key} is a character which is used to identify the macro for input
+with @code{reftex-index}.  @samp{?i}, @samp{?I}, and @samp{?g} are
+reserved for default index and glossary.
+
+@var{prefix} can be a prefix which is added to the @var{key} part of the
+index entry.  If you have a macro
+@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
+should be @samp{Molecules!}.
+
+@var{exclude} can be a function.  If this function exists and returns a
+non-@code{nil} value, the index entry at point is ignored.  This was
+implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
+in the LaTeX2e @code{index} package.
+
+@var{repeat}, if non-@code{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 @code{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 @code{reftex-index-macros-builtin} to specify the main
+indexing package you are using.  Valid values are currently
+@example
+default         @r{The LaTeX default - unnecessary to specify this one}
+multind         @r{The multind.sty package}
+index           @r{The index.sty package}
+index-shortcut  @r{The index.sty packages with the ^ and _ shortcuts.}
+                @r{Should not be used - only for old documents}
+@end example
+Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
+so with a sufficiently new version of AUCTeX, you should not set the
+package here.
+@end defopt
+
+@defopt reftex-index-default-macro
+The default index macro for @code{reftex-index-selection-or-word}.
+This is a list with @code{(@var{macro-key} @var{default-tag})}.
+
+@var{macro-key} is a character identifying an index macro - see
+@code{reftex-index-macros}.
+
+@var{default-tag} is the tag to be used if the macro requires a
+@var{tag} argument.  When this is @code{nil} and a @var{tag} is needed,
+@b{Ref@TeX{}} 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.
+@end defopt
+
+@defopt reftex-index-default-tag
+Default index tag.  When working with multiple indexes, RefTeX queries
+for an index tag when creating index entries or displaying a specific
+index.  This variable controls the default offered for these queries.
+The default can be selected with @key{RET} during selection or
+completion.  Valid values of this variable are:
+@example
+nil        @r{Do not provide a default index}
+"tag"      @r{The default index tag given as a string, e.g. "idx"}
+last       @r{The last used index tag will be offered as default}
+@end example
+@end defopt
+
+@defopt reftex-index-math-format
+Format of index entries when copied from inside math mode.  When
+@code{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 @code{format} function.  This can be used to add the
+math delimiters (e.g. @samp{$}) to the string.  Requires the
+@file{texmathp.el} library which is part of AUCTeX.
+@end defopt
+
+@defopt reftex-index-phrase-file-extension
+File extension for the index phrase file.  This extension will be added
+to the base name of the master file.
+@end defopt
+
+@defopt reftex-index-phrases-logical-and-regexp
+Regexp matching the @samp{and} operator for index arguments in phrases
+file.  When several index arguments in a phrase line are separated by
+this operator, each part will generate an index macro.  So each match of
+the search phrase will produce @emph{several} different index entries.
+Make sure this does no match things which are not separators.  This
+logical @samp{and} has higher priority than the logical @samp{or}
+specified in @code{reftex-index-phrases-logical-or-regexp}.
+@end defopt
+
+@defopt reftex-index-phrases-logical-or-regexp
+Regexp matching the @samp{or} operator for index arguments in phrases
+file.  When several index arguments in a phrase line are separated by
+this operator, the user will be asked to select one of them at each
+match of the search phrase.  The first index arg will be the default.  A
+number key @kbd{1}--@kbd{9} must be pressed to switch to another.  Make
+sure this does no match things which are not separators.  The logical
+@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
+has higher priority than this logical @samp{or}.
+@end defopt
+
+@defopt reftex-index-phrases-search-whole-words
+Non-@code{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.
+@end defopt
+
+@defopt reftex-index-phrases-case-fold-search
+Non-@code{nil} means, searching for index phrases will ignore
+case.
+@end defopt
+
+@defopt reftex-index-verify-function
+A function which is called at each match during global indexing.
+If the function returns nil, the current match is skipped.
+@end defopt
+
+@defopt reftex-index-phrases-skip-indexed-matches
+Non-@code{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-@code{nil},
+@b{Ref@TeX{}} 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.
+@end defopt
+
+@defopt reftex-index-phrases-wrap-long-lines
+Non-@code{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-@code{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.
+@end defopt
+
+@defopt reftex-index-phrases-sort-prefers-entry
+Non-@code{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-@code{nil}, the index argument will be used for sorting.
+@end defopt
+
+@defopt reftex-index-phrases-sort-in-blocks
+Non-@code{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.
+@end defopt
+
+@defopt reftex-index-phrases-map
+Keymap for the Index Phrases buffer.
+@end defopt
+
+@defopt reftex-index-phrases-mode-hook
+Normal hook which is run when a buffer is put into
+@code{reftex-index-phrases-mode}.
+@end defopt
+
+@defopt reftex-index-section-letters
+The letters which denote sections in the index.  Usually these are all
+capital letters.  Don't use any downcase letters.  Order is not
+significant, the index will be sorted by whatever the sort function
+thinks is correct.  In addition to these letters, @b{Ref@TeX{}} will
+create a group @samp{!} which contains all entries sorted below the
+lowest specified letter.  In the @file{*Index*} buffer, pressing any of
+these capital letters or @kbd{!} will jump to that section.
+@end defopt
+
+@defopt reftex-index-include-context
+Non-@code{nil} means, display the index definition context in the
+@file{*Index*} buffer.  This flag may also be toggled from the
+@file{*Index*} buffer with the @kbd{c} key.
+@end defopt
+
+@defopt reftex-index-follow-mode
+Non-@code{nil} means, point in @file{*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 @file{*Index*}
+buffer with the @kbd{f} key.
+@end defopt
+
+@deffn Keymap reftex-index-map
+The keymap which is active in the @file{*Index*} buffer
+(@pxref{Index Support}).
+@end deffn
+
+@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support),  Options
+@section Viewing Cross-References
+@cindex Options, viewing cross-references
+@cindex Viewing cross-references, options
+
+@defopt reftex-view-crossref-extra
+Macros which can be used for the display of cross references.
+This is used when `reftex-view-crossref' is called with point in an
+argument of a macro.  Note that crossref viewing for citations,
+references (both ways) and index entries is hard-coded.  This variable
+is only to configure additional structures for which crossreference
+viewing can be useful.  Each entry has the structure
+@example
+(@var{macro-re} @var{search-re} @var{highlight}).
+@end example
+@var{macro-re} is matched against the macro.  @var{search-re} is the
+regexp used to search for cross references.  @samp{%s} in this regexp is
+replaced with the macro argument at point.  @var{highlight} is an
+integer indicating which subgroup of the match should be highlighted.
+@end defopt
+
+@defopt reftex-auto-view-crossref
+Non-@code{nil} means, initially turn automatic viewing of crossref info
+on.  Automatic viewing of crossref info normally uses the echo area.
+Whenever point is idle for more than @code{reftex-idle-time} seconds on
+the argument of a @code{\ref} or @code{\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
+@code{window}.  In this case a small temporary window is used for the
+display.  This feature can be turned on and off from the menu
+(Ref->Options).
+@end defopt
+
+@defopt reftex-idle-time
+Time (secs) Emacs has to be idle before automatic crossref display
+or toc recentering is done.
+@end defopt
+
+@defopt reftex-cite-view-format
+Citation format used to display citation info in the message area.  See
+the variable @code{reftex-cite-format} for possible percent
+escapes.
+@end defopt
+
+@defopt reftex-revisit-to-echo
+Non-@code{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 @code{reftex-cache-cite-echo}), or for
+BibTeX database files which are already visited by a live associated
+buffers.
+@end defopt
+
+@defopt reftex-cache-cite-echo
+Non-@code{nil} means, the information displayed in the echo area for
+cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
+saved along with the parsing information.  The cache survives document
+scans.  In order to clear it, use @kbd{M-x reftex-reset-mode}.
+@end defopt
+
+@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References),  Options
+@section Finding Files
+@cindex Options, Finding Files
+@cindex Finding files, options
+
+@defopt reftex-texpath-environment-variables
+List of specifications how to retrieve the search path for TeX files.
+Several entries are possible.
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.
+@item
+If an element starts with an exclamation mark, it is used as a command
+to retrieve the path.  A typical command with the kpathsearch library
+would be @w{@code{"!kpsewhich -show-path=.tex"}}.
+@item
+Otherwise the element itself is interpreted as a path.
+@end itemize
+Multiple directories can be separated by the system dependent
+@code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
+be expanded recursively.  See also @code{reftex-use-external-file-finders}.
+@end defopt
+
+@defopt reftex-bibpath-environment-variables
+List of specifications how to retrieve the search path for BibTeX
+files.  Several entries are possible.
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.
+@item
+If an element starts with an exclamation mark, it is used as a command
+to retrieve the path.  A typical command with the kpathsearch library
+would be @w{@code{"!kpsewhich -show-path=.bib"}}.
+@item
+Otherwise the element itself is interpreted as a path.
+@end itemize
+Multiple directories can be separated by the system dependent
+@code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
+be expanded recursively.  See also @code{reftex-use-external-file-finders}.
+@end defopt
+
+@defopt reftex-file-extensions
+Association list with file extensions for different file types.
+This is a list of items, each item is like:
+@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
+@example
+@var{type}:       @r{File type like @code{"bib"} or @code{"tex"}.}
+@var{def-ext}:    @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
+@var{other-ext}:  @r{Any number of other valid extensions for this file type.}
+@end example
+When a files is searched and it does not have any of the valid extensions,
+we try the default extension first, and then the naked file name.
+@end defopt
+
+@defopt reftex-search-unrecursed-path-first
+Non-@code{nil} means, search all specified directories before trying
+recursion.  Thus, in a path @samp{.//:/tex/}, search first @samp{./},
+then @samp{/tex/}, and then all subdirectories of @samp{./}.  If this
+option is @code{nil}, the subdirectories of @samp{./} are searched
+before @samp{/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 @code{nil} if the default makes @b{Ref@TeX{}} finding files with
+equal names in wrong sequence.
+@end defopt
+
+@defopt reftex-use-external-file-finders
+Non-@code{nil} means, use external programs to find files.  Normally,
+@b{Ref@TeX{}} searches the paths given in the environment variables
+@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
+database files.  With this option turned on, it calls an external
+program specified in the option @code{reftex-external-file-finders}
+instead.  As a side effect, the variables
+@code{reftex-texpath-environment-variables} and
+@code{reftex-bibpath-environment-variables} will be ignored.
+@end defopt
+
+@defopt reftex-external-file-finders
+Association list with external programs to call for finding files.  Each
+entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
+@var{type} is either @code{"tex"} or @code{"bib"}.  @var{program} is a
+string containing the external program to use with any arguments.
+@code{%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 @code{reftex-use-external-file-finders} is
+non-@code{nil}.
+@end defopt
+
+@page
+@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
+@section Optimizations
+@cindex Options, optimizations
+@cindex Optimizations, options
+
+@defopt reftex-keep-temporary-buffers
+Non-@code{nil} means, keep buffers created for parsing and lookup.
+@b{Ref@TeX{}} sometimes needs to visit files related to the current
+document.  We distinguish files visited for
+@table @asis
+@item PARSING
+Parts of a multifile document loaded when (re)-parsing the
+document.
+@item LOOKUP
+BibTeX database files and TeX files loaded to find a reference, to
+display label context, etc.
+@end table
+The created buffers can be kept for later use, or be thrown away
+immediately after use, depending on the value of this variable:
+
+@table @code
+@item nil
+Throw away as much as possible.
+@item t
+Keep everything.
+@item 1
+Throw away buffers created for parsing, but keep the ones created for
+lookup.
+@end table
+
+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
+@code{reftex-initialize-temporary-buffers}.
+@end defopt
+
+@defopt reftex-initialize-temporary-buffers
+Non-@code{nil} means do initializations even when visiting file
+temporarily.  When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
+other stuff to briefly visit a file. When @code{t}, the full default
+initializations are done (@code{find-file-hook} etc.).  Instead of
+@code{t} or @code{nil}, this variable may also be a list of hook
+functions to do a minimal initialization.
+@end defopt
+
+@defopt reftex-no-include-regexps
+List of regular expressions to exclude certain input files from parsing.
+If the name of a file included via @code{\include} or @code{\input} is
+matched by any of the regular expressions in this list, that file is not
+parsed by @b{Ref@TeX{}}.
+@end defopt
+
+@defopt reftex-enable-partial-scans
+Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
+Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
+commands, or with the @kbd{r} key in menus.  When this option is
+@code{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 @kbd{C-u C-u} prefix or the capital @kbd{R} key in
+menus.
+@end defopt
+
+@defopt reftex-save-parse-info
+Non-@code{nil} means, save information gathered with parsing in files.
+The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
+used to save the information.  When this variable is @code{t},
+@itemize @minus
+@item
+accessing the parsing information for the first time in an editing
+session will read that file (if available) instead of parsing the
+document.
+@item
+exiting Emacs or killing a buffer in reftex-mode will cause a new
+version of the file to be written.
+@end itemize
+@end defopt
+
+@defopt reftex-parse-file-extension
+File extension for the file in which parser information is stored.
+This extension is added to the base name of the master file.
+@end defopt
+
+@defopt reftex-allow-automatic-rescan
+Non-@code{nil} means, @b{Ref@TeX{}} 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.
+@end defopt
+
+@defopt reftex-use-multiple-selection-buffers
+Non-@code{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 @code{reftex-auto-update-selection-buffers}.
+@end defopt
+
+@defopt reftex-auto-update-selection-buffers
+Non-@code{nil} means, selection buffers will be updated automatically.
+When a new label is defined with @code{reftex-label}, all selection
+buffers associated with that label category are emptied, in order to
+force an update upon next use.  When @code{nil}, the buffers are left
+alone and have to be updated by hand, with the @kbd{g} key from the
+label selection process.  The value of this variable will only have any
+effect when @code{reftex-use-multiple-selection-buffers} is
+non-@code{nil}.
+@end defopt
+
+@node Options (Fontification), Options (Misc), Options (Optimizations), Options
+@section Fontification
+@cindex Options, fontification
+@cindex Fontification, options
+
+@defopt reftex-use-fonts
+Non-@code{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.
+@end defopt
+
+@defopt reftex-refontify-context
+Non-@code{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:
+@table @code
+@item nil
+Never refontify.
+@item t
+Always refontify.
+@item 1
+Refontify when necessary, e.g. with old versions of the x-symbol
+package.
+@end table
+The option is ignored when @code{reftex-use-fonts} is @code{nil}.
+@end defopt
+
+@defopt reftex-highlight-selection
+Non-@code{nil} means, highlight selected text in selection and
+@file{*toc*} buffers.  Normally, the text near the cursor is the
+@emph{selected} text, and it is highlighted.  This is the entry most
+keys in the selection and @file{*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 @emph{instead} or @emph{as well}. The
+variable may have one of these values:
+
+@example
+nil      @r{No highlighting.}
+cursor   @r{Highlighting is cursor driven.}
+mouse    @r{Highlighting is mouse driven.}
+both     @r{Both cursor and mouse trigger highlighting.}
+@end example
+
+Changing this variable requires to rebuild the selection and *toc*
+buffers to become effective (keys @kbd{g} or @kbd{r}).
+@end defopt
+
+@defopt reftex-cursor-selected-face
+Face name to highlight cursor selected item in toc and selection buffers.
+See also the variable @code{reftex-highlight-selection}.
+@end defopt
+@defopt reftex-mouse-selected-face
+Face name to highlight mouse selected item in toc and selection buffers.
+See also the variable @code{reftex-highlight-selection}.
+@end defopt
+@defopt reftex-file-boundary-face
+Face name for file boundaries in selection buffer.
+@end defopt
+@defopt reftex-label-face
+Face name for labels in selection buffer.
+@end defopt
+@defopt reftex-section-heading-face
+Face name for section headings in toc and selection buffers.
+@end defopt
+@defopt reftex-toc-header-face
+Face name for the header of a toc buffer.
+@end defopt
+@defopt reftex-bib-author-face
+Face name for author names in bib selection buffer.
+@end defopt
+@defopt reftex-bib-year-face
+Face name for year in bib selection buffer.
+@end defopt
+@defopt reftex-bib-title-face
+Face name for article title in bib selection buffer.
+@end defopt
+@defopt reftex-bib-extra-face
+Face name for bibliographic information in bib selection buffer.
+@end defopt
+@defopt reftex-select-mark-face
+Face name for marked entries in the selection buffers.
+@end defopt
+@defopt reftex-index-header-face
+Face name for the header of an index buffer.
+@end defopt
+@defopt reftex-index-section-face
+Face name for the start of a new letter section in the index.
+@end defopt
+@defopt reftex-index-tag-face
+Face name for index names (for multiple indices).
+@end defopt
+@defopt reftex-index-face
+Face name for index entries.
+@end defopt
+
+@node Options (Misc), , Options (Fontification), Options
+@section Miscellaneous
+@cindex Options, misc
+
+@defopt reftex-extra-bindings
+Non-@code{nil} means, make additional key bindings on startup.  These
+extra bindings are located in the users @samp{C-c letter}
+map.  @xref{Key Bindings}.
+@end defopt
+
+@defopt reftex-plug-into-AUCTeX
+Plug-in flags for AUCTeX interface.  This variable is a list of
+5 boolean flags.  When a flag is non-@code{nil}, @b{Ref@TeX{}}
+will
+
+@example
+- supply labels in new sections and environments  (flag 1)
+- supply arguments for macros like @code{\label}         (flag 2)
+- supply arguments for macros like @code{\ref}           (flag 3)
+- supply arguments for macros like @code{\cite}          (flag 4)
+- supply arguments for macros like @code{\index}         (flag 5)
+@end example
+
+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 @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
+Supplying macro arguments applies when you insert such a macro
+interactively with @kbd{C-c @key{RET}}.@*
+See the AUCTeX documentation for more information.
+@end defopt
+
+@defopt reftex-revisit-to-follow
+Non-@code{nil} means, follow-mode will revisit files if necessary.
+When nil, follow-mode will be suspended for stuff in unvisited files.
+@end defopt
+
+@defopt reftex-allow-detached-macro-args
+Non-@code{nil} means, allow arguments of macros to be detached by
+whitespace.  When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
+[xxx] @{aaa@}}} will be considered an argument of @code{\bb}.  Note that
+this will be the case even if @code{\bb} is defined with zero or one
+argument.
+@end defopt
+
+@node Keymaps and Hooks, Changes, Options, Top
+@section Keymaps and Hooks
+@cindex Keymaps
+
+@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
+
+@deffn Keymap reftex-mode-map
+The keymap for @b{Ref@TeX{}} mode.
+@end deffn
+
+@deffn {Normal Hook} reftex-load-hook
+Normal hook which is being run when loading @file{reftex.el}.
+@end deffn
+
+@deffn {Normal Hook} reftex-mode-hook
+Normal hook which is being run when turning on @b{Ref@TeX{}} mode.
+@end deffn
+
+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 @b{Ref@TeX{}}.
+
+@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top
+@chapter Changes
+@cindex Changes
+
+Here is a list of recent changes to @b{Ref@TeX{}}.
+
+@noindent @b{Version 4.28}
+@itemize @bullet
+@item Support for the Jurabib package.
+@item Improvements when selecting several items in a selection buffer.
+@end itemize
+
+@noindent @b{Version 4.26}
+@itemize @bullet
+@item
+Support for global incremental search.
+@item
+Some improvements for XEmacs compatibility.
+@end itemize
+
+@noindent @b{Version 4.25}
+@itemize @bullet
+@item
+Fixed bug with @samp{%F} in a label prefix.  Added new escapes
+@samp{%m} and @samp{%M} for mater file name and master directory.
+@end itemize
+
+@noindent @b{Version 4.24}
+@itemize @bullet
+@item 
+Inserting citation commands now prompts for optional arguments
+when called with a prefix argument.  Related new options are
+@code{reftex-cite-prompt-optional-args} and
+@code{reftex-cite-cleanup-optional-args}. 
+@item
+New option @code{reftex-trust-label-prefix}.  Configure this variable
+if you'd like RefTeX to base its classification of labels on prefixes.
+This can speed-up document parsing, but may in some cases reduce the
+quality of the context used by RefTeX to describe a label.
+@item
+Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
+is non-nil.
+@item
+Fixed bugs in indexing: Case-sensitive search, quotes before and/or
+after words.  Disabled indexing in comment lines.
+@end itemize
+
+@noindent @b{Version 4.22}
+@itemize @bullet
+@item 
+New command @code{reftex-create-bibtex-file} to create a new database
+with all entries referenced in the current document.
+@item
+New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
+from entries marked in a citation selection buffer.
+@end itemize
+
+@noindent @b{Version 4.21}
+@itemize @bullet
+@item 
+Renaming labels from the toc buffer with key @kbd{M-%}.
+@end itemize
+
+@noindent @b{Version 4.20}
+@itemize @bullet
+@item
+Structure editing capabilities.  The command keys @kbd{<} and @kbd{>} in
+the TOC buffer promote/demote the section at point or all sections in
+the current region.
+@item
+New option @code{reftex-toc-split-windows-fraction} to set the size of
+the window used by the TOC.  This makes the old variable
+@code{reftex-toc-split-windows-horizontally-fraction} obsolete.
+@item
+A dedicated frame can show the TOC with the current section
+always automatically highlighted.  The frame is created and
+deleted from the toc buffer with the @kbd{d} key.
+@end itemize
+
+@noindent @b{Version 4.19}
+@itemize @bullet
+@item
+New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
+section in the TOC buffer without selecting the TOC window.
+@item
+Recentering happens automatically in idle time when the option
+@code{reftex-auto-recenter-toc} is turned on.
+@item
+Fixed several bugs related to automatic cursor positioning in the TOC
+buffer.
+@item
+The highlight in the TOC buffer stays when the focus moves to a
+different window.
+@item
+New command `reftex-goto-label'.
+@item
+Part numbers are no longer included in chapter numbers, and a new
+part does not reset the chapter counter.  See new option
+@code{reftex-part-resets-chapter}.
+@end itemize
+
+@noindent @b{Version 4.18}
+@itemize @bullet
+@item
+@code{reftex-citation} uses the word before the cursor as a default
+search string.
+@item
+Simplified several regular expressions for speed.
+@item
+Better support for chapterbib.
+@end itemize
+
+@noindent @b{Version 4.17}
+@itemize @bullet
+@item
+The toc window can be split off horizontally.  See new options
+@code{reftex-toc-split-windows-horizontally},
+@code{reftex-toc-split-windows-horizontally-fraction}.
+@item
+It is possible to specify a function which verifies an index match
+during global indexing.  See new option @code{reftex-index-verify-function}.
+@item
+The macros which input a file in LaTeX (like \input, \include) can
+be configured.  See new option @code{reftex-include-file-commands}.
+@item
+The macros which specify the bibliography file (like \bibliography) can
+be configured.  See new option @code{reftex-bibliography-commands}.
+@item
+The regular expression used to search for the \bibliography macro has
+been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
+chapterbib.
+@item
+Small bug fixes.
+@end itemize
+
+@noindent @b{Version 4.15}
+@itemize @bullet
+@item
+Fixed bug with parsing of BibTeX files, when fields contain quotes or
+unmatched parenthesis.
+@item
+Small bug fixes.
+@item
+Improved interaction with Emacs LaTeX mode.
+@end itemize
+
+@noindent @b{Version 4.12}
+@itemize @bullet
+@item
+Support for @file{bibentry} citation style.
+@end itemize
+
+@noindent @b{Version 4.11}
+@itemize @bullet
+@item
+Fixed bug which would parse @samp{\Section} just like @samp{\section}.
+@end itemize
+
+@noindent @b{Version 4.10}
+@itemize @bullet
+@item
+Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
+with @file{reftex-vars.el} on DOS machines.
+@item
+New options @code{reftex-parse-file-extension} and
+@code{reftex-index-phrase-file-extension}.
+@end itemize
+
+@noindent [.....]
+@ignore
+@noindent @b{Version 4.09}
+@itemize @bullet
+@item
+New option @code{reftex-toc-max-level} to limit the depth of the toc.
+New key binding @kbd{t} in the @file{*toc*} buffer to change this
+setting.
+@item
+RefTeX maintains an @file{Index Phrases} file in which phrases can be
+collected.  When the document is ready, RefTeX can search all
+these phrases and assist indexing all matches.
+@item
+The variables @code{reftex-index-macros} and
+@code{reftex-index-default-macro} have changed their syntax slightly.
+The @var{repeat} parameter has move from the latter to the former.
+Also calls to @code{reftex-add-index-macros} from AUCTeX style files
+need to be adapted.
+@item
+The variable @code{reftex-section-levels} no longer contains the
+default stuff which has been moved to a constant.
+@item
+Environments like theorems can be placed into the TOC by putting
+entries for @samp{"begin@{theorem@}"} in
+@code{reftex-setion-levels}.
+@end itemize
+
+@noindent @b{Version 4.06}
+@itemize @bullet
+@item
+@code{reftex-section-levels} can contain a function to compute the level
+of a sectioning command.
+@item
+Multiple @code{thebibliography} environments recognized.
+@end itemize
+
+@noindent @b{Version 4.04}
+@itemize @bullet
+@item
+New option @code{reftex-index-default-tag} implements a default for queries.
+@end itemize
+
+@noindent @b{Version 4.02}
+@itemize @bullet
+@item
+macros ending in @samp{refrange} are considered to contain references.
+@item
+Index entries made with @code{reftex-index-selection-or-word} in TeX
+math mode automatically get enclosing @samp{$} to preserve math mode.  See
+new option @code{reftex-index-math-format}.  Requires AUCTeX.
+@end itemize
+
+@noindent @b{Version 4.01}
+@itemize @bullet
+@item
+New command @code{reftex-index-globally} to index a word in many
+places in the document.  Also available from the index buffer with
+@kbd{&}.
+@item
+The first item in a @code{reftex-label-alist} entry may now also be a parser
+function to do non-standard parsing.
+@item
+@code{reftex-auto-view-crossref} no longer interferes with
+@code{pop-up-frames} (patch from Stefan Monnier).
+@end itemize
+
+@noindent @b{Version 4.00}
+@itemize @bullet
+@item
+RefTeX has been split into several smaller files which are autoloaded on
+demand.
+@item
+Index support, along with many new options.
+@item
+The selection of keys for @code{\ref} and @code{\cite} now allows to
+select multiple items by marking entries with the @kbd{m} key.
+@item
+Fancyref support.
+@end itemize
+
+@noindent @b{Version 3.43}
+@itemize @bullet
+@item
+Viewing cross-references generalized.  Now works on @code{\label},
+@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
+these, and from BibTeX buffers.
+@item
+New option @code{reftex-view-crossref-extra}.
+@item
+Support for the additional sectioning commands @code{\addchap} and
+@code{\addsec} which are defined in the LaTeX KOMA-Script classes.
+@item
+Files in @code{reftex-default-bibliography} will be searched along
+@code{BIBINPUTS} path.
+@item
+Reading a parse file now checks consistency.
+@end itemize
+
+@noindent @b{Version 3.42}
+@itemize @bullet
+@item
+File search further refined.  New option @code{reftex-file-extensions}.
+@item
+@file{*toc*} buffer can show the file boundaries of a multifile
+document, all labels and associated context.  New keys @kbd{i}, @kbd{l},
+and @kbd{c}.  New options @code{reftex-toc-include-labels},
+@code{reftex-toc-include-context},
+@code{reftex-toc-include-file-boundaries}. 
+@end itemize
+
+@noindent @b{Version 3.41}
+@itemize @bullet
+@item
+New options @code{reftex-texpath-environment-variables},
+@code{reftex-use-external-file-finders},
+@code{reftex-external-file-finders},
+@code{reftex-search-unrecursed-path-first}.
+@item
+@emph{kpathsearch} support.  See new options and
+@code{reftex-bibpath-environment-variables}.
+@end itemize
+
+@noindent @b{Version 3.38}
+@itemize @bullet
+@item
+@code{reftex-view-crossref} no longer moves to find a macro.  Point has
+to be on the macro argument.
+@end itemize
+
+@noindent @b{Version 3.36}
+@itemize @bullet
+@item
+New value @code{window} for option @code{reftex-auto-view-crossref}.
+@end itemize
+
+@noindent @b{Version 3.35}
+@itemize @bullet
+@item
+ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
+This takes back the related changes in 3.34 for safety reasons.
+@end itemize
+
+@noindent @b{Version 3.34}
+@itemize @bullet
+@item
+Additional flag in @code{reftex-derive-label-parameters} do make only
+lowercase labels (default @code{t}).
+@item
+All @file{.rel} files have a final newline to avoid queries.
+@item
+Single byte representations of accented European letters (ISO-8859-1)
+are now valid in labels.
+@end itemize
+
+@noindent @b{Version 3.33}
+@itemize @bullet
+@item
+Multiple selection buffers are now hidden buffers (they start with a
+SPACE).
+@item
+Fixed bug with file search when TEXINPUTS environment variable is empty.
+@end itemize
+
+@noindent @b{Version 3.30}
+@itemize @bullet
+@item
+In @code{reftex-citation}, the regular expression used to scan BibTeX
+files can be specified using completion on known citation keys.
+@item
+New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
+entries.
+@item
+New command @code{reftex-renumber-simple-labels} to renumber simple
+labels like @samp{eq:13} sequentially through a document.
+@end itemize
+
+@noindent @b{Version 3.28}
+@itemize @bullet
+@item
+Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
+timer, since itimer restart is not reliable.
+@item
+Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
+@item
+Expansion of recursive tex and bib path rewritten.
+@item
+Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
+@item
+Fixed bug with section numbering after *-red sections.
+@end itemize
+
+@noindent @b{Version 3.27}
+@itemize @bullet
+@item
+Macros can define @emph{neutral} labels, just like @code{\label}
+itself.
+@item
+New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
+@end itemize
+
+@noindent @b{Version 3.26}
+@itemize @bullet
+@item
+[X]Emacs 19 no longer supported.  Use 3.22 for Emacs 19.
+@item
+New hooks @code{reftex-translate-to-ascii-function},
+@code{reftex-string-to-label-function}.
+@item
+Made sure automatic crossref display will not visit/scan files.
+@end itemize
+
+@noindent @b{Version 3.25}
+@itemize @bullet
+@item
+Echoing of citation info caches the info for displayed entries.
+New option @code{reftex-cache-cite-echo}.
+@item
+@kbd{M-x reftex-reset-mode} now also removes the file with parsing
+info.
+@item
+Default of @code{reftex-revisit-to-follow} changed to nil.
+@end itemize
+
+@noindent @b{Version 3.24}
+@itemize @bullet
+@item
+New option @code{reftex-revisit-to-echo}.
+@item
+Interface with X-Symbol (>=2.6) is now complete and stable.
+@item
+Adapted to new outline, which uses overlays.
+@item
+File names in @code{\bibliography} may now have the @code{.bib}
+extension.
+@item
+Fixed Bug with parsing "single file" from master file buffer.
+@end itemize
+
+@noindent @b{Version 3.23}
+@itemize @bullet
+@item
+Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
+@item
+@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
+file.
+@item
+The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
+automatic display of crossref information in the echo area.  See
+variable @code{reftex-auto-view-crossref}.
+@item
+AUCTeX interface updates:
+@itemize @minus
+@item
+AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
+@item
+@b{Ref@TeX{}} notifies AUCTeX about new labels.
+@item
+@code{TeX-arg-ref} no longer used (introduction was unnecessary).
+@item
+@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
+@item
+Settings added to @b{Ref@TeX{}} via style files remain local.
+@end itemize
+@item
+Fixed bug with @code{reftex-citation} in non-latex buffers.
+@item
+Fixed bug with syntax table and context refontification.
+@item
+Safety-net for name change of @code{font-lock-reference-face}.
+@end itemize
+
+@noindent @b{Version 3.22}
+@itemize @bullet
+@item
+Fixed bug with empty context strings.
+@item
+@code{reftex-mouse-view-crossref} is now bound by default at
+@kbd{S-mouse-2}.
+@end itemize
+
+@noindent @b{Version 3.21}
+@itemize @bullet
+@item
+New options for all faces used by @b{Ref@TeX{}}. They're in the
+customization group @code{reftex-fontification-configurations}.
+@end itemize
+
+@noindent @b{Version 3.19}
+@itemize @bullet
+@item
+Fixed bug with AUCTeX @code{TeX-master}.
+@end itemize
+
+@noindent @b{Version 3.18}
+@itemize @bullet
+@item
+The selection now uses a recursive edit, much like minibuffer input.
+This removes all restrictions during selection.  E.g. you can now
+switch buffers at will, use the mouse etc.
+@item
+New option @code{reftex-highlight-selection}.
+@item
+@kbd{mouse-2} can be used to select in selection and @file{*toc*}
+buffers.
+@item
+Fixed some problems regarding the interaction with VIPER mode.
+@item
+Follow-mode is now only used after point motion.
+@item
+@b{Ref@TeX{}} now finally does not fontify temporary files anymore.
+@end itemize
+
+@noindent @b{Version 3.17}
+@itemize @bullet
+@item
+Additional bindings in selection and @file{*toc*} buffers.  @kbd{g}
+redefined.
+@item
+New command @code{reftex-save-all-document-buffers}.
+@item
+Magic word matching made more intelligent.
+@item
+Selection process can switch to completion (with @key{TAB}).
+@item
+@code{\appendix} is now recognized and influences section numbering.
+@item
+File commentary shortened considerably (use Info documentation).
+@item
+New option @code{reftex-no-include-regexps} to skip some include files.
+@item
+New option @code{reftex-revisit-to-follow}.
+@end itemize
+
+@noindent @b{Version 3.16}
+@itemize @bullet
+@item
+New hooks @code{reftex-format-label-function},
+@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
+@item
+TeXInfo documentation completed.
+@item
+Some restrictions in Label inserting and referencing removed.
+@item
+New variable @code{reftex-default-bibliography}.
+@end itemize
+
+@noindent @b{Version 3.14}
+@itemize @bullet
+@item
+Selection buffers can be kept between selections: this is faster.
+See new variable @code{reftex-use-multiple-selection-buffers}.
+@item
+Prefix interpretation of reftex-view-crossref changed.
+@item
+Support for the @code{varioref} package (@kbd{v} key in selection
+buffer).
+@end itemize
+
+@noindent @b{Version 3.12}
+@itemize @bullet
+@item
+There are 3 new keymaps for customization: @code{reftex-toc-map},
+@code{reftex-select-label-map}, @code{reftex-select-bib-map}.
+@item
+Refontification uses more standard font-lock stuff.
+@item
+When no BibTeX database files are specified, citations can also use
+@code{\bibitem} entries from a @code{thebibliography} environment.
+@end itemize
+
+@noindent @b{Version 3.11}
+@itemize @bullet
+@item
+Fixed bug which led to naked label in (e.g.) footnotes.
+@item
+Added scroll-other-window functions to RefTeX-Select.
+@end itemize
+
+@noindent @b{Version 3.10}
+@itemize @bullet
+@item
+Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
+@item
+Removed unimportant code which caused OS/2 Emacs to crash.
+@item
+All customization variables now accessible from menu.
+@end itemize
+
+@noindent @b{Version 3.07}
+@itemize @bullet
+@item
+@code{Ref} menu improved.
+@end itemize
+
+@noindent @b{Version 3.05}
+@itemize @bullet
+@item
+Compatibility code now first checks for XEmacs feature.
+@end itemize
+
+@noindent @b{Version 3.04}
+@itemize @bullet
+@item
+Fixed BUG in the @emph{xr} support.
+@end itemize
+
+@noindent @b{Version 3.03}
+@itemize @bullet
+@item
+Support for the LaTeX package @code{xr}, for inter-document
+references.
+@item
+A few (minor) Mule-related changes.
+@item
+Fixed bug which could cause @emph{huge} @file{.rel} files.
+@item
+Search for input and @file{.bib} files with recursive path definitions.
+@end itemize
+
+@noindent @b{Version 3.00}
+@itemize @bullet
+@item
+@b{Ref@TeX{}} should work better for very large projects:
+@item
+The new parser works without creating a master buffer.
+@item
+Rescanning can be limited to a part of a multifile document.
+@item
+Information from the parser can be stored in a file.
+@item
+@b{Ref@TeX{}} can deal with macros having a naked label as an argument.
+@item
+Macros may have white space and newlines between arguments.
+@item
+Multiple identical section headings no longer confuse
+@code{reftex-toc}.
+@item
+@b{Ref@TeX{}} should work correctly in combination with buffer-altering
+packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
+@item
+All labeled environments discussed in @emph{The LaTeX Companion} by
+Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
+@b{Ref@TeX{}}'s defaults.
+@end itemize
+
+@noindent @b{Version 2.17}
+@itemize @bullet
+@item
+Label prefix expands % escapes with current file name and other stuff.
+@item
+Citation format now with % escapes.  This is not backward
+compatible!
+@item
+TEXINPUTS variable recognized when looking for input files.
+@item
+Context can be the nth argument of a macro.
+@item
+Searching in the select buffer is now possible (@kbd{C-s} and
+@kbd{C-r}).
+@item
+Display and derive-label can use two different context methods.
+@item
+AMSmath @code{xalignat} and @code{xxalignat} added.
+@end itemize
+
+@noindent @b{Version 2.14}
+@itemize @bullet
+@item
+Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
+AUCTeX.
+@end itemize
+
+@noindent @b{Version 2.11}
+@itemize @bullet
+@item
+Submitted for inclusion to Emacs and XEmacs.
+@end itemize
+
+@noindent @b{Version 2.07}
+@itemize @bullet
+@item
+New functions @code{reftex-search-document},
+@code{reftex-query-replace-document}.
+@end itemize
+
+@noindent @b{Version 2.05}
+@itemize @bullet
+@item
+Support for @file{custom.el}.
+@item
+New function @code{reftex-grep-document} (thanks to Stephen Eglen).
+@end itemize
+
+@noindent @b{Version 2.03}
+@itemize @bullet
+@item
+@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
+default environments.
+@item
+@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
+@item
+New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
+@code{reftex-arg-cite}.
+@item
+Emacs/XEmacs compatibility reworked.  XEmacs 19.15 now is
+required.
+@item
+@code{reftex-add-to-label-alist} (to be called from AUCTeX style
+files).
+@item
+Finding context with a hook function.
+@item
+Sorting BibTeX entries (new variable:
+@code{reftex-sort-bibtex-matches}).
+@end itemize
+
+@noindent @b{Version 2.00}
+@itemize @bullet
+@item
+Labels can be derived from context (default for sections).
+@item
+Configuration of label insertion and label referencing revised.
+@item
+Crossref fields in BibTeX database entries.
+@item
+@code{reftex-toc} introduced (thanks to Stephen Eglen).
+@end itemize
+
+@noindent @b{Version 1.09}
+@itemize @bullet
+@item
+Support for @code{tex-main-file}, an analogue for
+@code{TeX-master}.
+@item
+MS-DOS support.
+@end itemize
+
+@noindent @b{Version 1.07}
+@itemize @bullet
+@item
+@b{Ref@TeX{}} gets its own menu.
+@end itemize
+
+@noindent @b{Version 1.05}
+@itemize @bullet
+@item
+XEmacs port.
+@end itemize
+
+@noindent @b{Version 1.04}
+@itemize @bullet
+@item
+Macros as wrappers, AMSTeX support, delayed context parsing for
+new labels.
+@end itemize
+@end ignore
+
+@noindent @b{Version 1.00}
+@itemize @bullet
+@item
+released on 7 Jan 1997.
+@end itemize
+
+@node GNU Free Documentation License, Index, Changes, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
+@ignore
+   arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43
+@end ignore