[AUCTeX-diffs] Changes to reftex/doc/reftex.texi,v

[Ralf Angeli]

CVSROOT:        /sources/auctex
Module name:    reftex
Changes by:     Ralf Angeli <angeli>    08/03/02 14:35:43

Index: reftex.texi
===================================================================
RCS file: /sources/auctex/reftex/doc/reftex.texi,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -b -r1.55 -r1.56
--- reftex.texi 17 Feb 2008 17:19:21 -0000      1.55
+++ reftex.texi 2 Mar 2008 14:35:43 -0000       1.56
@@ -24,7 +24,7 @@
 for LaTeX documents with Emacs.
 
 Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-2005, 2006, 2007  Free Software Foundation, Inc.
+2005, 2006, 2007, 2008 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -134,9 +134,8 @@
 * 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.
+* Reference Styles::                 Macros to be used instead of \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
 
@@ -669,7 +668,7 @@
 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
+a common label category.  For example labels in both @code{equation} and
 @code{eqnarray} environments record the value of the same counter -- the
 equation counter.
 
@@ -679,9 +678,8 @@
 * 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.
+* Reference Styles::                 Macros to be used instead of \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
@@ -765,19 +763,19 @@
 @RefTeX{} 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
+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 @RefTeX{}.  Press @kbd{C-c
-)} in order to reference a label (reftex-reference).  This will start a
-selection process and finally insert the complete @address@hidden@}}
-into the buffer.
+)} in order to reference a label (@code{reftex-reference}).  This will
+start a selection process and finally insert the complete
address@hidden@address@hidden into the buffer.
 
 First, @RefTeX{} 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 )}, @RefTeX{} knows
+write @samp{As shown in eq.} and then press @kbd{C-c )}, @RefTeX{} 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.
 
@@ -790,7 +788,7 @@
 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
+In order to reference a label, move the 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).
@@ -841,7 +839,7 @@
 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
+in files already visited is shown.  @RefTeX{} will not visit a file
 just for follow mode.  See, however, the variable
 @code{reftex-revisit-to-follow}.
 
@@ -858,8 +856,8 @@
 @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)}.
+would.  See also variable @code{reftex-highlight-selection},
address@hidden (Misc)}.
 
 @vindex reftex-multiref-punctuation
 @item m - + ,
@@ -893,26 +891,26 @@
 yet exist in the document.
 
 @item v
address@hidden @code{varioref}, LaTeX package
address@hidden @code{\vref}
address@hidden LaTeX packages, @code{varioref}
-Toggle between @code{\ref} and @code{\vref} macro for references.  The
address@hidden macro is defined in the @code{varioref} @LaTeX{} package.
-With this key you can force @RefTeX{} 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.
address@hidden reftex-ref-style-alist
address@hidden reftex-ref-style-active-list
+Cycle forward through reference macros defined by
address@hidden and activated through
address@hidden  The selected macro is displayed by
+the @samp{S<>} indicator in the mode line of the selection buffer.  This
+mechanism comes in handy if you are using @LaTeX{} packages like
address@hidden or @code{fancyref} and want to use the special
+referencing macros they provide (e.g. @code{\vref} or @code{\fref})
+instead of @code{\ref}.
 
 @item V
address@hidden @code{fancyref}, LaTeX package
address@hidden @code{\fref}
address@hidden @code{\Fref}
address@hidden LaTeX packages, @code{fancyref}
-Cycle between @code{\ref}, @code{\fref} and @code{\Fref}.  The
address@hidden and @code{\Fref} macros are defined in the @code{fancyref}
address@hidden package.  With this key you can force @RefTeX{} to insert a
address@hidden 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.
+Cycle backward through reference macros defined by
address@hidden and activated through
address@hidden
+
address@hidden p
+Toggle between @code{\ref}-style and @code{\pageref}-style referencing
+macros.  This affects the macros available for cycling through with the
address@hidden and @key{V} commands.
 
 @tablesubheading{Exiting}
 
@@ -936,7 +934,7 @@
 @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.
+to @var{arg}.  Chapters are level 1, sections are level 2.
 
 @item #
 Toggle the display of a label counter in the selection buffer.
@@ -1196,7 +1194,7 @@
 @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
+from the word before point when creating a reference.  For example if you
 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
 @RefTeX{} will know that you are looking for a theorem label and
 restrict the menu to only these labels without even asking.
@@ -1280,7 +1278,7 @@
 @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
+indicates that the context of the label definition should be the first
 argument of the macro.
 
 Here is again how this would look in the customization buffer:
@@ -1322,7 +1320,7 @@
 address@hidden@address@hidden address@hidden@address@hidden@address@hidden
 @end example
 
-Now we need to tell @RefTeX{} that the 4th argument of the
+Now we need to tell @RefTeX{} that the fourth argument of the
 @code{\myfig} macro @emph{is itself} a figure label, and where to find
 the context.
 
@@ -1336,8 +1334,8 @@
 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.
+The @samp{3} for the context method means to grab the third 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
@@ -1390,7 +1388,7 @@
 
 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 address@hidden stuff, you might
+referencing the label.  When working with the address@hidden, you might
 prefer @code{\eqref} for doing equation references.  Here is how to
 do this:
 
@@ -1406,7 +1404,7 @@
 @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{},
+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
@@ -1528,7 +1526,7 @@
     (detect-linguex ?x "ex:" "address@hidden@}" nil ("Example" "Ex."))))
 @end lisp
 
address@hidden Reference Info, xr (LaTeX package), Defining Label Environments, 
Labels and References
address@hidden Reference Info, Reference Styles, Defining Label Environments, 
Labels and References
 @section Reference Info
 @findex reftex-view-crossref
 @findex reftex-mouse-view-crossref
@@ -1550,7 +1548,83 @@
 @code{\label} macro.  @xref{Viewing Cross-References}, for more
 information.
 
address@hidden xr (LaTeX package), varioref (LaTeX package), Reference Info, 
Labels and References
address@hidden Reference Styles, xr (LaTeX package), Reference Info, Labels and 
References
address@hidden Reference Styles
+
+In case you defined your own macros for referencing or you are using
address@hidden packages providing specialized macros to be used instead of
address@hidden, @RefTeX{} provides ways for selecting and inserting them in
+a convenient way.
+
address@hidden comes equipped with a set of so-called reference styles where
+each relates to one or more reference macros.  The styles besides the
+Default option which relates to @code{\ref} and @code{\pageref} are
+Varioref for the @code{varioref} @LaTeX{} package (@code{\vref},
address@hidden, @code{\Ref}, @code{\vpageref}), Fancyref for the
address@hidden package (@code{\fref}, @code{\Fref}) and Hyperref for
+the @code{hyperref} package (@code{\autoref}, @code{\autopageref}.
+
address@hidden reftex-ref-style-active-list
+A style can be toggled by selecting the respective entry in the
address@hidden Style} menu.  Changes made through the menu will only
+last for the Emacs session.  For configuring a preference permanently
+the variable @code{reftex-ref-style-active-list} should be customized.
+This variable specifies the list of active styles.  Of course it can
+also be set as a file variable if the preference should be set for a
+specific file.
+
address@hidden reftex-ref-style-alist
+In case the built-in styles do not suffice, you can add additional
+macros and styles can to the variable @code{reftex-ref-style-alist}.
+Those do not necessarily have to be related to a certain @LaTeX{}
+package but can follow an arbitrary grouping rule.  For example you
+could define a Personal style for your personal referencing macros.
+
+Once a style is active the macros it relates to are available in the
+buffer for selecting a label for reference.  Type @key{v} in order to
+cycle forward through the list of available macros or @key{V} to cycle
+backward.  The mode line of the selection buffer shows the macro
+currently selected.
+
+Per default these commands will cycle through @code{\ref}-style macros
+for referencing sections, figures, eqations, etc.  By typing @key{p} you
+can switch to the @code{\pageref}-style macros like for referencing
+pages.  Typing @key{p} again will select @code{\ref}-style macros again.
+
+In case you are not satisfied with the order of macros when cycling
+through them you should adapt the order of entries in the variable
address@hidden to fit your liking.
+
+For each entry in @code{reftex-ref-style-alist} a function with the name
address@hidden<package>-<macro>} (e.g. @code{reftex-varioref-vref}) will
+be created automatically by @RefTeX{}.  These functions can be used
+instead of @kbd{C-c )} and provide an alternative way of having your
+favorite referencing macro preselected and if cycling through the macros
+seems inconvenient to address@hidden could e.g. bind
address@hidden to @kbd{C-c v} and
address@hidden to @kbd{C-c f}.}
+
address@hidden @code{varioref}, LaTeX package
address@hidden LaTeX packages, @code{varioref}
address@hidden @code{fancyref}, LaTeX package
address@hidden LaTeX packages, @code{fancyref}
address@hidden reftex-vref-is-default (deprecated)
address@hidden reftex-fref-is-default (deprecated)
+In former versions of @RefTeX{} only support for @code{varioref} and
address@hidden was included.  @code{varioref} is a @LaTeX{} package to
+create cross-references with page information.  @code{fancyref} is a
+package where a macro call like @address@hidden@var{fig:address@hidden
+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 @RefTeX{} does automatically.  For each of
+these packages a variable could be configured to make its macros to take
+precedence over @code{\ref}.  Those were @code{reftex-vref-is-default}
+and @code{reftex-fref-is-default} respectively.  While still working,
+these variables are deprecated now.  Instead of setting them, the
+variable @code{reftex-ref-style-active-list} should be adapted now.
+
address@hidden xr (LaTeX package), , Reference Styles, Labels and References
 @section @code{xr}: Cross-Document References
 @cindex @code{xr}, LaTeX package
 @cindex LaTeX packages, @code{xr}
@@ -1585,46 +1659,6 @@
 information and the use of multiple selection buffers can mean a large
 speed-up (@pxref{Optimizations}).
 
address@hidden varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX 
package), Labels and References
address@hidden @code{varioref}: Variable Page References
address@hidden @code{varioref}, LaTeX package
address@hidden @code{\vref}
address@hidden LaTeX packages, @code{varioref}
address@hidden reftex-vref-is-default
address@hidden 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
address@hidden@footnote{bind it to @kbd{C-c v}.}.
-Or use @AUCTeX{} to create your macros (@pxref{AUCTeX}).
-
address@hidden fancyref (LaTeX package), , varioref (LaTeX package), Labels and 
References
address@hidden @code{fancyref}: Fancy Cross References
address@hidden @code{fancyref}, LaTeX package
address@hidden @code{\fref}
address@hidden @code{\Fref}
address@hidden LaTeX packages, @code{fancyref}
address@hidden reftex-fref-is-default
address@hidden is a @LaTeX{} package where a macro call like
address@hidden@address@hidden:address@hidden creates not only the number of
-the referenced counter but also the complete text around it, like
address@hidden 3 on the preceding page}.  In order to make it work you
-need to use label prefixes like @samp{fig:} consistently - something
address@hidden 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 @address@hidden 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
@@ -4238,35 +4272,31 @@
 @code{reftex-reference}.
 @end defopt
 
address@hidden reftex-vref-is-default
address@hidden 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.
address@hidden defopt
-
address@hidden reftex-fref-is-default
address@hidden 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.
address@hidden reftex-ref-style-alist
+Alist of reference styles.  Each element is a list of the string to be
+inserted as reference macro, the style name, the @LaTeX{} package
+providing the macro (the package name as a string or t for no specific
+package) and the reference type (the symbol @code{num} for a number
+reference or @code{page} for a page reference macro).
address@hidden defopt
+
address@hidden reftex-ref-style-active-list
+List of active reference styles.  The order is significant and controls
+the order in which macros can be cycled in the buffer for selecting a
+label.  The entries in the list have to match the respective reference
+style names used in the variable @code{reftex-ref-style-alist}.
 @end defopt
 
 @deffn Hook reftex-format-ref-function
 If address@hidden, 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
address@hidden and the @var{default-format} (usually @address@hidden@}}).
-It should return the string to insert into the buffer.
+special commands to insert e.g. @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 three arguments, the
address@hidden, the @var{default format} which normally is
address@hidden@address@hidden and the @var{reference style}.  The function 
should
+return the string to insert into the buffer.
 @end deffn
 
 @defopt reftex-level-indent