Referencing Labels
==================

   Referencing Labels is really at the heart of RefTeX.  Press `C-c )'
in order to reference a label (reftex-reference).  This will start a
selection process and finally insert the complete `\ref{label}' 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
`As shown in eq.' and the press `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.

   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 <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 <RET>.
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 `?'.

`0-9,-'
     Prefix argument.

`b'
     Jump back to the position where you last left the selection buffer.
     Normally this should get you back to the last referenced label.

`c'
     Toggle the display of the one-line label definition context in the
     selection buffer.

`f'
     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 <SPC> after each cursor motion.  Note that
     only context in files already visited is shown.  RefTeX will not
     visit a file just for follow mode.  See, however, the variable
     `reftex-revisit-to-follow'.

`g'
     Update the menu.  This will rebuilt the menu from the internal
     label list, but not reparse the document (see `r').

`i'
     Toggle the display of the file borders of a multifile document in
     the selection buffer.

`l'
     Use the last referenced label again.  This is equivalent to moving
     to that label and pressing <RET>.

`n'
     Go to next label.

`p'
     Go to previous label.

`q'
     Exit the selection process without inserting any reference into the
     buffer.

`r'
     Reparse the document to update the information on all labels and
     rebuild the menu.  If the variable `reftex-enable-partial-scans' is
     non-`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).

`R'
     Reparse the *entire* document.

`s'
     Switch the label category.  After prompting for another label
     category, a menu for that category will be shown.

`t'
     Toggle the display of the table of contents in the selection
     buffer.

`v'
     Toggle between `\ref' and `\vref' macro for references.  The
     `\vref' macro is defined in the `varioref' LaTeX package.  With
     this key you can force RefTeX to insert a `\vref' macro.  The
     current state of this flag is displayed in the mode line of the
     selection buffer.

`x'
     Reference a label from an external document.  With the LaTeX
     package `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 (see xr: xr
     (LaTeX package).).

`.'
     Show insertion point in another window.  This is the point from
     where you called `reftex-reference'.

`<TAB>'
     Enter a label with completion.  This may also be a label which
     does not yet exist in the document.

`<SPC>'
     Show the surroundings of the definition of the current label in
     another window.  See also the `f' key.

`<RET>'
     Insert a reference to the label at point into the buffer from
     which the selection process was started.

`mouse-2'
     Clicking with mouse button 2 on a label will accept it like <RET>
     would. See also variable `reftex-highlight-selection', *Note
     Options (Misc)::.

`#'
     Toggle the display of a label counter in the selection buffer.

`%'
     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, RefTeX can
     still display and reference these labels.

`?'
     Show a summary of the available keys.

`C-c C-n'
     Goto next section heading (like outline mode).

`C-c C-p'
     Goto previous section heading (like outline mode).

   Several of these keys toggle certain settings.  The default value for
these flags can be preset by configuring the variable
`reftex-label-menu-flags' (see Options (Referencing Labels).).  In
order to define additional commands for the selection process, the
keymap `reftex-select-label-map' may be used.