Update to reftex 4.9

man/reftex.texi

@@ -9,9 +9,9 @@
 @synindex ky cp
 @syncodeindex vr cp
 @syncodeindex fn cp
-@set VERSION 4.6
-@set EDITION 4.6
-@set DATE September 1999
+@set VERSION 4.9
+@set EDITION 4.9
+@set DATE December 1999
 @set AUTHOR Carsten Dominik
 @set AUTHOR-EMAIL dominik@@strw.leidenuniv.nl
 @set MAINTAINER Carsten Dominik
@@ -72,7 +72,7 @@ translation approved by the Free Software Foundation.
 
 @author by Carsten Dominik
 @page
-Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1997, 1998, 1999 Free Software Foundation, Inc.
 
 @sp 2
 This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
@@ -178,11 +178,18 @@ Citations
 
 Index Support
 
-* Creating Index Entries::
-* Displaying and Editing the Index:: 
+* 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
@@ -356,22 +363,24 @@ are supported.@refill
 @itemize @bullet
 @item
 @b{Creating Index Entries}@*
-Type @kbd{C-c /} (@code{reftex-index-selection-or-word}) to index the
-current selection or the word at the cursor with the default macro (see
-the variable @code{reftex-index-default-macro}).@*
-Type @kbd{C-c <} (@code{reftex-index}) to insert a general index macro.
-@b{Ref@TeX{}} will offer a list of available macros and provide
-completion for the index tag (used to identify one of multiple indices)
-and for the entry itself (useful with subentries).
-
-@refill
-
-@item
-@b{Displaying 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.  The index can be restricted
-to those entries defined in a single document section or in a user
-defined region.@refill
+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.@refill
+
+@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.@refill
+
+@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.@refill
 @end itemize
 
 @page
@@ -381,10 +390,10 @@ When point is on the @var{key} argument of a cross--referencing macro
 @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.@refill @* 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.@refill
+files.@refill @*
+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.@refill
 
 @item
 @b{Multifile Documents}@*
@@ -440,7 +449,8 @@ an AUCTeX style file to support them with both AUCTeX and
 @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.  The first part of the manual explains in
+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
@@ -541,6 +551,16 @@ 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}.@refill
+
 @item F
 @vindex reftex-toc-include-file-boundaries
 Toggle the display of the file borders of a multifile document in the
@@ -602,12 +622,16 @@ keymap @code{reftex-toc-map} may be used.@refill
 @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}.
+@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
@@ -882,7 +906,9 @@ 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.@refill
+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
@@ -1095,8 +1121,8 @@ library.  With Lisp it would look like this
 
 @lisp
 (setq reftex-label-alist
-   '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax."))
-     ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "theor." "th."))))
+   '(("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
@@ -1130,11 +1156,19 @@ For more complex ways of getting context, see the variable
 Environments)}).@refill
 @end itemize
 
-The strings at the end of each entry are used to guess the correct label
-type from the word before point when creating a reference.  E.g. if you
+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.@refill
+@b{Ref@TeX{}} will know that you are looking for a theorem label and
+restrict the menu to only these labels without even asking.@refill
+
+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.@refill
 
 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
@@ -1152,6 +1186,7 @@ Reftex Label Alist: [Hide]
               [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
@@ -1163,6 +1198,7 @@ Reftex Label Alist: [Hide]
               [INS] [DEL] String: theor.
               [INS] [DEL] String: th.
               [INS]
+            [X] Make TOC entry    : [Value Menu] Level: -3
 @end example
 
 @vindex reftex-insert-label-flags
@@ -1220,6 +1256,7 @@ Reftex Label Alist: [Hide]
             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
@@ -1279,6 +1316,7 @@ Again, here the configuration in the customization buffer:
             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
@@ -1443,8 +1481,8 @@ the entries described above:
 
 @lisp
 (setq reftex-label-alist
-  '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax."))
-    ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "theor." "th."))
+  '(("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)
@@ -1801,12 +1839,9 @@ the @kbd{C-c [} binding to the mail buffer.  It also provides a local
 binding for @code{reftex-cite-format}.@refill
 
 @lisp
-(add-hook
- 'mail-setup-hook
- (lambda ()
-   (define-key mail-mode-map "\C-c["
-     (lambda ()
-       (interactive)
+(add-hook 'mail-setup-hook
+          (lambda () (define-key mail-mode-map "\C-c["
+                       (lambda () (interactive)
                          (require 'reftex)
                          (let ((reftex-cite-format 'locally))
                            (reftex-citation))))))
@@ -1828,44 +1863,63 @@ 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}.@refill
 
-Indexing is a lot of work and must follow strict conventions, so that
-the same word looks the same in all index entries referencing it, and in
-order to avoid spurious multiple entries.  Therefore, the author of a
-document will most likely define special macros to make this easier.  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}).@refill
+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}).@refill
+
+@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.@refill
+@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@refill
+
+@lisp
+(setq reftex-index-macros '(multind))     @r{or}
+(setq reftex-index-macros '(index))
+@end lisp
 
 @menu
-* Creating Index Entries::
-* Displaying and Editing the Index:: 
+* 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, Displaying and Editing the Index, , Index Support
+@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
-
-First 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
-
 @kindex C-c /
 @findex reftex-index-selection-or-word
 
@@ -1891,20 +1945,235 @@ 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.@refill
 
-@findex reftex-index-globally
+@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:@refill
 
-There is also a command @code{reftex-index-globally}@footnote{This
-function is still experimentally and may change or go away.} which
-copies an index entry near point to other occurrences of the same word
-in the document.  @b{Ref@TeX{}} assumes that the word you want to index
-is in direct contact with the index macro, e.g.
-@samp{\index@{@var{word}@}@var{word}} or
-@samp{@var{word}\index@{@var{word}@}}.  If there is no such word, it
-uses the key argument of the index macro.  After making you confirm the
-precise search and replace strings, a query-replace over the entire
-document will be launched.
+@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
 
-@node Displaying and Editing the Index, Builtin Index Macros, Creating Index Entries, Index Support
+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.@refill
+
+@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:@refill
+
+@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.@refill
+
+@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}).@refill
+
+@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.@refill
+
+@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.@refill
+
+@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.@refill
+
+@b{Ref@TeX{}} will start at the first phrase line and search the phrase