comparison man/reftex.texi @ 49600:23a1cea22d13

Trailing whitespace deleted.

49599:5ade352e8d1c

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.

additional labeled environments you have defined yourself (variable
@code{reftex-label-alist}).@refill

@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)@refill
@end itemize
@noindent
Which labels are created how is configurable with the variable

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.@refill  
@end enumerate

@node Table of Contents, Labels and References, Introduction, Top
@chapter Table of Contents
@cindex @file{*toc*} buffer

Kill the @file{*toc*} buffer, return to the position where
@code{reftex-toc} was last called.@refill

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

@item c
@vindex reftex-toc-include-context
Toggle the display of label and index context in the @file{*toc*}

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

@tablesubheading{Displaying Context}
@item @key{SPC}
Show the surroundings of the definition of the current label in another

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

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

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

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

@item #
Toggle the display of a label counter in the selection buffer.@refill

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]

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

      '((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

[y]    \citeyear@{%l@}
@end example

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)}).@refill

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

@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

may not last long enough to do everything in one go.@refill

@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.}:@refill

@table @kbd
@item y
Replace this match with the proposed string.

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.@refill
@item n
Go to next entry.@refill
@item p
Go to previous entry.@refill

@tablesubheading{Access to document locations}
@item @key{SPC}
Show the place in the document where this index entry is defined.@refill 

@item @key{TAB}
Go to the definition of the current index entry in another
window.@refill

appearance of the entry in the index.  When called with @kbd{C-u}
prefix, kill the entire @var{visual} part.@refill

@item (
Toggle the beginning of page range property @samp{|(} of the
entry.@refill 

@item )
Toggle the end of page range property @samp{|)} of the entry.@refill 

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

@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}).@refill 

@tablesubheading{Exiting}
@item q
Hide the @file{*Index*} buffer.@refill

Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
buffer.@refill

@item s
Switch to a different index (for documents with multiple
indices).@refill 
@end table


@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
@section Builtin Index Macros

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

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

@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

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

@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

@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

@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

   (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

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:@refill 
@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

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

@item
@b{Idle timers in XEmacs}@*
@cindex Idle timer restart
@vindex reftex-use-itimer-in-xemacs

buffer.@refill @*
When called with one or two @kbd{C-u} prefixes, first rescans the
document.  When called with a numeric prefix, make that many citations.
When called with point inside the braces of a @code{\cite} command, it
will add another key, ignoring the value of
@code{reftex-cite-format}.@refill @* 
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.@refill

@defopt reftex-auto-recenter-toc
Non-@code{nil} means, initially turn automatic recentering of toc on.
When active, the @file{*TOC*} buffer will always show the section you
are currently working in.  Recentering happens whenever Emacs is idle
for more than `reftex-idle-time' seconds.
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

called.@refill
@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}.@refill 
@end deffn

@deffn Keymap reftex-select-label-map
The keymap which is active in the labels selection process
(@pxref{Referencing Labels}).@refill

@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}.@refill 
@end deffn

@deffn Keymap reftex-select-bib-map
The keymap which is active in the citation-key selection process
(@pxref{Creating Citations}).@refill

document.@refill
@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

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

display.  This feature can be turned on and off from the menu
(Ref->Options).@refill
@end defopt

@defopt reftex-idle-time
Time (secs) Emacs has to be idle before automatic crossref display 
or toc recentering is done.@refill
@end defopt

@defopt reftex-cite-view-format
Citation format used to display citation info in the message area.  See

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 legal extensions for this file type.}

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

@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.34}
@itemize @bullet
@item

@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.42}

Reading a parse file now checks consistency.
@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

@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.@refill 
@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.@refill
@item
The variables @code{reftex-index-macros} and
@code{reftex-index-default-macro} have changed their syntax slightly.

The variable @code{reftex-section-levels} no longer contains the
default stuff which has been moved to a constant.@refill
@item
Environments like theorems can be placed into the TOC by putting
entries for @samp{"begin@{theorem@}"} in
@code{reftex-setion-levels}.@refill 
@end itemize
@noindent @b{Version 4.10}
@itemize @bullet
@item
Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict

Improved interaction with Emacs LaTeX mode.
@end itemize
@end ignore
@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

49600:23a1cea22d13

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.

additional labeled environments you have defined yourself (variable
@code{reftex-label-alist}).@refill

@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)@refill
@end itemize
@noindent
Which labels are created how is configurable with the variable

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.@refill
@end enumerate

@node Table of Contents, Labels and References, Introduction, Top
@chapter Table of Contents
@cindex @file{*toc*} buffer

Kill the @file{*toc*} buffer, return to the position where
@code{reftex-toc} was last called.@refill

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

@item c
@vindex reftex-toc-include-context
Toggle the display of label and index context in the @file{*toc*}

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

@tablesubheading{Displaying Context}
@item @key{SPC}
Show the surroundings of the definition of the current label in another

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

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

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

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

@item #
Toggle the display of a label counter in the selection buffer.@refill

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]

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

      '((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

[y]    \citeyear@{%l@}
@end example

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)}).@refill

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

@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

may not last long enough to do everything in one go.@refill

@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.}:@refill

@table @kbd
@item y
Replace this match with the proposed string.

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.@refill
@item n
Go to next entry.@refill
@item p
Go to previous entry.@refill

@tablesubheading{Access to document locations}
@item @key{SPC}
Show the place in the document where this index entry is defined.@refill

@item @key{TAB}
Go to the definition of the current index entry in another
window.@refill

appearance of the entry in the index.  When called with @kbd{C-u}
prefix, kill the entire @var{visual} part.@refill

@item (
Toggle the beginning of page range property @samp{|(} of the
entry.@refill

@item )
Toggle the end of page range property @samp{|)} of the entry.@refill

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

@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}).@refill

@tablesubheading{Exiting}
@item q
Hide the @file{*Index*} buffer.@refill

Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
buffer.@refill

@item s
Switch to a different index (for documents with multiple
indices).@refill
@end table


@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
@section Builtin Index Macros

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

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

@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

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

@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

@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

@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

   (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

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:@refill
@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

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

@item
@b{Idle timers in XEmacs}@*
@cindex Idle timer restart
@vindex reftex-use-itimer-in-xemacs

buffer.@refill @*
When called with one or two @kbd{C-u} prefixes, first rescans the
document.  When called with a numeric prefix, make that many citations.
When called with point inside the braces of a @code{\cite} command, it
will add another key, ignoring the value of
@code{reftex-cite-format}.@refill @*
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.@refill

@defopt reftex-auto-recenter-toc
Non-@code{nil} means, initially turn automatic recentering of toc on.
When active, the @file{*TOC*} buffer will always show the section you
are currently working in.  Recentering happens whenever Emacs is idle
for more than `reftex-idle-time' seconds.
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

called.@refill
@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}.@refill
@end deffn

@deffn Keymap reftex-select-label-map
The keymap which is active in the labels selection process
(@pxref{Referencing Labels}).@refill

@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}.@refill
@end deffn

@deffn Keymap reftex-select-bib-map
The keymap which is active in the citation-key selection process
(@pxref{Creating Citations}).@refill

document.@refill
@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

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

display.  This feature can be turned on and off from the menu
(Ref->Options).@refill
@end defopt

@defopt reftex-idle-time
Time (secs) Emacs has to be idle before automatic crossref display
or toc recentering is done.@refill
@end defopt

@defopt reftex-cite-view-format
Citation format used to display citation info in the message area.  See

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 legal extensions for this file type.}

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

@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.34}
@itemize @bullet
@item

@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.42}

Reading a parse file now checks consistency.
@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

@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.@refill
@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.@refill
@item
The variables @code{reftex-index-macros} and
@code{reftex-index-default-macro} have changed their syntax slightly.

The variable @code{reftex-section-levels} no longer contains the
default stuff which has been moved to a constant.@refill
@item
Environments like theorems can be placed into the TOC by putting
entries for @samp{"begin@{theorem@}"} in
@code{reftex-setion-levels}.@refill
@end itemize
@noindent @b{Version 4.10}
@itemize @bullet
@item
Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict

Improved interaction with Emacs LaTeX mode.
@end itemize
@end ignore
@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