reftex.texi 219 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1 2
\input texinfo  @c -*-texinfo-*-
@c %**start of header
Carsten Dominik's avatar
Carsten Dominik committed
3
@setfilename ../info/reftex
Dave Love's avatar
#  
Dave Love committed
4 5 6 7
@settitle RefTeX User Manual
@synindex ky cp
@syncodeindex vr cp
@syncodeindex fn cp
Carsten Dominik's avatar
Carsten Dominik committed
8 9

@c Version and Contact Info
10 11 12
@set VERSION 4.31
@set EDITION 4.31
@set DATE February 2006
13 14 15
@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}
16 17 18 19
@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})
20
@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}
Dave Love's avatar
#  
Dave Love committed
21 22
@c %**end of header

23
@copying
Dave Love's avatar
#  
Dave Love committed
24
This file documents @b{Ref@TeX{}}, a package to do labels, references,
Karl Berry's avatar
Karl Berry committed
25
citations and indices for LaTeX documents with Emacs.
Dave Love's avatar
#  
Dave Love committed
26 27

This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
Carsten Dominik's avatar
Carsten Dominik committed
28
@b{Ref@TeX{}} @value{VERSION}
Dave Love's avatar
#  
Dave Love committed
29

30 31
Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
2005, 2006, 2007  Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
32

33
@quotation
34
Permission is granted to copy, distribute and/or modify this document
35
under the terms of the GNU Free Documentation License, Version 1.2 or
36 37 38 39 40 41 42 43 44 45 46 47 48 49
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.
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
@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\
Dave Love's avatar
#  
Dave Love committed
66
@end ifinfo
67 68 69 70
@ifnotinfo
@item @b{\text\}
@end ifnotinfo
@end macro
Dave Love's avatar
#  
Dave Love committed
71 72 73 74 75 76 77 78

@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
79 80
@vskip 0pt plus 1filll
@insertcopying
Dave Love's avatar
#  
Dave Love committed
81 82
@end titlepage

Carsten Dominik's avatar
Carsten Dominik committed
83
@ifnottex
Dave Love's avatar
#  
Dave Love committed
84 85 86
@node Top,,,(dir)

@b{Ref@TeX{}} is a package for managing Labels, References,
Carsten Dominik's avatar
Carsten Dominik committed
87
Citations and index entries with GNU Emacs.
Dave Love's avatar
#  
Dave Love committed
88 89 90 91 92

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
Carsten Dominik's avatar
Carsten Dominik committed
93
needed.
Dave Love's avatar
#  
Dave Love committed
94 95 96 97 98 99 100 101 102 103 104

@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.
Richard M. Stallman's avatar
Richard M. Stallman committed
105
* Key Bindings::                      The default key bindings.
Dave Love's avatar
#  
Dave Love committed
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
* 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.

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.
130

Dave Love's avatar
#  
Dave Love committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
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.
Carsten Dominik's avatar
Carsten Dominik committed
159
* BibTeX Database Subsets::          Extract parts of a big database. 
Dave Love's avatar
#  
Dave Love committed
160 161 162

Index Support

Carsten Dominik's avatar
Carsten Dominik committed
163 164 165
* 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.
Dave Love's avatar
#  
Dave Love committed
166 167 168
* Builtin Index Macros::             The index macros RefTeX knows about.
* Defining Index Macros::                ... and macros it  doesn't.

Carsten Dominik's avatar
Carsten Dominik committed
169 170 171 172 173 174
The Index Phrases File

* Collecting Phrases::               Collecting from document or external.
* Consistency Checks::               Check for duplicates etc.
* Global Indexing::                  The interactive indexing process.

Dave Love's avatar
#  
Dave Love committed
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
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

Carsten Dominik's avatar
Carsten Dominik committed
198
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
199 200 201 202 203 204 205 206 207 208 209 210

@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
Carsten Dominik's avatar
Carsten Dominik committed
211
document and to move around in this structure quickly.
Dave Love's avatar
#  
Dave Love committed
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231

@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

Carsten Dominik's avatar
Carsten Dominik committed
232 233 234 235 236
@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.
Dave Love's avatar
#  
Dave Love committed
237 238 239

Users of earlier Emacs distributions (including Emacs 19) can get a copy
of the @b{Ref@TeX{}} distribution from the maintainers web-page.
Carsten Dominik's avatar
Carsten Dominik committed
240
@xref{Imprint}, for more information.
Dave Love's avatar
#  
Dave Love committed
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266

@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
Carsten Dominik's avatar
Carsten Dominik committed
267
files, add the following lines to your @file{.emacs} file:
Dave Love's avatar
#  
Dave Love committed
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287

@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
Carsten Dominik's avatar
Carsten Dominik committed
288
help.
Dave Love's avatar
#  
Dave Love committed
289 290 291 292 293 294 295

@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
Carsten Dominik's avatar
Carsten Dominik committed
296
@code{reftex-label-alist}).
Dave Love's avatar
#  
Dave Love committed
297 298 299

@itemize @bullet
@item
300
@b{Creating Labels}@*
Dave Love's avatar
#  
Dave Love committed
301 302 303 304 305 306 307
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
308
@item
Dave Love's avatar
#  
Dave Love committed
309
insert a simple label made of a prefix and a number (all other
Carsten Dominik's avatar
Carsten Dominik committed
310
environments)
Dave Love's avatar
#  
Dave Love committed
311 312 313
@end itemize
@noindent
Which labels are created how is configurable with the variable
Carsten Dominik's avatar
Carsten Dominik committed
314
@code{reftex-insert-label-flags}.
Dave Love's avatar
#  
Dave Love committed
315 316 317 318 319 320

@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
Carsten Dominik's avatar
Carsten Dominik committed
321
into the original buffer.
Dave Love's avatar
#  
Dave Love committed
322 323 324 325 326 327 328 329 330 331
@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
Carsten Dominik's avatar
Carsten Dominik committed
332
different macros).
Dave Love's avatar
#  
Dave Love committed
333 334 335 336 337 338 339 340

@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
Carsten Dominik's avatar
Carsten Dominik committed
341
are supported.
Dave Love's avatar
#  
Dave Love committed
342 343 344 345

@itemize @bullet
@item
@b{Creating Index Entries}@*
Carsten Dominik's avatar
Carsten Dominik committed
346 347 348 349
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
Carsten Dominik's avatar
Carsten Dominik committed
350
and enter the arguments with completion.
Carsten Dominik's avatar
Carsten Dominik committed
351 352 353 354 355 356

@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
Carsten Dominik's avatar
Carsten Dominik committed
357
phrases and let you interactively index the matches.
Carsten Dominik's avatar
Carsten Dominik committed
358 359 360 361 362

@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
Carsten Dominik's avatar
Carsten Dominik committed
363
all entries.
Dave Love's avatar
#  
Dave Love committed
364 365 366 367 368 369 370 371 372
@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
Carsten Dominik's avatar
Carsten Dominik committed
373
files. @*
Carsten Dominik's avatar
Carsten Dominik committed
374 375
When the enclosing macro is @code{\cite} or @code{\ref} and no other
message occupies the echo area, information about the citation or label
Carsten Dominik's avatar
Carsten Dominik committed
376
will automatically be displayed in the echo area.
Dave Love's avatar
#  
Dave Love committed
377 378 379 380 381 382 383

@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
Carsten Dominik's avatar
Carsten Dominik committed
384
(@file{xr.sty}).
Dave Love's avatar
#  
Dave Love committed
385 386 387 388 389 390 391 392

@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
Carsten Dominik's avatar
Carsten Dominik committed
393
buffer, or the index buffer.
Dave Love's avatar
#  
Dave Love committed
394 395 396 397 398 399

@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
Carsten Dominik's avatar
Carsten Dominik committed
400
additional customizations will be necessary.
Dave Love's avatar
#  
Dave Love committed
401 402

@item
Carsten Dominik's avatar
Carsten Dominik committed
403 404
@b{Useful Settings}@*
To integrate RefTeX with AUCTeX, use
Dave Love's avatar
#  
Dave Love committed
405 406 407 408 409
@lisp
(setq reftex-plug-into-AUCTeX t)
@end lisp

To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
Carsten Dominik's avatar
Carsten Dominik committed
410
customize the variables
Dave Love's avatar
#  
Dave Love committed
411 412 413 414 415 416 417 418 419
@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
Carsten Dominik's avatar
Carsten Dominik committed
420
@b{Ref@TeX{}}.
Dave Love's avatar
#  
Dave Love committed
421 422 423 424

@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
Carsten Dominik's avatar
Carsten Dominik committed
425 426
the manual if you get stuck, of if you are curious what else might be
available.  The first part of the manual explains in
Dave Love's avatar
#  
Dave Love committed
427
a tutorial way how to use and customize @b{Ref@TeX{}}.  The second
428
part is a command and variable reference.
Dave Love's avatar
#  
Dave Love committed
429 430 431 432 433
@end enumerate

@node Table of Contents, Labels and References, Introduction, Top
@chapter Table of Contents
@cindex @file{*toc*} buffer
Carsten Dominik's avatar
Carsten Dominik committed
434
@cindex Structure editing
Dave Love's avatar
#  
Dave Love committed
435 436 437 438 439 440 441 442
@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
Carsten Dominik's avatar
Carsten Dominik committed
443
well.
Dave Love's avatar
#  
Dave Love committed
444 445 446

With the cursor in any of the lines denoting a location in the
document, simple key strokes will display the corresponding part in
Carsten Dominik's avatar
Carsten Dominik committed
447
another window, jump to that location, or perform other actions.
Dave Love's avatar
#  
Dave Love committed
448 449 450 451

@kindex ?
Here is a list of special commands in the @file{*toc*} buffer.  A
summary of this information is always available by pressing
Carsten Dominik's avatar
Carsten Dominik committed
452
@kbd{?}.
Dave Love's avatar
#  
Dave Love committed
453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471

@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
Carsten Dominik's avatar
Carsten Dominik committed
472
separate section headings.
Dave Love's avatar
#  
Dave Love committed
473 474 475 476

@item C-c C-p
Goto previous section heading.

Carsten Dominik's avatar
Carsten Dominik committed
477 478
@item N z
Jump to section N, using the prefix arg.  For example, @kbd{3 z} jumps
Carsten Dominik's avatar
Carsten Dominik committed
479
to section 3.
Carsten Dominik's avatar
Carsten Dominik committed
480

Dave Love's avatar
#  
Dave Love committed
481 482 483
@tablesubheading{Access to document locations}
@item @key{SPC}
Show the corresponding location in another window.  This command does
Carsten Dominik's avatar
Carsten Dominik committed
484
@emph{not} select that other window.
Dave Love's avatar
#  
Dave Love committed
485 486 487 488 489 490 491

@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
Carsten Dominik's avatar
Carsten Dominik committed
492
called.
Dave Love's avatar
#  
Dave Love committed
493

Carsten Dominik's avatar
Carsten Dominik committed
494
@item mouse-2
Dave Love's avatar
#  
Dave Love committed
495 496 497
@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
Carsten Dominik's avatar
Carsten Dominik committed
498
(Fontification)}.
Dave Love's avatar
#  
Dave Love committed
499 500 501 502 503 504 505 506 507 508 509

@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
Carsten Dominik's avatar
Carsten Dominik committed
510
@code{reftex-revisit-to-follow}.
Dave Love's avatar
#  
Dave Love committed
511 512 513 514 515

@item .
Show calling point in another window.  This is the point from where
@code{reftex-toc} was last called.

Carsten Dominik's avatar
Carsten Dominik committed
516
@page
Carsten Dominik's avatar
Carsten Dominik committed
517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542
@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.

Dave Love's avatar
#  
Dave Love committed
543 544 545
@tablesubheading{Exiting}
@item q
Hide the @file{*toc*} buffer, return to the position where
Carsten Dominik's avatar
Carsten Dominik committed
546
@code{reftex-toc} was last called.
Dave Love's avatar
#  
Dave Love committed
547 548 549

@item k
Kill the @file{*toc*} buffer, return to the position where
Carsten Dominik's avatar
Carsten Dominik committed
550
@code{reftex-toc} was last called.
Dave Love's avatar
#  
Dave Love committed
551 552 553

@item C-c >
Switch to the @file{*Index*} buffer of this document.  With prefix
554
@samp{2}, restrict the index to the section at point in the @file{*toc*}
Dave Love's avatar
#  
Dave Love committed
555 556 557 558
buffer.

@tablesubheading{Controlling what gets displayed}

Carsten Dominik's avatar
Carsten Dominik committed
559 560 561 562 563 564 565 566
@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
Carsten Dominik's avatar
Carsten Dominik committed
567
@code{reftex-toc-max-level}.
Carsten Dominik's avatar
Carsten Dominik committed
568

Dave Love's avatar
#  
Dave Love committed
569 570 571 572
@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
Carsten Dominik's avatar
Carsten Dominik committed
573
variable @code{reftex-toc-include-file-boundaries}.
Dave Love's avatar
#  
Dave Love committed
574 575 576 577 578 579 580 581

@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<>}
Carsten Dominik's avatar
Carsten Dominik committed
582
indicator shows which labels are included.
Dave Love's avatar
#  
Dave Love committed
583 584 585 586 587 588 589

@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
590
only entries in the selected index in the @file{*toc*} buffer.  The mode
Carsten Dominik's avatar
Carsten Dominik committed
591
line @samp{I<>} indicator shows which index is used.
Dave Love's avatar
#  
Dave Love committed
592 593 594 595 596

@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
Carsten Dominik's avatar
Carsten Dominik committed
597
@code{reftex-toc-include-context}.
Dave Love's avatar
#  
Dave Love committed
598 599 600 601 602

@tablesubheading{Updating the buffer}

@item g
Rebuild the @file{*toc*} buffer.  This does @emph{not} rescan the
Carsten Dominik's avatar
Carsten Dominik committed
603
document.
Dave Love's avatar
#  
Dave Love committed
604 605 606 607

@item r
@vindex reftex-enable-partial-scans
Reparse the LaTeX document and rebuild the @file{*toc*} buffer.  When
608
@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
Carsten Dominik's avatar
Carsten Dominik committed
609
location is defined in, not the entire document.
Dave Love's avatar
#  
Dave Love committed
610 611 612

@item C-u r
Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
Carsten Dominik's avatar
Carsten Dominik committed
613
buffer.
Dave Love's avatar
#  
Dave Love committed
614 615 616 617 618

@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
Carsten Dominik's avatar
Carsten Dominik committed
619 620 621 622 623 624 625 626 627 628
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).
Dave Love's avatar
#  
Dave Love committed
629

Carsten Dominik's avatar
Carsten Dominik committed
630 631 632
@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*}
Carsten Dominik's avatar
Carsten Dominik committed
633 634 635
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}.
Carsten Dominik's avatar
Carsten Dominik committed
636

Dave Love's avatar
#  
Dave Love committed
637 638 639 640
@end table

@vindex reftex-toc-map
In order to define additional commands for the @file{*toc*} buffer, the
Carsten Dominik's avatar
Carsten Dominik committed
641
keymap @code{reftex-toc-map} may be used.
Dave Love's avatar
#  
Dave Love committed
642

Carsten Dominik's avatar
Carsten Dominik committed
643 644 645 646 647 648 649 650 651 652 653 654
@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
Carsten Dominik's avatar
Carsten Dominik committed
655 656 657 658 659 660
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
Carsten Dominik's avatar
Carsten Dominik committed
661 662 663 664 665
@lisp
(setq reftex-auto-recenter-toc t)
@end lisp


Dave Love's avatar
#  
Dave Love committed
666 667 668
@cindex Sectioning commands
@cindex KOMA-Script, LaTeX classes
@cindex LaTeX classes, KOMA-Script
Carsten Dominik's avatar
Carsten Dominik committed
669
@cindex TOC entries for environments
Dave Love's avatar
#  
Dave Love committed
670 671 672 673 674
@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
Carsten Dominik's avatar
Carsten Dominik committed
675 676 677 678
@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.
Dave Love's avatar
#  
Dave Love committed
679 680 681 682 683 684 685 686 687 688 689 690 691 692

@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
Carsten Dominik's avatar
Carsten Dominik committed
693
counter.
Dave Love's avatar
#  
Dave Love committed
694 695 696 697

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
Carsten Dominik's avatar
Carsten Dominik committed
698
records the figure counter, not the section counter.
Dave Love's avatar
#  
Dave Love committed
699 700 701 702

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
Carsten Dominik's avatar
Carsten Dominik committed
703
equation counter.
Dave Love's avatar
#  
Dave Love committed
704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728

@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
Carsten Dominik's avatar
Carsten Dominik committed
729
3 different modes to create this mark.
Dave Love's avatar
#  
Dave Love committed
730 731 732 733 734 735 736 737 738 739

@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
740
invalid in labels.  @b{Ref@TeX{}} will therefore strip the accent from
Dave Love's avatar
#  
Dave Love committed
741
accented Latin-1 characters and remove everything else which is not
742
valid in labels.  This mechanism is safe, but may not be satisfactory
Dave Love's avatar
#  
Dave Love committed
743 744 745 746 747 748 749
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
Carsten Dominik's avatar
Carsten Dominik committed
750
it.
Dave Love's avatar
#  
Dave Love committed
751 752 753 754 755 756 757 758 759 760

@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
Carsten Dominik's avatar
Carsten Dominik committed
761
reference a label (@pxref{Referencing Labels}).
Dave Love's avatar
#  
Dave Love committed
762 763 764 765 766 767 768 769 770

@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
Carsten Dominik's avatar
Carsten Dominik committed
771
this label later.
Dave Love's avatar
#  
Dave Love committed
772 773 774 775 776
@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
Carsten Dominik's avatar
Carsten Dominik committed
777
Labels)}).
Dave Love's avatar
#  
Dave Love committed
778 779 780 781 782 783 784 785 786 787 788 789 790 791 792

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

Carsten Dominik's avatar
Carsten Dominik committed
793 794 795 796 797 798 799 800 801
@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}.

Dave Love's avatar
#  
Dave Love committed
802 803 804
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@}}
Carsten Dominik's avatar
Carsten Dominik committed
805
into the buffer.
Dave Love's avatar
#  
Dave Love committed
806 807 808 809 810

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
Carsten Dominik's avatar
Carsten Dominik committed
811
out what label category is needed, it will query for one.
Dave Love's avatar
#  
Dave Love committed
812 813 814 815 816 817 818 819

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
Carsten Dominik's avatar
Carsten Dominik committed
820
another window.
Dave Love's avatar
#  
Dave Love committed
821 822 823 824 825 826 827 828 829

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
Carsten Dominik's avatar
Carsten Dominik committed
830
pressing @kbd{?}.
Dave Love's avatar
#  
Dave Love committed
831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850



@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.
Carsten Dominik's avatar
Carsten Dominik committed
851
Normally this should get you back to the last referenced label.
Dave Love's avatar
#  
Dave Love committed
852 853 854 855 856 857 858

@item C-c C-n
Goto next section heading.

@item C-c C-p
Goto previous section heading.

Carsten Dominik's avatar
Carsten Dominik committed
859
@item N z
860
Jump to section N, using the prefix arg.  For example @kbd{3 z} jumps to
Carsten Dominik's avatar
Carsten Dominik committed
861
section 3.
Carsten Dominik's avatar
Carsten Dominik committed
862

Dave Love's avatar
#  
Dave Love committed
863 864 865
@tablesubheading{Displaying Context}
@item @key{SPC}
Show the surroundings of the definition of the current label in another
Carsten Dominik's avatar
Carsten Dominik committed
866
window.  See also the @kbd{f} key.
Dave Love's avatar
#  
Dave Love committed
867 868 869 870 871 872 873 874

@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
Carsten Dominik's avatar
Carsten Dominik committed
875
@code{reftex-revisit-to-follow}.
Dave Love's avatar
#  
Dave Love committed
876 877 878

@item .
Show insertion point in another window.  This is the point from where you
Carsten Dominik's avatar
Carsten Dominik committed
879
called @code{reftex-reference}.
Dave Love's avatar
#  
Dave Love committed
880 881 882 883 884

@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}
Carsten Dominik's avatar
Carsten Dominik committed
885
references all marked labels.
Dave Love's avatar
#  
Dave Love committed
886

Carsten Dominik's avatar
Carsten Dominik committed
887
@item mouse-2
Dave Love's avatar
#  
Dave Love committed
888 889 890
@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
Carsten Dominik's avatar
Carsten Dominik committed
891
(Misc)}.
Dave Love's avatar
#  
Dave Love committed
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913

@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
Carsten Dominik's avatar
Carsten Dominik committed
914
@file{saferef.sty} support multiple references in this way.
Dave Love's avatar
#  
Dave Love committed
915 916 917

@item l
Use the last referenced label(s) again.  This is equivalent to moving to
Carsten Dominik's avatar
Carsten Dominik committed
918
that label and pressing @key{RET}.
Dave Love's avatar
#  
Dave Love committed
919 920 921 922 923 924 925 926 927 928 929 930 931

@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<>}
Carsten Dominik's avatar
Carsten Dominik committed
932
indicator in the mode line of the selection buffer.
Dave Love's avatar
#  
Dave Love committed
933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949

@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
Carsten Dominik's avatar
Carsten Dominik committed
950
buffer.
Dave Love's avatar
#  
Dave Love committed
951 952 953

@tablesubheading{Controlling what gets displayed}
@vindex reftex-label-menu-flags
954
The defaults for the following flags can be configured with the variable
Dave Love's avatar
#  
Dave Love committed
955 956 957 958
@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).

@item c
Toggle the display of the one-line label definition context in the
Carsten Dominik's avatar
Carsten Dominik committed
959
selection buffer.
Dave Love's avatar
#  
Dave Love committed
960 961 962

@item F
Toggle the display of the file borders of a multifile document in the
Carsten Dominik's avatar
Carsten Dominik committed
963
selection buffer.
Dave Love's avatar
#  
Dave Love committed
964 965

@item t
Carsten Dominik's avatar
Carsten Dominik committed
966
Toggle the display of the table of contents in the selection buffer.
967
With prefix @var{arg}, change the maximum level of toc entries displayed
Carsten Dominik's avatar
Carsten Dominik committed
968
to @var{arg}.  Chapters are level 1, section are level 2.
Dave Love's avatar
#  
Dave Love committed
969 970

@item #
Carsten Dominik's avatar
Carsten Dominik committed
971
Toggle the display of a label counter in the selection buffer.
Dave Love's avatar
#  
Dave Love committed
972 973 974 975 976

@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
Carsten Dominik's avatar
Carsten Dominik committed
977
and reference these labels.
Dave Love's avatar
#  
Dave Love committed
978 979 980 981

@tablesubheading{Updating the buffer}
@item g
Update the menu.  This will rebuilt the menu from the internal label
Carsten Dominik's avatar
Carsten Dominik committed
982
list, but not reparse the document (see @kbd{r}).
Dave Love's avatar
#  
Dave Love committed
983 984 985 986 987 988 989

@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
Carsten Dominik's avatar
Carsten Dominik committed
990
point was defined).
Dave Love's avatar
#  
Dave Love committed
991 992 993 994 995 996

@item C-u r
Reparse the @emph{entire} document.

@item s
Switch the label category.  After prompting for another label category,
Carsten Dominik's avatar
Carsten Dominik committed
997
a menu for that category will be shown.
Dave Love's avatar
#  
Dave Love committed
998 999 1000 1001 1002 1003

@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
Carsten Dominik's avatar
Carsten Dominik committed
1004
package),,xr}).
Dave Love's avatar
#  
Dave Love committed
1005 1006 1007 1008 1009

@end table

@vindex reftex-select-label-map
In order to define additional commands for the selection process, the
Carsten Dominik's avatar
Carsten Dominik committed
1010
keymap @code{reftex-select-label-map} may be used.
Dave Love's avatar
#  
Dave Love committed
1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023

@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
Carsten Dominik's avatar
Carsten Dominik committed
1024
1994.}.  These are:
Dave Love's avatar
#  
Dave Love committed
1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039

@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
Carsten Dominik's avatar
Carsten Dominik committed
1040
the LaTeX core stuff)
Dave Love's avatar
#  
Dave Love committed
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054
@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}
Carsten Dominik's avatar
Carsten Dominik committed
1055
(from AMS-LaTeX's @file{amsmath.sty} package)
Dave Love's avatar
#  
Dave Love committed
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099
@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
Carsten Dominik's avatar
Carsten Dominik committed
1100
(@file{subfigure.sty})
Dave Love's avatar
#  
Dave Love committed
1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114
@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
Carsten Dominik's avatar
Carsten Dominik committed
1115
them (@pxref{Defining Label Environments}).
Dave Love's avatar
#  
Dave Love committed
1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137

@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
Carsten Dominik's avatar
Carsten Dominik committed
1138
Environments}).
Dave Love's avatar
#  
Dave Love committed
1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156

@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
Carsten Dominik's avatar
Carsten Dominik committed
1157
new environments, @code{theorem} and @code{axiom}
Dave Love's avatar
#  
Dave Love committed
1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180

@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
Carsten Dominik's avatar
Carsten Dominik committed
1181 1182
   '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
     ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "th.") -3)))
Dave Love's avatar
#  
Dave Love committed
1183 1184 1185 1186 1187 1188
@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},
Carsten Dominik's avatar
Carsten Dominik committed
1189
@code{?i}, @code{?n} are already used for standard environments.
Dave Love's avatar
#  
Dave Love committed
1190 1191 1192 1193

@noindent
The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
@samp{thr:}, respectively.  @xref{AUCTeX}, for information on how
Carsten Dominik's avatar
Carsten Dominik committed
1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
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

Dave Love's avatar
#  
Dave Love committed
1207 1208 1209

@noindent
The @samp{~\ref@{%s@}} is a format string indicating how to insert
Carsten Dominik's avatar
Carsten Dominik committed
1210
references to these labels.
Dave Love's avatar
#  
Dave Love committed
1211 1212

@noindent
Carsten Dominik's avatar
Carsten Dominik committed
1213
The next item indicates how to grab context of the label definition.
Dave Love's avatar
#  
Dave Love committed
1214 1215 1216 1217
@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
Carsten Dominik's avatar
Carsten Dominik committed
1218
@emph{not} a good choice for eqnarray and similar environments.
Dave Love's avatar
#  
Dave Love committed
1219
@item
Carsten Dominik's avatar
Carsten Dominik committed
1220
@code{nil} means to use the text right after the label definition.
Dave Love's avatar
#  
Dave Love committed
1221 1222 1223
@item
For more complex ways of getting context, see the variable
@code{reftex-label-alist} (@ref{Options (Defining Label
Carsten Dominik's avatar
Carsten Dominik committed
1224
Environments)}).
Dave Love's avatar
#  
Dave Love committed
1225 1226
@end itemize

Carsten Dominik's avatar
Carsten Dominik committed
1227 1228
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
Dave Love's avatar
#  
Dave Love committed
1229
write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
Carsten Dominik's avatar
Carsten Dominik committed
1230
@b{Ref@TeX{}} will know that you are looking for a theorem label and
Carsten Dominik's avatar
Carsten Dominik committed
1231
restrict the menu to only these labels without even asking.
Carsten Dominik's avatar
Carsten Dominik committed
1232 1233 1234 1235 1236 1237 1238

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
Carsten Dominik's avatar
Carsten Dominik committed
1239
item.
Dave Love's avatar
#  
Dave Love committed
1240 1241 1242

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
Carsten Dominik's avatar
Carsten Dominik committed
1243
like this:
Dave Love's avatar
#  
Dave Love committed
1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256

@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]
Carsten Dominik's avatar
Carsten Dominik committed
1257
            [X] Make TOC entry    : [Value Menu] Level: -2
Dave Love's avatar
#  
Dave Love committed
1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268
[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]
Carsten Dominik's avatar
Carsten Dominik committed
1269
            [X] Make TOC entry    : [Value Menu] Level: -3
Dave Love's avatar
#  
Dave Love committed
1270 1271 1272 1273 1274 1275 1276 1277 1278
@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
Carsten Dominik's avatar
Carsten Dominik committed
1279
Labels)}).
Dave Love's avatar
#  
Dave Love committed
1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312


@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
Carsten Dominik's avatar
Carsten Dominik committed
1313
argument of the macro.
Dave Love's avatar
#  
Dave Love committed
1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326

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]
Carsten Dominik's avatar
Carsten Dominik committed
1327
            [ ] Make TOC entry    : [Value Menu] No entry
Dave Love's avatar
#  
Dave Love committed
1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355
@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
Carsten Dominik's avatar
Carsten Dominik committed
1356
the context.
Dave Love's avatar
#  
Dave Love committed
1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368

@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
Carsten Dominik's avatar
Carsten Dominik committed
1369
- the caption.
Dave Love's avatar
#  
Dave Love committed
1370 1371 1372 1373

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
Carsten Dominik's avatar
Carsten Dominik committed
1374
argument.
Dave Love's avatar
#  
Dave Love committed
1375 1376 1377 1378 1379 1380

Again, here the configuration in the customization buffer:

@example
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1381
            Type specification    : [Value Menu] Char  : f
Dave Love's avatar
#  
Dave Love committed
1382 1383 1384 1385 1386
            Label prefix string   : [Value Menu] Default
            Label reference format: [Value Menu] Default
            Context method        : [Value Menu] Macro arg nr: 3
            Magic words:
              [INS]
Carsten Dominik's avatar
Carsten Dominik committed
1387
            [ ] Make TOC entry    : [Value Menu] No entry
Dave Love's avatar
#  
Dave Love committed
1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401
@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
Carsten Dominik's avatar
Carsten Dominik committed
1402
predefined label categories.
Dave Love's avatar
#  
Dave Love committed
1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430

@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
Carsten Dominik's avatar
Carsten Dominik committed
1431
following is equivalent to the line above.
Dave Love's avatar
#  
Dave Love committed
1432 1433 1434 1435 1436 1437 1438

@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,
Carsten Dominik's avatar
Carsten Dominik committed
1439
this configuration will not be necessary.
Dave Love's avatar
#  
Dave Love committed
1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457

@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
Carsten Dominik's avatar
Carsten Dominik committed
1458
which should be observed.  We will discuss two examples.
Dave Love's avatar
#  
Dave Love committed
1459