Reduce use of @email in doc/misc
[emacs.git] / doc / misc / reftex.texi
blob2a7a231aa555dd061516c90fe31e9315a210b478
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../../info/reftex
4 @settitle RefTeX User Manual
5 @synindex ky cp
6 @syncodeindex vr cp
7 @syncodeindex fn cp
9 @ifnottex
10 @macro RefTeX {}
11 Ref@TeX{}
12 @end macro
13 @macro AUCTeX {}
14 AUC@TeX{}
15 @end macro
16 @macro BibTeX {}
17 Bib@TeX{}
18 @end macro
19 @macro ConTeXt {}
20 Con@TeX{}t
21 @end macro
22 @end ifnottex
23 @tex
24 \gdef\RefTeX{Ref\TeX}
25 \gdef\AUCTeX{AUC\TeX}
26 \gdef\BibTeX{Bib\TeX}
27 \gdef\ConTeXt{Con\TeX t}
28 @end tex
30 @include emacsver.texi
32 @set VERSION @value{EMACSVER}
33 @set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,@AUCTeX{} web site}
34 @set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,@RefTeX{} web page}
35 @set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers}
36 @set MAINTAINER the @AUCTeX{} project
37 @set SUPPORTADDRESS @AUCTeX{} user mailing list (@email{auctex@@gnu.org})
38 @set DEVELADDRESS @AUCTeX{} developer mailing list (@email{auctex-devel@@gnu.org})
39 @set BUGADDRESS @AUCTeX{} bug mailing list (@email{bug-auctex@@gnu.org})
40 @set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs FTP site}
41 @c %**end of header
43 @copying
44 This manual documents @RefTeX{} (version @value{VERSION}), a package
45 to do labels, references, citations and indices for LaTeX documents
46 with Emacs.
48 Copyright @copyright{} 1997--2013 Free Software Foundation, Inc.
50 @quotation
51 Permission is granted to copy, distribute and/or modify this document
52 under the terms of the GNU Free Documentation License, Version 1.3 or
53 any later version published by the Free Software Foundation; with no
54 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
55 and with the Back-Cover Texts as in (a) below.  A copy of the license
56 is included in the section entitled ``GNU Free Documentation License''.
58 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
59 modify this GNU manual.''
60 @end quotation
61 @end copying
63 @dircategory Emacs misc features
64 @direntry
65 * RefTeX: (reftex).             Emacs support for LaTeX cross-references
66                                   and citations.
67 @end direntry
69 @finalout
71 @c Macro definitions
73 @c Subheadings inside a table.  Need a difference between info and the rest.
74 @macro tablesubheading{text}
75 @ifinfo
76 @subsubheading \text\
77 @end ifinfo
78 @ifnotinfo
79 @item @b{\text\}
80 @end ifnotinfo
81 @end macro
83 @titlepage
84 @title @RefTeX{} User Manual
85 @subtitle Support for @LaTeX{} labels, references, citations and index entries with GNU Emacs
86 @subtitle Version @value{VERSION}
88 @author by Carsten Dominik
89 @page
90 @vskip 0pt plus 1filll
91 @insertcopying
92 @end titlepage
94 @summarycontents
95 @contents
97 @ifnottex
98 @node Top,,,(dir)
99 @top @RefTeX{}
101 @RefTeX{} is a package for managing Labels, References, Citations and
102 index entries with GNU Emacs.
104 This manual documents @RefTeX{} version @value{VERSION}.
106 Don't be discouraged by the size of this manual, which covers @RefTeX{}
107 in great depth.  All you need to know to use @RefTeX{} can be summarized
108 on two pages (@pxref{RefTeX in a Nutshell}).  You can go back later to
109 other parts of this document when needed.
111 @menu
112 * Introduction::                     Quick-Start information.
114 * Table of Contents::                A Tool to move around quickly.
115 * Labels and References::            Creating and referencing labels.
116 * Citations::                        Creating Citations.
117 * Index Support::                    Creating and Checking Index Entries.
118 * Viewing Cross-References::         Who references or cites what?
120 * RefTeXs Menu::                     The Ref menu in the menubar.
121 * Key Bindings::                      The default key bindings.
122 * Faces::                            Fontification of RefTeX's buffers.
123 * Multifile Documents::              Document spread over many files.
124 * Language Support::                 How to support other languages.
125 * Finding Files::                    Included @TeX{} files and @BibTeX{} .bib files.
126 * AUCTeX::                           Cooperation with @AUCTeX{}.
127 * Optimizations::                    When RefTeX is too slow.
128 * Problems and Work-Arounds::        First Aid.
129 * Imprint::                          Author, Web-site, Thanks
131 * Commands::                         Which are the available commands.
132 * Options::                          How to extend and configure RefTeX.
133 * Keymaps and Hooks::                For customization.
134 * Changes::                          A List of recent changes to RefTeX.
135 * GNU Free Documentation License::   The license for this documentation.
137 The Index
139 * Index::                            The full index.
141 @detailmenu
142  --- The Detailed Node Listing ---
144 Introduction
146 * Installation::                     How to install and activate RefTeX.
147 * RefTeX in a Nutshell::             A brief summary and quick guide.
149 Labels and References
151 * Creating Labels::
152 * Referencing Labels::
153 * Builtin Label Environments::       The environments RefTeX knows about.
154 * Defining Label Environments::        ... and environments it doesn't.
155 * Reference Info::                   View the label corresponding to a \ref.
156 * Reference Styles::                 Macros to be used instead of \ref.
157 * xr (LaTeX package)::               References to external documents.
159 Defining Label Environments
161 * Theorem and Axiom::                Defined with @code{\newenvironment}.
162 * Quick Equation::                   When a macro sets the label type.
163 * Figure Wrapper::                   When a macro argument is a label.
164 * Adding Magic Words::               Other words for other languages.
165 * Using \eqref::                     How to switch to this AMS-LaTeX macro.
166 * Non-Standard Environments::        Environments without \begin and \end
167 * Putting it Together::              How to combine many entries.
169 Citations
171 * Creating Citations::               How to create them.
172 * Citation Styles::                  Natbib, Harvard, Chicago and Co.
173 * Citation Info::                    View the corresponding database entry.
174 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
175 * Citations Outside LaTeX::          How to make citations in Emails etc.
176 * BibTeX Database Subsets::          Extract parts of a big database.
178 Index Support
180 * Creating Index Entries::           Macros and completion of entries.
181 * The Index Phrases File::           A special file for global indexing.
182 * Displaying and Editing the Index:: The index editor.
183 * Builtin Index Macros::             The index macros RefTeX knows about.
184 * Defining Index Macros::                ... and macros it  doesn't.
186 The Index Phrases File
188 * Collecting Phrases::               Collecting from document or external.
189 * Consistency Checks::               Check for duplicates etc.
190 * Global Indexing::                  The interactive indexing process.
192 AUCTeX
194 * AUCTeX-RefTeX Interface::          How both packages work together
195 * Style Files::                      @AUCTeX{}'s style files can support RefTeX
196 * Bib-Cite::                         Hypertext reading of a document
198 Options, Keymaps, Hooks
200 * Options (Table of Contents)::
201 * Options (Defining Label Environments)::
202 * Options (Creating Labels)::
203 * Options (Referencing Labels)::
204 * Options (Creating Citations)::
205 * Options (Index Support)::
206 * Options (Viewing Cross-References)::
207 * Options (Finding Files)::
208 * Options (Optimizations)::
209 * Options (Fontification)::
210 * Options (Misc)::
212 @end detailmenu
213 @end menu
215 @end ifnottex
217 @node Introduction, Table of Contents, , Top
218 @chapter Introduction
219 @cindex Introduction
221 @RefTeX{} is a specialized package for support of labels, references,
222 citations, and the index in @LaTeX{}.  @RefTeX{} wraps itself round four
223 @LaTeX{} macros: @code{\label}, @code{\ref}, @code{\cite}, and
224 @code{\index}.  Using these macros usually requires looking up different
225 parts of the document and searching through @BibTeX{} database files.
226 @RefTeX{} automates these time-consuming tasks almost entirely.  It also
227 provides functions to display the structure of a document and to move
228 around in this structure quickly.
230 @iftex
231 Don't be discouraged by the size of this manual, which covers @RefTeX{}
232 in great depth.  All you need to know to use @RefTeX{} can be
233 summarized on two pages (@pxref{RefTeX in a Nutshell}).  You can go
234 back later to other parts of this document when needed.
235 @end iftex
237 @xref{Imprint}, for information about who to contact for help, bug
238 reports or suggestions.
240 @menu
241 * Installation::                     How to install and activate RefTeX.
242 * RefTeX in a Nutshell::             A brief summary and quick guide.
243 @end menu
245 @node Installation, RefTeX in a Nutshell, , Introduction
246 @section Installation
247 @cindex Installation
249 @RefTeX{} has been bundled and pre-installed with Emacs since
250 version 20.2.  It has also been bundled and pre-installed with XEmacs
251 19.16--20.x.  XEmacs 21.x users want to install the corresponding
252 plug-in package which is available from the @value{XEMACSFTP}.  See the
253 XEmacs 21.x documentation on package installation for details.
255 Users of earlier Emacs distributions (including Emacs 19) or people
256 craving for new features and bugs can get a copy of the @RefTeX{}
257 distribution from the maintainer's web page.  @xref{Imprint}, for more
258 information.  The following instructions will guide you through the
259 process of installing such a distribution.
261 @subsection Building and Installing
263 Note: Currently installation is supported for Emacs only.  XEmacs users
264 might want to refer to the @RefTeX{} package available through the
265 package system of XEmacs.
267 @subsubheading Installation with make
269 In order to install RefTeX, unpack the distribution and edit the header
270 of the Makefile.  Basically, you need to change the path specifications
271 for Emacs Lisp files and info files.  Also, enter the name of your Emacs
272 executable (usually either @samp{emacs} or @samp{xemacs}).
274 Then, type
276 @example
277 make
278 make install
279 @end example
281 to compile and install the code and documentation.
283 Per default @RefTeX{} is installed in its own subdirectory which might
284 not be on your load path.  In this case, add it to load path with a
285 command like the following, replacing the sample directory with the one
286 where @RefTeX{} is installed in your case.
288 @example
289 (add-to-list 'load-path "/path/to/reftex")
290 @end example
292 Put this command into your init file before other @RefTeX{}-related
293 settings.
295 @subsubheading Installation by Hand
297 If you want to get your hands dirty, there is also the possibility to
298 install by manually copying files.
300 @enumerate a
301 @item
302 Copy the reftex*.el lisp files to a directory on your load path.  Make
303 sure that no old copy of @RefTeX{} shadows these files.
304 @item
305 Byte compile the files.  The sequence of compiling should be:
306 reftex-var.el, reftex.el, and then all the others.
307 @item
308 Copy the info file reftex.info to the info directory.
309 @end enumerate
311 @subsection Loading @RefTeX{}
313 In order to make the most important functions for entering @RefTeX{}
314 mode available add the following line to your init file.
316 @example
317 (require 'reftex)
318 @end example
320 @subsection Entering @RefTeX{} Mode
322 @findex turn-on-reftex
323 @findex reftex-mode
324 @vindex LaTeX-mode-hook
325 @vindex latex-mode-hook
326 To turn @RefTeX{} Mode on and off in a particular buffer, use
327 @kbd{M-x reftex-mode @key{RET}}.  To turn on @RefTeX{} Mode for all
328 LaTeX files, add the following lines to your @file{.emacs} file:
330 @example
331 (add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
332 (add-hook 'latex-mode-hook 'turn-on-reftex)   ; with Emacs latex mode
333 @end example
335 That's all!
337 To get started, read the documentation, in particular the
338 summary. (@pxref{RefTeX in a Nutshell})
340 In order to produce a printed version of the documentation, use
341 @code{make pdf} to produce a reftex.pdf file.  Analogously you can use
342 the @code{dvi}, @code{ps}, or @code{html} targets to create DVI,
343 PostScript or HTML files.
345 @subsection Environment
346 @cindex Finding files
347 @cindex BibTeX database files, not found
348 @cindex TeX files, not found
349 @cindex @code{TEXINPUTS}, environment variable
350 @cindex @code{BIBINPUTS}, environment variable
352 @RefTeX{} needs to access all files which are part of a multifile
353 document, and the BibTeX database files requested by the
354 @code{\bibliography} command.  To find these files, @RefTeX{} will
355 require a search path, i.e., a list of directories to check.  Normally
356 this list is stored in the environment variables @code{TEXINPUTS} and
357 @code{BIBINPUTS} which are also used by @RefTeX{}.  However, on some
358 systems these variables do not contain the full search path.  If
359 @RefTeX{} does not work for you because it cannot find some files,
360 @xref{Finding Files}.
362 @page
363 @node RefTeX in a Nutshell, , Installation, Introduction
364 @section @RefTeX{} in a Nutshell
365 @cindex Quick-Start
366 @cindex Getting Started
367 @cindex RefTeX in a Nutshell
368 @cindex Nutshell, RefTeX in a
370 @enumerate
371 @item
372 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
373 a table of contents of the document.  This buffer can display sections,
374 labels and index entries defined in the document.  From the buffer, you
375 can jump quickly to every part of your document.  Press @kbd{?} to get
376 help.
378 @item
379 @b{Labels and References}@* @RefTeX{} helps to create unique labels
380 and to find the correct key for references quickly.  It distinguishes
381 labels for different environments, knows about all standard
382 environments (and many others), and can be configured to recognize any
383 additional labeled environments you have defined yourself (variable
384 @code{reftex-label-alist}).
386 @itemize @bullet
387 @item
388 @b{Creating Labels}@*
389 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
390 @RefTeX{} will either
391 @itemize @minus
392 @item
393 derive a label from context (default for section labels)
394 @item
395 prompt for a label string (default for figures and tables) or
396 @item
397 insert a simple label made of a prefix and a number (all other
398 environments)
399 @end itemize
400 @noindent
401 Which labels are created how is configurable with the variable
402 @code{reftex-insert-label-flags}.
404 @item
405 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
406 (@code{reftex-reference}).  This shows an outline of the document with
407 all labels of a certain type (figure, equation,...) and some label
408 context.  Selecting a label inserts a @code{\ref@{@var{label}@}} macro
409 into the original buffer.
410 @end itemize
412 @item
413 @b{Citations}@*
414 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
415 regular expression to search in current @BibTeX{} database files (as
416 specified in the @code{\bibliography} command) and pull out a list of
417 matches for you to choose from.  The list is @emph{formatted} and
418 sorted.  The selected article is referenced as @samp{\cite@{@var{key}@}}
419 (see the variable @code{reftex-cite-format} if you want to insert
420 different macros).
422 @item
423 @b{Index Support}@*
424 @RefTeX{} helps to enter index entries.  It also compiles all
425 entries into an alphabetically sorted @file{*Index*} buffer which you
426 can use to check and edit the entries.  @RefTeX{} knows about the
427 standard index macros and can be configured to recognize any additional
428 macros you have defined (@code{reftex-index-macros}).  Multiple indices
429 are supported.
431 @itemize @bullet
432 @item
433 @b{Creating Index Entries}@*
434 To index the current selection or the word at point, type @kbd{C-c /}
435 (@code{reftex-index-selection-or-word}).  The default macro
436 @code{reftex-index-default-macro} will be used.  For a more complex entry
437 type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
438 and enter the arguments with completion.
440 @item
441 @b{The Index Phrases File (Delayed Indexing)}@*
442 Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
443 the current word or selection to a special @emph{index phrase file}.
444 @RefTeX{} can later search the document for occurrences of these
445 phrases and let you interactively index the matches.
447 @item
448 @b{Displaying and Editing the Index}@*
449 To display the compiled index in a special buffer, type @kbd{C-c >}
450 (@code{reftex-display-index}).  From that buffer you can check and edit
451 all entries.
452 @end itemize
454 @page
455 @item @b{Viewing Cross-References}@*
456 When point is on the @var{key} argument of a cross-referencing macro
457 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
458 @code{\index}, and variations) or inside a @BibTeX{} database entry, you
459 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
460 corresponding locations in the document and associated @BibTeX{} database
461 files. @*
462 When the enclosing macro is @code{\cite} or @code{\ref} and no other
463 message occupies the echo area, information about the citation or label
464 will automatically be displayed in the echo area.
466 @item
467 @b{Multifile Documents}@*
468 Multifile Documents are fully supported.  The included files must have a
469 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
470 master file.  @RefTeX{} provides cross-referencing information from
471 all parts of the document, and across document borders
472 (@file{xr.sty}).
474 @item
475 @b{Document Parsing}@* @RefTeX{} needs to parse the document in
476 order to find labels and other information.  It does it automatically
477 once and updates its list internally when @code{reftex-label} and
478 @code{reftex-index} are used.  To enforce reparsing, call any of the
479 commands described above with a raw @kbd{C-u} prefix, or press the
480 @kbd{r} key in the label selection buffer, the table of contents
481 buffer, or the index buffer.
483 @item
484 @b{@AUCTeX{}} @* If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can
485 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}).  @AUCTeX{}
486 contains style files which trigger appropriate settings in
487 @RefTeX{}, so that for many of the popular @LaTeX{} packages no
488 additional customizations will be necessary.
490 @item
491 @b{Useful Settings}@*
492 To integrate RefTeX with @AUCTeX{}, use
493 @lisp
494 (setq reftex-plug-into-AUCTeX t)
495 @end lisp
497 To make your own @LaTeX{} macro definitions known to @RefTeX{},
498 customize the variables
499 @example
500 @code{reftex-label-alist}          @r{(for label macros/environments)}
501 @code{reftex-section-levels}       @r{(for sectioning commands)}
502 @code{reftex-cite-format}          @r{(for @code{\cite}-like macros)}
503 @code{reftex-index-macros}         @r{(for @code{\index}-like macros)}
504 @code{reftex-index-default-macro}  @r{(to set the default macro)}
505 @end example
506 If you have a large number of macros defined, you may want to write
507 an @AUCTeX{} style file to support them with both @AUCTeX{} and
508 @RefTeX{}.
510 @item @b{Where Next?}@* Go ahead and use @RefTeX{}.  Use its menus
511 until you have picked up the key bindings.  For an overview of what you
512 can do in each of the different special buffers, press @kbd{?}.  Read
513 the manual if you get stuck, or if you are curious what else might be
514 available.  The first part of the manual explains in
515 a tutorial way how to use and customize @RefTeX{}.  The second
516 part is a command and variable reference.
517 @end enumerate
519 @node Table of Contents, Labels and References, Introduction, Top
520 @chapter Table of Contents
521 @cindex @file{*toc*} buffer
522 @cindex Structure editing
523 @cindex Table of contents buffer
524 @findex reftex-toc
525 @kindex C-c =
527 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
528 contents of the document.  By default, this @file{*toc*} buffer shows
529 only the sections of a document.  Using the @kbd{l} and @kbd{i} keys you
530 can display all labels and index entries defined in the document as
531 well.
533 With the cursor in any of the lines denoting a location in the
534 document, simple key strokes will display the corresponding part in
535 another window, jump to that location, or perform other actions.
537 @kindex ?
538 Here is a list of special commands in the @file{*toc*} buffer.  A
539 summary of this information is always available by pressing
540 @kbd{?}.
542 @table @kbd
544 @tablesubheading{General}
545 @item ?
546 Display a summary of commands.
548 @item 0-9, -
549 Prefix argument.
551 @tablesubheading{Moving around}
552 @item n
553 Goto next entry in the table of contents.
555 @item p
556 Goto previous entry in the table of contents.
558 @item C-c C-n
559 Goto next section heading.  Useful when many labels and index entries
560 separate section headings.
562 @item C-c C-p
563 Goto previous section heading.
565 @item N z
566 Jump to section N, using the prefix arg.  For example, @kbd{3 z} jumps
567 to section 3.
569 @tablesubheading{Access to document locations}
570 @item @key{SPC}
571 Show the corresponding location in another window.  This command does
572 @emph{not} select that other window.
574 @item @key{TAB}
575 Goto the location in another window.
577 @item @key{RET}
578 Go to the location and hide the @file{*toc*} buffer.  This will restore
579 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
580 called.
582 @item mouse-2
583 @vindex reftex-highlight-selection
584 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
585 See also variable @code{reftex-highlight-selection}, @ref{Options
586 (Fontification)}.
588 @item f
589 @vindex reftex-toc-follow-mode
590 @vindex reftex-revisit-to-follow
591 Toggle follow mode.  When follow mode is active, the other window will
592 always show the location corresponding to the line at point in the
593 @file{*toc*} buffer.  This is similar to pressing @key{SPC} after each
594 cursor motion.  The default for this flag can be set with the variable
595 @code{reftex-toc-follow-mode}.  Note that only context in files already
596 visited is shown.  @RefTeX{} will not visit a file just for follow
597 mode.  See, however, the variable
598 @code{reftex-revisit-to-follow}.
600 @item .
601 Show calling point in another window.  This is the point from where
602 @code{reftex-toc} was last called.
604 @page
605 @tablesubheading{Promotion and Demotion}
607 @item <
608 Promote the current section.  This will convert @code{\section} to
609 @code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
610 an active region, all sections in the region will be promoted, including
611 the one at point.  To avoid mistakes, @RefTeX{} requires a fresh
612 document scan before executing this command; if necessary, it will
613 automatically do this scan and ask the user to repeat the promotion
614 command.
616 @item >
617 Demote the current section.  This is the opposite of promotion.  It will
618 convert @code{\chapter} to @code{\section} etc.  If there is an active
619 region, all sections in the region will be demoted, including the one at
620 point.
622 @item M-%
623 Rename the label at point.  While generally not recommended, this can be
624 useful when a package like @file{fancyref} is used where the label
625 prefix determines the wording of a reference.  After a
626 promotion/demotion it may be necessary to change a few labels from
627 @samp{sec:xyz} to @samp{cha:xyz} or vice versa.  This command can be
628 used to do this; it launches a query replace to rename the definition
629 and all references of a label.
631 @tablesubheading{Exiting}
632 @item q
633 Hide the @file{*toc*} buffer, return to the position where
634 @code{reftex-toc} was last called.
636 @item k
637 Kill the @file{*toc*} buffer, return to the position where
638 @code{reftex-toc} was last called.
640 @item C-c >
641 Switch to the @file{*Index*} buffer of this document.  With prefix
642 @samp{2}, restrict the index to the section at point in the @file{*toc*}
643 buffer.
645 @tablesubheading{Controlling what gets displayed}
647 @item t
648 @vindex reftex-toc-max-level
649 Change the maximum level of toc entries displayed in the @file{*toc*}
650 buffer.  Without prefix arg, all levels will be included.  With prefix
651 arg (e.g., @kbd{3 t}), ignore all toc entries with level greater than
652 @var{arg} (3 in this case).  Chapters are level 1, sections are level 2.
653 The mode line @samp{T<>} indicator shows the current value.  The default
654 depth can be configured with the variable
655 @code{reftex-toc-max-level}.
657 @item F
658 @vindex reftex-toc-include-file-boundaries
659 Toggle the display of the file borders of a multifile document in the
660 @file{*toc*} buffer.  The default for this flag can be set with the
661 variable @code{reftex-toc-include-file-boundaries}.
663 @item l
664 @vindex reftex-toc-include-labels
665 Toggle the display of labels in the @file{*toc*} buffer.  The default
666 for this flag can be set with the variable
667 @code{reftex-toc-include-labels}.  When called with a prefix argument,
668 @RefTeX{} will prompt for a label type and include only labels of
669 the selected type in the @file{*toc*} buffer.  The mode line @samp{L<>}
670 indicator shows which labels are included.
672 @item i
673 @vindex reftex-toc-include-index-entries
674 Toggle the display of index entries in the @file{*toc*} buffer.  The
675 default for this flag can be set with the variable
676 @code{reftex-toc-include-index-entries}.  When called with a prefix
677 argument, @RefTeX{} will prompt for a specific index and include
678 only entries in the selected index in the @file{*toc*} buffer.  The mode
679 line @samp{I<>} indicator shows which index is used.
681 @item c
682 @vindex reftex-toc-include-context
683 Toggle the display of label and index context in the @file{*toc*}
684 buffer.  The default for this flag can be set with the variable
685 @code{reftex-toc-include-context}.
687 @tablesubheading{Updating the buffer}
689 @item g
690 Rebuild the @file{*toc*} buffer.  This does @emph{not} rescan the
691 document.
693 @item r
694 @vindex reftex-enable-partial-scans
695 Reparse the @LaTeX{} document and rebuild the @file{*toc*} buffer.  When
696 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
697 location is defined in, not the entire document.
699 @item C-u r
700 Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*toc*}
701 buffer.
703 @item x
704 Switch to the @file{*toc*} buffer of an external document.  When the
705 current document is using the @code{xr} package (@pxref{xr (LaTeX
706 package)}), @RefTeX{} will switch to one of the external
707 documents.
710 @tablesubheading{Automatic recentering}
712 @item d
713 Toggle the display of a dedicated frame displaying just the @file{*toc*}
714 buffer.  Follow mode and visiting locations will not work that frame,
715 but automatic recentering will make this frame always show your current
716 editing location in the document (see below).
718 @item a
719 Toggle the automatic recentering of the @file{*toc*} buffer.  When this
720 option is on, moving around in the document will cause the @file{*toc*}
721 to always highlight the current section.  By default, this option is
722 active while the dedicated @file{*TOC*} frame exists.  See also the
723 variable @code{reftex-auto-recenter-toc}.
725 @end table
727 @vindex reftex-toc-map
728 In order to define additional commands for the @file{*toc*} buffer, the
729 keymap @code{reftex-toc-map} may be used.
731 @findex reftex-toc-recenter
732 @vindex reftex-auto-recenter-toc
733 @vindex reftex-idle-time
734 @cindex @file{*toc*} buffer, recentering
735 @cindex Table of contents buffer, recentering
736 @kindex C-c -
737 If you call @code{reftex-toc} while the @file{*toc*} buffer already
738 exists, the cursor will immediately jump to the right place, i.e., the
739 section from which @code{reftex-toc} was called will be highlighted.
740 The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
741 the @file{*toc*} buffer and highlight the correct line without actually
742 selecting the @file{*toc*} window.  This can be useful to quickly find
743 out where in the document you currently are.  You can also automate this
744 by asking RefTeX to keep track of your current editing position in the
745 TOC@.  The TOC window will then be updated whenever you stop typing for
746 more than @code{reftex-idle-time} seconds.  By default this works only
747 with the dedicated @file{*TOC*} frame.  But you can also force automatic
748 recentering of the TOC window on the current frame with
749 @lisp
750 (setq reftex-auto-recenter-toc t)
751 @end lisp
754 @cindex Sectioning commands
755 @cindex KOMA-Script, LaTeX classes
756 @cindex LaTeX classes, KOMA-Script
757 @cindex TOC entries for environments
758 @vindex reftex-section-levels
759 The section macros recognized by @RefTeX{} are all @LaTeX{} section
760 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
761 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
762 Additional macros can be configured with the variable
763 @code{reftex-section-levels}.  It is also possible to add certain @LaTeX{}
764 environments to the table of contents.  This is probably only useful for
765 theorem-like environments. @xref{Defining Label Environments}, for an
766 example.
768 @node Labels and References, Citations, Table of Contents, Top
769 @chapter Labels and References
770 @cindex Labels in LaTeX
771 @cindex References in LaTeX
772 @cindex Label category
773 @cindex Label environment
774 @cindex @code{\label}
776 @LaTeX{} provides a powerful mechanism to deal with cross-references in a
777 document.  When writing a document, any part of it can be marked with a
778 label, like @samp{\label@{mark@}}.  @LaTeX{} records the current value of a
779 certain counter when a label is defined.  Later references to this label
780 (like @samp{\ref@{mark@}}) will produce the recorded value of the
781 counter.
783 Labels can be used to mark sections, figures, tables, equations,
784 footnotes, items in enumerate lists etc.  @LaTeX{} is context sensitive in
785 doing this: A label defined in a figure environment automatically
786 records the figure counter, not the section counter.
788 Several different environments can share a common counter and therefore
789 a common label category.  For example labels in both @code{equation} and
790 @code{eqnarray} environments record the value of the same counter: the
791 equation counter.
793 @menu
794 * Creating Labels::
795 * Referencing Labels::
796 * Builtin Label Environments::       The environments RefTeX knows about.
797 * Defining Label Environments::        ... and environments it doesn't.
798 * Reference Info::                   View the label corresponding to a \ref.
799 * Reference Styles::                 Macros to be used instead of \ref.
800 * xr (LaTeX package)::               References to external documents.
801 @end menu
803 @node Creating Labels, Referencing Labels, , Labels and References
804 @section Creating Labels
805 @cindex Creating labels
806 @cindex Labels, creating
807 @cindex Labels, deriving from context
808 @kindex C-c (
809 @findex reftex-label
811 In order to create a label in a @LaTeX{} document, press @kbd{C-c (}
812 (@code{reftex-label}).  Just like @LaTeX{}, @RefTeX{} is context sensitive
813 and will figure out the environment it currently is in and adapt the
814 label to that environment.  A label usually consists of a short prefix
815 indicating the type of the label and a unique mark.  @RefTeX{} has
816 three different modes to create this mark.
818 @enumerate
819 @item
820 @vindex reftex-translate-to-ascii-function
821 @vindex reftex-derive-label-parameters
822 @vindex reftex-label-illegal-re
823 @vindex reftex-abbrev-parameters
824 A label can be derived from context.  This means, @RefTeX{} takes
825 the context of the label definition and constructs a label from
826 that@footnote{Note that the context may contain constructs which are
827 invalid in labels.  @RefTeX{} will therefore strip the accent from
828 accented Latin-1 characters and remove everything else which is not
829 valid in labels.  This mechanism is safe, but may not be satisfactory
830 for non-western languages.  Check the following variables if you need to
831 change things: @code{reftex-translate-to-ascii-function},
832 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
833 @code{reftex-abbrev-parameters}.}.  This works best for section labels,
834 where the section heading is used to construct a label.  In fact,
835 @RefTeX{}'s default settings use this method only for section
836 labels.  You will be asked to confirm the derived label, or edit
839 @item
840 We may also use a simple unique number to identify a label.  This is
841 mostly useful for labels where it is difficult to come up with a very
842 good descriptive name.  @RefTeX{}'s default settings use this method
843 for equations, enumerate items and footnotes.  The author of @RefTeX{}
844 tends to write documents with many equations and finds it impossible
845 to come up with good names for each of them.  These simple labels are
846 inserted without query, and are therefore very fast.  Good descriptive
847 names are not really necessary as @RefTeX{} will provide context to
848 reference a label (@pxref{Referencing Labels}).
850 @item
851 The third method is to ask the user for a label.  This is most
852 useful for things which are easy to describe briefly and do not turn up
853 too frequently in a document.  @RefTeX{} uses this for figures and
854 tables.  Of course, one can enter the label directly by typing the full
855 @samp{\label@{mark@}}.  The advantage of using @code{reftex-label}
856 anyway is that @RefTeX{} will know that a new label has been defined.
857 It will then not be necessary to rescan the document in order to access
858 this label later.
859 @end enumerate
861 @vindex reftex-insert-label-flags
862 If you want to change the way certain labels are created, check out the
863 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
864 Labels)}).
866 If you are using @AUCTeX{} to write your @LaTeX{} documents, you can
867 set it up to delegate the creation of labels to
868 @RefTeX{}. @xref{AUCTeX}, for more information.
870 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
871 @section Referencing Labels
872 @cindex Referencing labels
873 @cindex Labels, referencing
874 @cindex Selection buffer, labels
875 @cindex Selection process
876 @cindex @code{\ref}
877 @kindex C-c )
878 @findex reftex-reference
880 @vindex reftex-trust-label-prefix
881 @RefTeX{} scans the document in order to find all labels.  To make
882 referencing labels easier, it assigns to each label a category, the
883 @emph{label type} (for example section, table, figure, equation, etc.).
884 In order to determine the label type, @RefTeX{} parses around each label
885 to see in what kind of environments it is located.  You can speed up
886 the parsing by using type-specific prefixes for labels and configuring
887 the variable @code{reftex-trust-label-prefix}.
889 Referencing Labels is really at the heart of @RefTeX{}.  Press @kbd{C-c
890 )} in order to reference a label (@code{reftex-reference}).  This will
891 start a selection process and finally insert the complete
892 @samp{\ref@{label@}} into the buffer.
894 @vindex reftex-ref-macro-prompt
895 First, you can select which reference macro you want to use,
896 e.g., @samp{\ref} or @samp{\pageref}.  Later in the process you have
897 another chance to make this selection and you can therefore disable this
898 step by customizing @code{reftex-ref-macro-prompt} if you find it too
899 intrusive.  @xref{Reference Styles}.
901 Then, @RefTeX{} will determine the label category which is required.
902 Often that can be figured out from context.  For example, if you write
903 @samp{As shown in eq.} and then press @kbd{C-c )}, @RefTeX{} knows that
904 an equation label is going to be referenced.  If it cannot figure out
905 what label category is needed, it will query for one.
907 You will then be presented with a label selection menu.  This is a
908 special buffer which contains an outline of the document along with all
909 labels of the given label category.  In addition, next to the label
910 there will be one line of context of the label definition, which is some
911 text in the buffer near the label definition.  Usually this is
912 sufficient to identify the label.  If you are unsure about a certain
913 label, pressing @key{SPC} will show the label definition point in
914 another window.
916 In order to reference a label, move the cursor to the correct label and
917 press @key{RET}.  You can also reference several labels with a single
918 call to @code{reftex-reference} by marking entries with the @kbd{m}
919 key (see below).
921 @kindex ?
922 Here is a list of special commands in the selection buffer.  A summary
923 of this information is always available from the selection process by
924 pressing @kbd{?}.
928 @table @kbd
929 @tablesubheading{General}
930 @item ?
931 Show a summary of available commands.
933 @item 0-9,-
934 Prefix argument.
936 @tablesubheading{Moving around}
937 @item n
938 Go to next label.
940 @item p
941 Go to previous label.
943 @item b
944 Jump back to the position where you last left the selection buffer.
945 Normally this should get you back to the last referenced label.
947 @item C-c C-n
948 Goto next section heading.
950 @item C-c C-p
951 Goto previous section heading.
953 @item N z
954 Jump to section N, using the prefix arg.  For example @kbd{3 z} jumps to
955 section 3.
957 @tablesubheading{Displaying Context}
958 @item @key{SPC}
959 Show the surroundings of the definition of the current label in another
960 window.  See also the @kbd{f} key.
962 @item f
963 @vindex reftex-revisit-to-follow
964 Toggle follow mode.  When follow mode is active, the other window will
965 always display the full context of the current label.  This is similar
966 to pressing @key{SPC} after each cursor motion.  Note that only context
967 in files already visited is shown.  @RefTeX{} will not visit a file
968 just for follow mode.  See, however, the variable
969 @code{reftex-revisit-to-follow}.
971 @item .
972 Show insertion point in another window.  This is the point from where you
973 called @code{reftex-reference}.
975 @tablesubheading{Selecting a label and creating the reference}
976 @item @key{RET}
977 Insert a reference to the label at point into the buffer from which the
978 selection process was started.  When entries have been marked, @key{RET}
979 references all marked labels.
981 @item mouse-2
982 @vindex reftex-highlight-selection
983 Clicking with mouse button 2 on a label will accept it like @key{RET}
984 would.  See also variable @code{reftex-highlight-selection},
985 @ref{Options (Misc)}.
987 @vindex reftex-multiref-punctuation
988 @item m - + ,
989 Mark the current entry.  When several entries have been marked, pressing
990 @kbd{RET} will accept all of them and place them into several
991 @code{\ref} macros.  The special markers @samp{,-+} also store a
992 separator to be inserted before the corresponding reference.  So marking
993 six entries with the keys @samp{m , , - , +} will give a reference list
994 like this (see the variable @code{reftex-multiref-punctuation})
995 @example
996 In eqs. (1), (2), (3)--(4), (5) and (6)
997 @end example
999 @item u
1000 Unmark a marked entry.
1002 @c FIXME: Do we need `A' as well for consistency?
1003 @cindex LaTeX packages, @code{saferef}
1004 @cindex @code{saferef}, LaTeX package
1005 @item a
1006 Accept the marked entries and put all labels as a comma-separated list
1007 into one @emph{single} @code{\ref} macro.  Some packages like
1008 @file{saferef.sty} support multiple references in this way.
1010 @item l
1011 Use the last referenced label(s) again.  This is equivalent to moving to
1012 that label and pressing @key{RET}.
1014 @item @key{TAB}
1015 Enter a label with completion.  This may also be a label which does not
1016 yet exist in the document.
1018 @item v
1019 Cycle forward through active reference macros.  The selected macro is
1020 displayed by the @samp{S<...>} indicator in the mode line of the
1021 selection buffer.  This mechanism comes in handy if you are using
1022 @LaTeX{} packages like @code{varioref} or @code{fancyref} and want to
1023 use the special referencing macros they provide (e.g., @code{\vref} or
1024 @code{\fref}) instead of @code{\ref}.
1026 @item V
1027 Cycle backward through active reference macros.
1029 @tablesubheading{Exiting}
1031 @item q
1032 Exit the selection process without inserting any reference into the
1033 buffer.
1035 @tablesubheading{Controlling what gets displayed}
1036 @vindex reftex-label-menu-flags
1037 The defaults for the following flags can be configured with the variable
1038 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
1040 @item c
1041 Toggle the display of the one-line label definition context in the
1042 selection buffer.
1044 @item F
1045 Toggle the display of the file borders of a multifile document in the
1046 selection buffer.
1048 @item t
1049 Toggle the display of the table of contents in the selection buffer.
1050 With prefix @var{arg}, change the maximum level of toc entries displayed
1051 to @var{arg}.  Chapters are level 1, sections are level 2.
1053 @item #
1054 Toggle the display of a label counter in the selection buffer.
1056 @item %
1057 Toggle the display of labels hidden in comments in the selection
1058 buffers.  Sometimes, you may have commented out parts of your document.
1059 If these parts contain label definitions, @RefTeX{} can still display
1060 and reference these labels.
1062 @tablesubheading{Updating the buffer}
1063 @item g
1064 Update the menu.  This will rebuilt the menu from the internal label
1065 list, but not reparse the document (see @kbd{r}).
1067 @item r
1068 @vindex reftex-enable-partial-scans
1069 Reparse the document to update the information on all labels and rebuild
1070 the menu.  If the variable @code{reftex-enable-partial-scans} is
1071 non-@code{nil} and your document is a multifile document, this will
1072 reparse only a part of the document (the file in which the label at
1073 point was defined).
1075 @item C-u r
1076 Reparse the @emph{entire} document.
1078 @item s
1079 Switch the label category.  After prompting for another label category,
1080 a menu for that category will be shown.
1082 @item x
1083 Reference a label from an external document.  With the @LaTeX{} package
1084 @code{xr} it is possible to reference labels defined in another
1085 document.  This key will switch to the label menu of an external
1086 document and let you select a label from there (@pxref{xr (LaTeX
1087 package),,xr}).
1089 @end table
1091 @vindex reftex-select-label-map
1092 In order to define additional commands for the selection process, the
1093 keymap @code{reftex-select-label-map} may be used.
1095 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
1096 @section Builtin Label Environments
1097 @cindex Builtin label environments
1098 @cindex Label environments, builtin
1099 @cindex Environments, builtin
1100 @vindex reftex-label-alist
1101 @vindex reftex-label-alist-builtin
1103 @RefTeX{} needs to be aware of the environments which can be referenced
1104 with a label (i.e., which carry their own counters).  By default, @RefTeX{}
1105 recognizes all labeled environments and macros discussed in @cite{The
1106 @LaTeX{} Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
1107 1994.}.  These are:
1109 @itemize @minus
1110 @item
1111 @cindex @code{figure}, LaTeX environment
1112 @cindex @code{figure*}, LaTeX environment
1113 @cindex @code{table}, LaTeX environment
1114 @cindex @code{table*}, LaTeX environment
1115 @cindex @code{equation}, LaTeX environment
1116 @cindex @code{eqnarray}, LaTeX environment
1117 @cindex @code{enumerate}, LaTeX environment
1118 @cindex @code{\footnote}, LaTeX macro
1119 @cindex LaTeX macro @code{footnote}
1120 @cindex LaTeX core
1121 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
1122 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
1123 the @LaTeX{} core stuff)
1124 @item
1125 @cindex AMS-LaTeX
1126 @cindex @code{amsmath}, LaTeX package
1127 @cindex LaTeX packages, @code{amsmath}
1128 @cindex @code{align}, AMS-LaTeX environment
1129 @cindex @code{gather}, AMS-LaTeX environment
1130 @cindex @code{multline}, AMS-LaTeX environment
1131 @cindex @code{flalign}, AMS-LaTeX environment
1132 @cindex @code{alignat}, AMS-LaTeX environment
1133 @cindex @code{xalignat}, AMS-LaTeX environment
1134 @cindex @code{xxalignat}, AMS-LaTeX environment
1135 @cindex @code{subequations}, AMS-LaTeX environment
1136 @code{align}, @code{gather}, @code{multline}, @code{flalign},
1137 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
1138 (from AMS-@LaTeX{}'s @file{amsmath.sty} package)
1139 @item
1140 @cindex @code{endnote}, LaTeX package
1141 @cindex LaTeX packages, @code{endnote}
1142 @cindex @code{\endnote}, LaTeX macro
1143 the @code{\endnote} macro (from @file{endnotes.sty})
1144 @item
1145 @cindex @code{fancybox}, LaTeX package
1146 @cindex LaTeX packages, @code{fancybox}
1147 @cindex @code{Beqnarray}, LaTeX environment
1148 @code{Beqnarray} (@file{fancybox.sty})
1149 @item
1150 @cindex @code{floatfig}, LaTeX package
1151 @cindex LaTeX packages, @code{floatfig}
1152 @cindex @code{floatingfig}, LaTeX environment
1153 @code{floatingfig} (@file{floatfig.sty})
1154 @item
1155 @cindex @code{longtable}, LaTeX package
1156 @cindex LaTeX packages, @code{longtable}
1157 @cindex @code{longtable}, LaTeX environment
1158 @code{longtable} (@file{longtable.sty})
1159 @item
1160 @cindex @code{picinpar}, LaTeX package
1161 @cindex LaTeX packages, @code{picinpar}
1162 @cindex @code{figwindow}, LaTeX environment
1163 @cindex @code{tabwindow}, LaTeX environment
1164 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1165 @item
1166 @cindex @code{sidecap}, LaTeX package
1167 @cindex LaTeX packages, @code{sidecap}
1168 @cindex @code{SCfigure}, LaTeX environment
1169 @cindex @code{SCtable}, LaTeX environment
1170 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1171 @item
1172 @cindex @code{rotating}, LaTeX package
1173 @cindex LaTeX packages, @code{rotating}
1174 @cindex @code{sidewaysfigure}, LaTeX environment
1175 @cindex @code{sidewaystable}, LaTeX environment
1176 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1177 @item
1178 @cindex @code{subfig}, LaTeX package
1179 @cindex LaTeX packages, @code{subfigure}
1180 @cindex @code{subfigure}, LaTeX environment
1181 @cindex @code{subfigure*}, LaTeX environment
1182 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1183 (@file{subfigure.sty})
1184 @item
1185 @cindex @code{supertab}, LaTeX package
1186 @cindex LaTeX packages, @code{supertab}
1187 @cindex @code{supertabular}, LaTeX environment
1188 @code{supertabular} (@file{supertab.sty})
1189 @item
1190 @cindex @code{wrapfig}, LaTeX package
1191 @cindex LaTeX packages, @code{wrapfig}
1192 @cindex @code{wrapfigure}, LaTeX environment
1193 @code{wrapfigure} (@file{wrapfig.sty})
1194 @end itemize
1196 If you want to use other labeled environments, defined with
1197 @code{\newtheorem}, @RefTeX{} needs to be configured to recognize
1198 them (@pxref{Defining Label Environments}).
1200 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1201 @section Defining Label Environments
1202 @cindex Label environments, defining
1204 @vindex reftex-label-alist
1205 @RefTeX{} can be configured to recognize additional labeled
1206 environments and macros.  This is done with the variable
1207 @code{reftex-label-alist} (@pxref{Options (Defining Label
1208 Environments)}).  If you are not familiar with Lisp, you can use the
1209 @code{custom} library to configure this rather complex variable.  To do
1210 this, use
1212 @example
1213 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1214 @end example
1216 @vindex reftex-label-alist-builtin
1217 Here we will discuss a few examples, in order to make things clearer.
1218 It can also be instructive to look at the constant
1219 @code{reftex-label-alist-builtin} which contains the entries for
1220 all the builtin environments and macros (@pxref{Builtin Label
1221 Environments}).
1223 @menu
1224 * Theorem and Axiom::                Defined with @code{\newenvironment}.
1225 * Quick Equation::                   When a macro sets the label type.
1226 * Figure Wrapper::                   When a macro argument is a label.
1227 * Adding Magic Words::               Other words for other languages.
1228 * Using \eqref::                     How to switch to this AMS-@LaTeX{} macro.
1229 * Non-Standard Environments::        Environments without \begin and \end
1230 * Putting it Together::              How to combine many entries.
1231 @end menu
1233 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1234 @subsection Theorem and Axiom Environments
1235 @cindex @code{theorem}, newtheorem
1236 @cindex @code{axiom}, newtheorem
1237 @cindex @code{\newtheorem}
1239 Suppose you are using @code{\newtheorem} in @LaTeX{} in order to define two
1240 new environments, @code{theorem} and @code{axiom}
1242 @example
1243 \newtheorem@{axiom@}@{Axiom@}
1244 \newtheorem@{theorem@}@{Theorem@}
1245 @end example
1247 @noindent
1248 to be used like this:
1250 @example
1251 \begin@{axiom@}
1252 \label@{ax:first@}
1253   ....
1254 \end@{axiom@}
1255 @end example
1257 So we need to tell @RefTeX{} that @code{theorem} and @code{axiom} are new
1258 labeled environments which define their own label categories.  We can
1259 either use Lisp to do this (e.g., in @file{.emacs}) or use the custom
1260 library.  With Lisp it would look like this
1262 @lisp
1263 (setq reftex-label-alist
1264    '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
1265      ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "th.") -3)))
1266 @end lisp
1268 The type indicator characters @code{?a} and @code{?h} are used for
1269 prompts when @RefTeX{} queries for a label type.  @code{?h}
1270 was chosen for @code{theorem} since @code{?t} is already taken by
1271 @code{table}.  Note that also @code{?s}, @code{?f}, @code{?e},
1272 @code{?i}, @code{?n} are already used for standard environments.
1274 @noindent
1275 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1276 @samp{thr:}, respectively.  @xref{AUCTeX}, for information on how
1277 @AUCTeX{} can use @RefTeX{} to automatically create labels when a new
1278 environment is inserted into a buffer.  Additionally, the following
1279 needs to be added to one's .emacs file before @AUCTeX{} will
1280 automatically create labels for the new environments.
1282 @lisp
1283 (add-hook 'LaTeX-mode-hook
1284    (lambda ()
1285      (LaTeX-add-environments
1286        '("axiom" LaTeX-env-label)
1287        '("theorem" LaTeX-env-label))))
1288 @end lisp
1291 @noindent
1292 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1293 references to these labels.
1295 @noindent
1296 The next item indicates how to grab context of the label definition.
1297 @itemize @minus
1298 @item
1299 @code{t} means to get it from a default location (from the beginning of
1300 a @code{\macro} or after the @code{\begin} statement).  @code{t} is
1301 @emph{not} a good choice for eqnarray and similar environments.
1302 @item
1303 @code{nil} means to use the text right after the label definition.
1304 @item
1305 For more complex ways of getting context, see the variable
1306 @code{reftex-label-alist} (@ref{Options (Defining Label
1307 Environments)}).
1308 @end itemize
1310 The following list of strings is used to guess the correct label type
1311 from the word before point when creating a reference.  For example if you
1312 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1313 @RefTeX{} will know that you are looking for a theorem label and
1314 restrict the menu to only these labels without even asking.
1316 The final item in each entry is the level at which the environment
1317 should produce entries in the table of context buffer.  If the number is
1318 positive, the environment will produce numbered entries (like
1319 @code{\section}), if it is negative the entries will be unnumbered (like
1320 @code{\section*}).  Use this only for environments which structure the
1321 document similar to sectioning commands.  For everything else, omit the
1322 item.
1324 To do the same configuration with @code{customize}, you need to click on
1325 the @code{[INS]} button twice to create two templates and fill them in
1326 like this:
1328 @example
1329 Reftex Label Alist: [Hide]
1330 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1331             Environment or \macro : [Value Menu] String: axiom
1332             Type specification    : [Value Menu] Char  : a
1333             Label prefix string   : [Value Menu] String: ax:
1334             Label reference format: [Value Menu] String: ~\ref@{%s@}
1335             Context method        : [Value Menu] After label
1336             Magic words:
1337               [INS] [DEL] String: axiom
1338               [INS] [DEL] String: ax.
1339               [INS]
1340             [X] Make TOC entry    : [Value Menu] Level: -2
1341 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1342             Environment or \macro : [Value Menu] String: theorem
1343             Type specification    : [Value Menu] Char  : h
1344             Label prefix string   : [Value Menu] String: thr:
1345             Label reference format: [Value Menu] String: ~\ref@{%s@}
1346             Context method        : [Value Menu] Default position
1347             Magic words:
1348               [INS] [DEL] String: theorem
1349               [INS] [DEL] String: theor.
1350               [INS] [DEL] String: th.
1351               [INS]
1352             [X] Make TOC entry    : [Value Menu] Level: -3
1353 @end example
1355 @vindex reftex-insert-label-flags
1356 @vindex reftex-label-menu-flags
1357 Depending on how you would like the label insertion and selection for
1358 the new environments to work, you might want to add the letters @samp{a}
1359 and @samp{h} to some of the flags in the variables
1360 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1361 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1362 Labels)}).
1365 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1366 @subsection Quick Equation Macro
1367 @cindex Quick equation macro
1368 @cindex Macros as environment wrappers
1370 Suppose you would like to have a macro for quick equations.  It
1371 could be defined like this:
1373 @example
1374 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1375 @end example
1377 @noindent
1378 and used like this:
1380 @example
1381 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1382 @end example
1384 We need to tell @RefTeX{} that any label defined in the argument of the
1385 @code{\quickeq} is an equation label.  Here is how to do this with lisp:
1387 @lisp
1388 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1389 @end lisp
1391 The first element in this list is now the macro with empty braces as an
1392 @emph{image} of the macro arguments.  @code{?e} indicates that this is
1393 an equation label, the different @code{nil} elements indicate to use the
1394 default values for equations.  The @samp{1} as the fifth element
1395 indicates that the context of the label definition should be the first
1396 argument of the macro.
1398 Here is again how this would look in the customization buffer:
1400 @example
1401 Reftex Label Alist: [Hide]
1402 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1403             Environment or \macro : [Value Menu] String: \quickeq@{@}
1404             Type specification    : [Value Menu] Char  : e
1405             Label prefix string   : [Value Menu] Default
1406             Label reference format: [Value Menu] Default
1407             Context method        : [Value Menu] Macro arg nr: 1
1408             Magic words:
1409               [INS]
1410             [ ] Make TOC entry    : [Value Menu] No entry
1411 @end example
1413 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1414 @subsection Figure Wrapping Macro
1415 @cindex Macros as environment wrappers
1416 @cindex Figure wrapping macro
1418 Suppose you want to make figures not directly with the figure
1419 environment, but with a macro like
1421 @example
1422 \newcommand@{\myfig@}[5][tbp]@{%
1423   \begin@{figure@}[#1]
1424     \epsimp[#5]@{#2@}
1425     \caption@{#3@}
1426     \label@{#4@}
1427   \end@{figure@}@}
1428 @end example
1430 @noindent
1431 which would be called like
1433 @example
1434 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1435 @end example
1437 Now we need to tell @RefTeX{} that the fourth argument of the
1438 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1439 the context.
1441 @lisp
1442 (setq reftex-label-alist
1443       '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1444 @end lisp
1446 The empty pairs of brackets indicate the different arguments of the
1447 @code{\myfig} macro. The @samp{*} marks the label argument.  @code{?f}
1448 indicates that this is a figure label which will be listed together with
1449 labels from normal figure environments.  The @code{nil} entries for
1450 prefix and reference format mean to use the defaults for figure labels.
1451 The @samp{3} for the context method means to grab the third macro argument:
1452 the caption.
1454 As a side effect of this configuration, @code{reftex-label} will now
1455 insert the required naked label (without the @code{\label} macro) when
1456 point is directly after the opening parenthesis of a @code{\myfig} macro
1457 argument.
1459 Again, here the configuration in the customization buffer:
1461 @example
1462 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1463             Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1464             Type specification    : [Value Menu] Char  : f
1465             Label prefix string   : [Value Menu] Default
1466             Label reference format: [Value Menu] Default
1467             Context method        : [Value Menu] Macro arg nr: 3
1468             Magic words:
1469               [INS]
1470             [ ] Make TOC entry    : [Value Menu] No entry
1471 @end example
1473 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1474 @subsection Adding Magic Words
1475 @cindex Magic words
1476 @cindex German magic words
1477 @cindex Label category
1479 Sometimes you don't want to define a new label environment or macro, but
1480 just change the information associated with a label category.  Maybe you
1481 want to add some magic words, for another language.  Changing only the
1482 information associated with a label category is done by giving
1483 @code{nil} for the environment name and then specify the items you want
1484 to define.  Here is an example which adds German magic words to all
1485 predefined label categories.
1487 @lisp
1488 (setq reftex-label-alist
1489   '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1490     (nil ?e nil nil nil ("Gleichung" "Gl."))
1491     (nil ?t nil nil nil ("Tabelle"))
1492     (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1493     (nil ?n nil nil nil ("Anmerkung" "Anm."))
1494     (nil ?i nil nil nil ("Punkt"))))
1495 @end lisp
1497 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1498 @subsection Using @code{\eqref}
1499 @cindex @code{\eqref}, AMS-LaTeX macro
1500 @cindex AMS-LaTeX
1501 @cindex Label category
1503 Another case where one only wants to change the information associated
1504 with the label category is to change the macro which is used for
1505 referencing the label.  When working with the AMS-@LaTeX{}, you might
1506 prefer @code{\eqref} for doing equation references.  Here is how to
1507 do this:
1509 @lisp
1510 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1511 @end lisp
1513 @RefTeX{} has also a predefined symbol for this special purpose.  The
1514 following is equivalent to the line above.
1516 @lisp
1517 (setq reftex-label-alist '(AMSTeX))
1518 @end lisp
1520 Note that this is automatically done by the @file{amsmath.el} style file
1521 of @AUCTeX{} (@pxref{Style Files}); so if you use @AUCTeX{},
1522 this configuration will not be necessary.
1524 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1525 @subsection Non-standard Environments
1526 @cindex Non-standard environments
1527 @cindex Environments without @code{\begin}
1528 @cindex Special parser functions
1529 @cindex Parser functions, for special environments
1531 Some @LaTeX{} packages define environment-like structures without using the
1532 standard @samp{\begin..\end} structure.  @RefTeX{} cannot parse
1533 these directly, but you can write your own special-purpose parser and
1534 use it instead of the name of an environment in an entry for
1535 @code{reftex-label-alist}.  The function should check if point is
1536 currently in the special environment it was written to detect.  If so,
1537 it must return a buffer position indicating the start of this
1538 environment.  The return value must be @code{nil} on failure to detect
1539 the environment.  The function is called with one argument @var{bound}.
1540 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1541 which should be observed.  We will discuss two examples.
1543 @cindex LaTeX commands, abbreviated
1545 Some people define abbreviations for
1546 environments, like @code{\be} for @code{\begin@{equation@}}, and
1547 @code{\ee} for @code{\end@{equation@}}.  The parser function would have
1548 to search backward for these macros.  When the first match is
1549 @code{\ee}, point is not in this environment.  When the first match is
1550 @code{\be}, point is in this environment and the function must return
1551 the beginning of the match.  To avoid scanning too far, we can also look
1552 for empty lines which cannot occur inside an equation environment.
1553 Here is the setup:
1555 @lisp
1556 ;; Setup entry in reftex-label-alist, using all defaults for equations
1557 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1559 (defun detect-be-ee (bound)
1560   ;; Search backward for the macros or an empty line
1561   (if (re-search-backward
1562        "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1563       (if (match-beginning 2)
1564           (match-beginning 2)  ; Return start of environment
1565         nil)                   ; Return nil because env is closed
1566     nil))                      ; Return nil for not found
1567 @end lisp
1569 @cindex @code{linguex}, LaTeX package
1570 @cindex LaTeX packages, @code{linguex}
1571 A more complex example is the @file{linguex.sty} package which defines
1572 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1573 terminated by @samp{\z.} or by an empty line.
1575 @example
1576 \ex.  \label@{ex:12@} Some text in an exotic language ...
1577       \a. \label@{ex:13@} more stuff
1578       \b. \label@{ex:14@} still more stuff
1579           \a. List on a deeper level
1580           \b. Another item
1581           \b. and the third one
1582       \z.
1583       \b. Third item on this level.
1585 ... text after the empty line terminating all lists
1586 @end example
1588 The difficulty is that the @samp{\a.} lists can nest and that an empty
1589 line terminates all list levels in one go.  So we have to count nesting
1590 levels between @samp{\a.} and @samp{\z.}.  Here is the implementation
1591 for @RefTeX{}.
1593 @lisp
1594 (setq reftex-label-alist
1595       '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1597 (defun detect-linguex (bound)
1598   (let ((cnt 0))
1599     (catch 'exit
1600       (while
1601           ;; Search backward for all possible delimiters
1602           (re-search-backward
1603            (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1604                    "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1605            nil t)
1606         ;; Check which delimiter was matched.
1607         (cond
1608          ((match-beginning 1)
1609           ;; empty line terminates all - return nil
1610           (throw 'exit nil))
1611          ((match-beginning 2)
1612           ;; \z. terminates one list level - decrease nesting count
1613           (decf cnt))
1614          ((match-beginning 3)
1615           ;; \ex. : return match unless there was a \z. on this level
1616           (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1617          ((match-beginning 4)
1618           ;; \a. : return match when on level 0, otherwise
1619           ;;       increment nesting count
1620           (if (>= cnt 0)
1621               (throw 'exit (match-beginning 4))
1622             (incf cnt))))))))
1623 @end lisp
1625 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1626 @subsection Putting it all together
1628 When you have to put several entries into @code{reftex-label-alist}, just
1629 put them after each other in a list, or create that many templates in
1630 the customization buffer.  Here is a lisp example which uses several of
1631 the entries described above:
1633 @lisp
1634 (setq reftex-label-alist
1635   '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
1636     ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "theor." "th.") -3)
1637     ("\\quickeq@{@}" ?e nil nil 1 nil)
1638     AMSTeX
1639     ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1640     (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1641 @end lisp
1643 @node Reference Info, Reference Styles, Defining Label Environments, Labels and References
1644 @section Reference Info
1645 @findex reftex-view-crossref
1646 @findex reftex-mouse-view-crossref
1647 @cindex Cross-references, displaying
1648 @cindex Reference info
1649 @cindex Displaying cross-references
1650 @cindex Viewing cross-references
1651 @kindex C-c &
1652 @kindex S-mouse-2
1654 When point is idle for more than @code{reftex-idle-time} seconds on the
1655 argument of a @code{\ref} macro, the echo area will display some
1656 information about the label referenced there.  Note that the information
1657 is only displayed if the echo area is not occupied by a different
1658 message.
1660 @RefTeX{} can also display the label definition corresponding to a
1661 @code{\ref} macro, or all reference locations corresponding to a
1662 @code{\label} macro.  @xref{Viewing Cross-References}, for more
1663 information.
1665 @node Reference Styles, xr (LaTeX package), Reference Info, Labels and References
1666 @section Reference Styles
1668 In case you defined your own macros for referencing or you are using
1669 @LaTeX{} packages providing specialized macros to be used instead of
1670 @code{\ref}, @RefTeX{} provides ways to select and insert them in a
1671 convenient way.
1673 @RefTeX{} comes equipped with a set of so-called reference styles where
1674 each relates to one or more reference macros.  The standard macros
1675 @samp{\ref} and @samp{\pageref} or provided by the ``Default'' style.
1676 The ``Varioref'' style offers macros for the @samp{varioref} @LaTeX{}
1677 package (@samp{\vref}, @samp{\Vref}, @samp{\Ref}, @samp{\vpageref}),
1678 ``Fancyref'' for the @samp{fancyref} package (@samp{\fref},
1679 @samp{\Fref}) and ``Hyperref'' for the @samp{hyperref} package
1680 (@samp{\autoref}, @samp{\autopageref}).
1682 @vindex reftex-ref-style-default-list
1683 A style can be toggled by selecting the respective entry in the
1684 @samp{Reference Style} menu.  Changes made through the menu will only
1685 last for the Emacs session.  In order to configure a preference
1686 permanently, the variable @code{reftex-ref-style-default-list} should be
1687 customized.  This variable specifies the list of styles to be activated.
1688 It can also be set as a file variable if the preference should be set
1689 for a specific file.
1691 @vindex reftex-ref-style-alist
1692 In case the built-in styles do not suffice, you can add additional
1693 macros and styles to the variable @code{reftex-ref-style-alist}.  Those
1694 do not necessarily have to be related to a certain @LaTeX{} package but
1695 can follow an arbitrary grouping rule.  For example you could define a
1696 style called ``Personal'' for your personal referencing macros.  (When
1697 changing the variable you should be aware that other Emacs packages,
1698 like @AUCTeX{}, might rely on the entries from the default value to be
1699 present.)
1701 Once a style is active the macros it relates to are available for
1702 selection when you are about to insert a reference.  In general this
1703 process involves three steps: the selection of a reference macro, a
1704 label type and a label.  Reference macros can be chosen in the first and
1705 last step.
1707 @vindex reftex-ref-macro-prompt
1708 In the first step you will be presented with a list of macros from which
1709 you can select one by typing a single key.  If you dislike having an
1710 extra step for reference macro selection, you can disable it by
1711 customizing @code{reftex-ref-macro-prompt} and relying only on the
1712 selection facilities provided in the last step.
1714 In the last step, i.e., the label selection, two key bindings are
1715 provided to set the reference macro.  Type @key{v} in order to cycle
1716 forward through the list of available macros or @key{V} to cycle
1717 backward.  The mode line of the selection buffer shows the macro
1718 currently selected.
1720 In case you are not satisfied with the order of macros when cycling
1721 through them you should adapt the order of entries in the variable
1722 @code{reftex-ref-style-alist} to fit your liking.
1724 For each entry in @code{reftex-ref-style-alist} a function with the name
1725 @code{reftex-<package>-<macro>} (e.g., @code{reftex-varioref-vref}) will
1726 be created automatically by @RefTeX{}.  These functions can be used
1727 instead of @kbd{C-c )} and provide an alternative way of having your
1728 favorite referencing macro preselected and if cycling through the macros
1729 seems inconvenient to you.@footnote{You could, e.g., bind
1730 @code{reftex-varioref-vref} to @kbd{C-c v} and
1731 @code{reftex-fancyref-fref} to @kbd{C-c f}.}
1733 @cindex @code{varioref}, LaTeX package
1734 @cindex LaTeX packages, @code{varioref}
1735 @cindex @code{fancyref}, LaTeX package
1736 @cindex LaTeX packages, @code{fancyref}
1737 @vindex reftex-vref-is-default (deprecated)
1738 @vindex reftex-fref-is-default (deprecated)
1739 In former versions of @RefTeX{} only support for @code{varioref} and
1740 @code{fancyref} was included.  @code{varioref} is a @LaTeX{} package to
1741 create cross-references with page information.  @code{fancyref} is a
1742 package where a macro call like @code{\fref@{@var{fig:map-of-germany}@}}
1743 creates not only the number of the referenced counter but also the
1744 complete text around it, like @samp{Figure 3 on the preceding page}.  In
1745 order to make it work you need to use label prefixes like @samp{fig:}
1746 consistently---something @RefTeX{} does automatically.  For each of
1747 these packages a variable could be configured to make its macros to take
1748 precedence over @code{\ref}.  Those were @code{reftex-vref-is-default}
1749 and @code{reftex-fref-is-default} respectively.  While still working,
1750 these variables are deprecated now.  Instead of setting them, the
1751 variable @code{reftex-ref-style-default-list} should be adapted now.
1753 @node xr (LaTeX package), , Reference Styles, Labels and References
1754 @section @code{xr}: Cross-Document References
1755 @cindex @code{xr}, LaTeX package
1756 @cindex LaTeX packages, @code{xr}
1757 @cindex @code{\externaldocument}
1758 @cindex External documents
1759 @cindex References to external documents
1760 @cindex Cross-document references
1762 The @LaTeX{} package @code{xr} makes it possible to create references to
1763 labels defined in external documents.  The preamble of a document using
1764 @code{xr} will contain something like this:
1766 @example
1767 \usepackage@{xr@}
1768 \externaldocument[V1-]@{volume1@}
1769 \externaldocument[V3-]@{volume3@}
1770 @end example
1772 @noindent
1773 and we can make references to any labels defined in these
1774 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1775 respectively.
1777 @RefTeX{} can be used to create such references as well.  Start the
1778 referencing process normally, by pressing @kbd{C-c )}.  Select a label
1779 type if necessary.  When you see the label selection buffer, pressing
1780 @kbd{x} will switch to the label selection buffer of one of the external
1781 documents.  You may then select a label as before and @RefTeX{} will
1782 insert it along with the required prefix.
1784 For this kind of inter-document cross-references, saving of parsing
1785 information and the use of multiple selection buffers can mean a large
1786 speed-up (@pxref{Optimizations}).
1788 @node Citations, Index Support, Labels and References, Top
1789 @chapter Citations
1790 @cindex Citations
1791 @cindex @code{\cite}
1793 Citations in @LaTeX{} are done with the @code{\cite} macro or variations of
1794 it.  The argument of the macro is a citation key which identifies an
1795 article or book in either a @BibTeX{} database file or in an explicit
1796 @code{thebibliography} environment in the document.  @RefTeX{}'s
1797 support for citations helps to select the correct key quickly.
1799 @menu
1800 * Creating Citations::               How to create them.
1801 * Citation Styles::                  Natbib, Harvard, Chicago and Co.
1802 * Citation Info::                    View the corresponding database entry.
1803 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
1804 * Citations Outside LaTeX::          How to make citations in Emails etc.
1805 * BibTeX Database Subsets::          Extract parts of a big database.
1806 @end menu
1808 @node Creating Citations, Citation Styles, , Citations
1809 @section Creating Citations
1810 @cindex Creating citations
1811 @cindex Citations, creating
1812 @findex reftex-citation
1813 @kindex C-c [
1814 @cindex Selection buffer, citations
1815 @cindex Selection process
1817 In order to create a citation, press @kbd{C-c [}.  @RefTeX{} then
1818 prompts for a regular expression which will be used to search through
1819 the database and present the list of matches to choose from in a
1820 selection process similar to that for selecting labels
1821 (@pxref{Referencing Labels}).
1823 The regular expression uses an extended syntax: @samp{&&} defines a
1824 logic @code{and} for regular expressions. For example
1825 @samp{Einstein&&Bose} will match all articles which mention
1826 Bose-Einstein condensation, or which are co-authored by Bose and
1827 Einstein.  When entering the regular expression, you can complete on
1828 known citation keys.  @RefTeX{} also offers a default when prompting for
1829 a regular expression.  This default is the word before the cursor or the
1830 word before the current @samp{\cite} command.  Sometimes this may be a
1831 good search key.
1833 @cindex @code{\bibliography}
1834 @cindex @code{thebibliography}, LaTeX environment
1835 @cindex @code{BIBINPUTS}, environment variable
1836 @cindex @code{TEXBIB}, environment variable
1837 @RefTeX{} prefers to use @BibTeX{} database files specified with a
1838 @code{\bibliography} macro to collect its information.  Just like
1839 @BibTeX{}, it will search for the specified files in the current directory
1840 and along the path given in the environment variable @code{BIBINPUTS}.
1841 If you do not use @BibTeX{}, but the document contains an explicit
1842 @code{thebibliography} environment, @RefTeX{} will collect its
1843 information from there.  Note that in this case the information
1844 presented in the selection buffer will just be a copy of relevant
1845 @code{\bibitem} entries, not the structured listing available with
1846 @BibTeX{} database files.
1848 @kindex ?
1849 In the selection buffer, the following keys provide special commands.  A
1850 summary of this information is always available from the selection
1851 process by pressing @kbd{?}.
1853 @table @kbd
1854 @tablesubheading{General}
1855 @item ?
1856 Show a summary of available commands.
1858 @item 0-9,-
1859 Prefix argument.
1861 @tablesubheading{Moving around}
1862 @item n
1863 Go to next article.
1865 @item p
1866 Go to previous article.
1868 @tablesubheading{Access to full database entries}
1869 @item @key{SPC}
1870 Show the database entry corresponding to the article at point, in
1871 another window.  See also the @kbd{f} key.
1873 @item f
1874 Toggle follow mode.  When follow mode is active, the other window will
1875 always display the full database entry of the current article.  This is
1876 equivalent to pressing @key{SPC} after each cursor motion.  With @BibTeX{}
1877 entries, follow mode can be rather slow.
1879 @tablesubheading{Selecting entries and creating the citation}
1880 @item @key{RET}
1881 Insert a citation referencing the article at point into the buffer from
1882 which the selection process was started.
1884 @item mouse-2
1885 @vindex reftex-highlight-selection
1886 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1887 would.  See also variable @code{reftex-highlight-selection}, @ref{Options
1888 (Misc)}.
1890 @item m
1891 Mark the current entry.  When one or several entries are marked,
1892 pressing @kbd{a} or @kbd{A} accepts all marked entries.  Also,
1893 @key{RET} behaves like the @kbd{a} key.
1895 @item u
1896 Unmark a marked entry.
1898 @item a
1899 Accept all (marked) entries in the selection buffer and create a single
1900 @code{\cite} macro referring to them.
1902 @item A
1903 Accept all (marked) entries in the selection buffer and create a
1904 separate @code{\cite} macro for each of it.
1906 @item e
1907 Create a new @BibTeX{} database file which contains all @i{marked} entries
1908 in the selection buffer.  If no entries are marked, all entries are
1909 selected.
1911 @item E
1912 Create a new @BibTeX{} database file which contains all @i{unmarked}
1913 entries in the selection buffer.  If no entries are marked, all entries
1914 are selected.
1916 @item @key{TAB}
1917 Enter a citation key with completion.  This may also be a key which does
1918 not yet exist.
1920 @item .
1921 Show insertion point in another window.  This is the point from where you
1922 called @code{reftex-citation}.
1924 @tablesubheading{Exiting}
1925 @item q
1926 Exit the selection process without inserting a citation into the
1927 buffer.
1929 @tablesubheading{Updating the buffer}
1931 @item g
1932 Start over with a new regular expression.  The full database will be
1933 rescanned with the new expression (see also @kbd{r}).
1935 @c FIXME: Should we use something else here? r is usually rescan!
1936 @item r
1937 Refine the current selection with another regular expression.  This will
1938 @emph{not} rescan the entire database, but just the already selected
1939 entries.
1941 @end table
1943 @vindex reftex-select-bib-map
1944 In order to define additional commands for this selection process, the
1945 keymap @code{reftex-select-bib-map} may be used.
1947 Note that if you do not use Emacs to edit the @BibTeX{} database files,
1948 @RefTeX{} will ask if the related buffers should be updated once it
1949 detects that the files were changed externally.  If you do not want to
1950 be bothered by such queries, you can activate Auto Revert mode for these
1951 buffers by adding the following expression to your init file:
1953 @lisp
1954 (add-hook 'bibtex-mode-hook 'turn-on-auto-revert-mode)
1955 @end lisp
1958 @node Citation Styles, Citation Info, Creating Citations, Citations
1959 @section Citation Styles
1960 @cindex Citation styles
1961 @cindex Citation styles, @code{natbib}
1962 @cindex Citation styles, @code{harvard}
1963 @cindex Citation styles, @code{chicago}
1964 @cindex Citation styles, @code{jurabib}
1965 @cindex Citation styles, @ConTeXt{}
1966 @cindex @code{natbib}, citation style
1967 @cindex @code{harvard}, citation style
1968 @cindex @code{chicago}, citation style
1969 @cindex @code{jurabib}, citation style
1970 @cindex @ConTeXt{}, citation style
1972 @vindex reftex-cite-format
1973 The standard @LaTeX{} macro @code{\cite} works well with numeric or
1974 simple key citations.  To deal with the more complex task of author-year
1975 citations as used in many natural sciences, a variety of packages has
1976 been developed which define derived forms of the @code{\cite} macro.
1977 @RefTeX{} can be configured to produce these citation macros as well by
1978 setting the variable @code{reftex-cite-format}.  For the most commonly
1979 used @LaTeX{} packages (@code{natbib}, @code{harvard}, @code{chicago},
1980 @code{jurabib}) and for @ConTeXt{} this may be done from the menu, under
1981 @code{Ref->Citation Styles}.  Since there are usually several macros to
1982 create the citations, executing @code{reftex-citation} (@kbd{C-c [})
1983 starts by prompting for the correct macro.  For the Natbib style, this
1984 looks like this:
1986 @example
1987 SELECT A CITATION FORMAT
1989 [^M]   \cite@{%l@}
1990 [t]    \citet@{%l@}
1991 [T]    \citet*@{%l@}
1992 [p]    \citep@{%l@}
1993 [P]    \citep*@{%l@}
1994 [e]    \citep[e.g.][]@{%l@}
1995 [s]    \citep[see][]@{%l@}
1996 [a]    \citeauthor@{%l@}
1997 [A]    \citeauthor*@{%l@}
1998 [y]    \citeyear@{%l@}
1999 @end example
2001 @vindex reftex-cite-prompt-optional-args
2002 If citation formats contain empty pairs of square brackets, @RefTeX{}
2003 will prompt for values of these optional arguments if you call the
2004 @code{reftex-citation} command with a @kbd{C-u} prefix.
2005 Following the most generic of these packages, @code{natbib}, the builtin
2006 citation packages always accept the @kbd{t} key for a @emph{textual}
2007 citation (like: @code{Jones et al. (1997) have shown...})  as well as
2008 the @kbd{p} key for a parenthetical citation (like: @code{As shown
2009 earlier (Jones et al, 1997)}).
2011 To make one of these styles the default, customize the variable
2012 @code{reftex-cite-format} or put into @file{.emacs}:
2014 @lisp
2015 (setq reftex-cite-format 'natbib)
2016 @end lisp
2018 You can also use @AUCTeX{} style files to automatically set the
2019 citation style based on the @code{usepackage} commands in a given
2020 document.  @xref{Style Files}, for information on how to set up the style
2021 files correctly.
2023 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations
2024 @section Citation Info
2025 @cindex Displaying citations
2026 @cindex Citations, displaying
2027 @cindex Citation info
2028 @cindex Viewing citations
2029 @kindex C-c &
2030 @kindex S-mouse-2
2031 @findex reftex-view-crossref
2032 @findex reftex-mouse-view-crossref
2034 When point is idle for more than @code{reftex-idle-time} seconds on the
2035 argument of a @code{\cite} macro, the echo area will display some
2036 information about the article cited there.  Note that the information is
2037 only displayed if the echo area is not occupied by a different message.
2039 @RefTeX{} can also display the @code{\bibitem} or @BibTeX{} database
2040 entry corresponding to a @code{\cite} macro, or all citation locations
2041 corresponding to a @code{\bibitem} or @BibTeX{} database entry.
2042 @xref{Viewing Cross-References}.
2044 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
2045 @section Chapterbib and Bibunits
2046 @cindex @code{chapterbib}, LaTeX package
2047 @cindex @code{bibunits}, LaTeX package
2048 @cindex Bibliographies, multiple
2050 @code{chapterbib} and @code{bibunits} are two @LaTeX{} packages which
2051 produce multiple bibliographies in a document.  This is no problem for
2052 @RefTeX{} as long as all bibliographies use the same @BibTeX{} database
2053 files.  If they do not, it is best to have each document part in a
2054 separate file (as it is required for @code{chapterbib} anyway).  Then
2055 @RefTeX{} will still scan the locally relevant databases correctly.  If
2056 you have multiple bibliographies within a @emph{single file}, this may
2057 or may not be the case.
2059 @node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations
2060 @section Citations outside @LaTeX{}
2061 @cindex Citations outside LaTeX
2062 @vindex reftex-default-bibliography
2064 The command @code{reftex-citation} can also be executed outside a @LaTeX{}
2065 buffer.  This can be useful to reference articles in the mail buffer and
2066 other documents.  You should @emph{not} enter @code{reftex-mode} for
2067 this, just execute the command.  The list of @BibTeX{} files will in this
2068 case be taken from the variable @code{reftex-default-bibliography}.
2069 Setting the variable @code{reftex-cite-format} to the symbol
2070 @code{locally} does a decent job of putting all relevant information
2071 about a citation directly into the buffer.  Here is the lisp code to add
2072 the @kbd{C-c [} binding to the mail buffer.  It also provides a local
2073 binding for @code{reftex-cite-format}.
2075 @lisp
2076 (add-hook 'mail-setup-hook
2077           (lambda () (define-key mail-mode-map "\C-c["
2078                        (lambda ()
2079                          (interactive)
2080                          (let ((reftex-cite-format 'locally))
2081                            (reftex-citation))))))
2082 @end lisp
2084 @node BibTeX Database Subsets, , Citations Outside LaTeX, Citations
2085 @section Database Subsets
2086 @cindex BibTeX database subsets
2087 @findex reftex-create-bibtex-file
2089 @RefTeX{} offers two ways to create a new @BibTeX{} database file.
2091 The first option produces a file which contains only the entries
2092 actually referenced in the current document.  This can be useful if
2093 the database is only meant for a single document and you want to clean
2094 it of old and unused ballast.  It can also be useful while writing a
2095 document together with collaborators, in order to avoid sending around
2096 the entire (possibly very large) database.  To create the file, use
2097 @kbd{M-x reftex-create-bibtex-file}, also available from the menu
2098 under @code{Ref->Global Actions->Create Bibtex File}.  The command will
2099 prompt for a @BibTeX{} file name and write the extracted entries to that
2100 file.
2102 The second option makes use of the selection process started by the
2103 command @kbd{C-c [} (@pxref{Creating Citations}).  This command uses a
2104 regular expression to select entries, and lists them in a formatted
2105 selection buffer.  After pressing the @kbd{e} key (mnemonics: Export),
2106 the command will prompt for the name of a new @BibTeX{} file and write
2107 the selected entries to that file.  You can also first mark some
2108 entries in the selection buffer with the @kbd{m} key and then export
2109 either the @i{marked} entries (with the @kbd{e} key) or the
2110 @i{unmarked} entries (with the @kbd{E} key).
2112 @node Index Support, Viewing Cross-References, Citations, Top
2113 @chapter Index Support
2114 @cindex Index Support
2115 @cindex @code{\index}
2117 @LaTeX{} has builtin support for creating an Index.  The @LaTeX{} core
2118 supports two different indices, the standard index and a glossary.  With
2119 the help of special @LaTeX{} packages (@file{multind.sty} or
2120 @file{index.sty}), any number of indices can be supported.
2122 Index entries are created with the @code{\index@{@var{entry}@}} macro.
2123 All entries defined in a document are written out to the @file{.aux}
2124 file.  A separate tool must be used to convert this information into a
2125 nicely formatted index.  Tools used with @LaTeX{} include @code{MakeIndex}
2126 and @code{xindy}.
2128 Indexing is a very difficult task.  It must follow strict conventions to
2129 make the index consistent and complete.  There are basically two
2130 approaches one can follow, and both have their merits.
2132 @enumerate
2133 @item
2134 Part of the indexing should already be done with the markup.  The
2135 document structure should be reflected in the index, so when starting
2136 new sections, the basic topics of the section should be indexed.  If the
2137 document contains definitions, theorems or the like, these should all
2138 correspond to appropriate index entries.  This part of the index can
2139 very well be developed along with the document.  Often it is worthwhile
2140 to define special purpose macros which define an item and at the same
2141 time make an index entry, possibly with special formatting to make the
2142 reference page in the index bold or underlined.  To make @RefTeX{}
2143 support for indexing possible, these special macros must be added to
2144 @RefTeX{}'s configuration (@pxref{Defining Index Macros}).
2146 @item
2147 The rest of the index is often just a collection of where in the
2148 document certain words or phrases are being used.  This part is
2149 difficult to develop along with the document, because consistent entries
2150 for each occurrence are needed and are best selected when the document
2151 is ready.  @RefTeX{} supports this with an @emph{index phrases file}
2152 which collects phrases and helps indexing the phrases globally.
2153 @end enumerate
2155 Before you start, you need to make sure that @RefTeX{} knows about
2156 the index style being used in the current document.  @RefTeX{} has
2157 builtin support for the default @code{\index} and @code{\glossary}
2158 macros.  Other @LaTeX{} packages, like the @file{multind} or @file{index}
2159 package, redefine the @code{\index} macro to have an additional
2160 argument, and @RefTeX{} needs to be configured for those.  A
2161 sufficiently new version of @AUCTeX{} (9.10c or later) will do this
2162 automatically.  If you really don't use @AUCTeX{} (you should!), this
2163 configuration needs to be done by hand with the menu (@code{Ref->Index
2164 Style}), or globally for all your documents with
2166 @lisp
2167 (setq reftex-index-macros '(multind))     @r{or}
2168 (setq reftex-index-macros '(index))
2169 @end lisp
2171 @menu
2172 * Creating Index Entries::           Macros and completion of entries.
2173 * The Index Phrases File::           A special file for global indexing.
2174 * Displaying and Editing the Index:: The index editor.
2175 * Builtin Index Macros::             The index macros RefTeX knows about.
2176 * Defining Index Macros::                ... and macros it  doesn't.
2177 @end menu
2179 @node Creating Index Entries, The Index Phrases File, , Index Support
2180 @section Creating Index Entries
2181 @cindex Creating index entries
2182 @cindex Index entries, creating
2183 @kindex C-c <
2184 @findex reftex-index
2185 @kindex C-c /
2186 @findex reftex-index-selection-or-word
2188 In order to index the current selection or the word at the cursor press
2189 @kbd{C-c /} (@code{reftex-index-selection-or-word}).  This causes the
2190 selection or word @samp{@var{word}} to be replaced with
2191 @samp{\index@{@var{word}@}@var{word}}.  The macro which is used
2192 (@code{\index} by default) can be configured with the variable
2193 @code{reftex-index-default-macro}.  When the command is called with a
2194 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
2195 generated index entry.  Use this to change the case of the word or to
2196 make the entry a subentry, for example by entering
2197 @samp{main!sub!@var{word}}.  When called with two raw @kbd{C-u} prefixes
2198 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
2199 When there is nothing selected and no word at point, this command will
2200 just call @code{reftex-index}, described below.
2202 In order to create a general index entry, press @kbd{C-c <}
2203 (@code{reftex-index}).  @RefTeX{} will prompt for one of the
2204 available index macros and for its arguments.  Completion will be
2205 available for the index entry and, if applicable, the index tag.  The
2206 index tag is a string identifying one of multiple indices.  With the
2207 @file{multind} and @file{index} packages, this tag is the first argument
2208 to the redefined @code{\index} macro.
2210 @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
2211 @section The Index Phrases File
2212 @cindex Index phrase file
2213 @cindex Phrase file
2214 @kindex C-c |
2215 @findex reftex-index-visit-phrases-buffer
2216 @cindex Macro definition lines, in phrase buffer
2218 @RefTeX{} maintains a file in which phrases can be collected for
2219 later indexing.  The file is located in the same directory as the master
2220 file of the document and has the extension @file{.rip} (@b{R}eftex
2221 @b{I}ndex @b{P}hrases).  You can create or visit the file with @kbd{C-c
2222 |} (@code{reftex-index-visit-phrases-buffer}).  If the file is empty it
2223 is initialized by inserting a file header which contains the definition
2224 of the available index macros.  This list is initialized from
2225 @code{reftex-index-macros} (@pxref{Defining Index Macros}).  You can
2226 edit the header as needed, but if you define new @LaTeX{} indexing macros,
2227 don't forget to add them to @code{reftex-index-macros} as well.  Here is
2228 a phrase file header example:
2230 @example
2231 % -*- mode: reftex-index-phrases -*-
2232 %                           Key   Macro Format       Repeat
2233 %----------------------------------------------------------
2234 >>>INDEX_MACRO_DEFINITION:   i    \index@{%s@}          t
2235 >>>INDEX_MACRO_DEFINITION:   I    \index*@{%s@}         nil
2236 >>>INDEX_MACRO_DEFINITION:   g    \glossary@{%s@}       t
2237 >>>INDEX_MACRO_DEFINITION:   n    \index*[name]@{%s@}   nil
2238 %----------------------------------------------------------
2239 @end example
2241 The macro definition lines consist of a unique letter identifying a
2242 macro, a format string and the @var{repeat} flag, all separated by
2243 @key{TAB}.  The format string shows how the macro is to be applied, the
2244 @samp{%s} will be replaced with the index entry.  The repeat flag
2245 indicates if @var{word} is indexed by the macro as
2246 @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
2247 @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}).  In the
2248 above example it is assumed that the macro @code{\index*@{@var{word}@}}
2249 already typesets its argument in the text, so that it is unnecessary to
2250 repeat @var{word} outside the macro.
2252 @menu
2253 * Collecting Phrases::               Collecting from document or external.
2254 * Consistency Checks::               Check for duplicates etc.
2255 * Global Indexing::                  The interactive indexing process.
2256 @end menu
2258 @node Collecting Phrases, Consistency Checks, , The Index Phrases File
2259 @subsection Collecting Phrases
2260 @cindex Collecting index phrases
2261 @cindex Index phrases, collection
2262 @cindex Phrases, collecting
2264 Phrases for indexing can be collected while writing the document.  The
2265 command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2266 copies the current selection (if active) or the word near point into the
2267 phrases buffer.  It then selects this buffer, so that the phrase line
2268 can be edited.  To return to the @LaTeX{} document, press @kbd{C-c C-c}
2269 (@code{reftex-index-phrases-save-and-return}).
2271 You can also prepare the list of index phrases in a different way and
2272 copy it into the phrases file.  For example you might want to start from
2273 a word list of the document and remove all words which should not be
2274 indexed.
2276 The phrase lines in the phrase buffer must have a specific format.
2277 @RefTeX{} will use font-lock to indicate if a line has the proper
2278 format.  A phrase line looks like this:
2280 @example
2281 [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
2282 @end example
2284 @code{<TABs>} stands for white space containing at least one @key{TAB}.
2285 @var{key} must be at the start of the line and is the character
2286 identifying one of the macros defined in the file header.  It is
2287 optional; when omitted, the first macro definition line in the file
2288 will be used for this phrase.  The @var{phrase} is the phrase to be
2289 searched for when indexing.  It may contain several words separated by
2290 spaces.  By default the search phrase is also the text entered as
2291 argument of the index macro.  If you want the index entry to be
2292 different from the search phrase, enter another @key{TAB} and the index
2293 argument @var{arg}.  If you want to have each match produce several
2294 index entries, separate the different index arguments with @samp{ &&
2295 }@footnote{@samp{&&} with optional spaces, see
2296 @code{reftex-index-phrases-logical-and-regexp}.}.  If you want to be
2297 able to choose at each match between several different index arguments,
2298 separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2299 see @code{reftex-index-phrases-logical-or-regexp}.}.  Here is an
2300 example:
2302 @example
2303 %--------------------------------------------------------------------
2304 I     Sun
2305 i     Planet         Planets
2306 i     Vega           Stars!Vega
2307       Jupiter        Planets!Jupiter
2308 i     Mars           Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2309 i     Pluto          Planets!Pluto && Kuiper Belt Objects!Pluto
2310 @end example
2313 So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2314 @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2315 @samp{Vega} will be indexed as a subitem of @samp{Stars}.  The
2316 @samp{Jupiter} line will also use the @samp{i} macro as it was the first
2317 macro definition in the file header (see above example).  At each
2318 occurrence of @samp{Mars} you will be able choose between indexing it as
2319 a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2320 Finally, every occurrence of @samp{Pluto} will be indexed as
2321 @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2322 and will therefore create two different index entries.
2324 @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
2325 @subsection Consistency Checks
2326 @cindex Index phrases, consistency checks
2327 @cindex Phrases, consistency checks
2328 @cindex Consistency check for index phrases
2330 @kindex C-c C-s
2331 Before indexing the phrases in the phrases buffer, they should be
2332 checked carefully for consistency.  A first step is to sort the phrases
2333 alphabetically; this is done with the command @kbd{C-c C-s}
2334 (@code{reftex-index-sort-phrases}).  It will sort all phrases in the
2335 buffer alphabetically by search phrase.  If you want to group certain
2336 phrases and only sort within the groups, insert empty lines between the
2337 groups.  Sorting will only change the sequence of phrases within each
2338 group (see the variable @code{reftex-index-phrases-sort-in-blocks}).
2340 @kindex C-c C-i
2341 A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2342 which lists information about the phrase at point, including an example
2343 of how the index entry will look like and the number of expected matches
2344 in the document.
2346 @kindex C-c C-t
2347 Another important check is to find out if there are double or
2348 overlapping entries in the buffer.  For example if you are first
2349 searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2350 second phrase will not match because of the index macro inserted before
2351 @samp{Mars} earlier.  The command @kbd{C-c C-t}
2352 (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2353 the buffer which is either duplicate or a subphrase of another phrase.
2354 In order to check the whole buffer like this, start at the beginning and
2355 execute this command repeatedly.
2357 @node Global Indexing, , Consistency Checks, The Index Phrases File
2358 @subsection Global Indexing
2359 @cindex Global indexing
2360 @cindex Indexing, global
2361 @cindex Indexing, from @file{phrases} buffer
2363 Once the index phrases have been collected and organized, you are set
2364 for global indexing.  I recommend to do this only on an otherwise
2365 finished document.  Global indexing starts from the phrases buffer.
2366 There are several commands which start indexing: @kbd{C-c C-x} acts on
2367 the current phrase line, @kbd{C-c C-r} on all lines in the current
2368 region and @kbd{C-c C-a} on all phrase lines in the buffer.  It is
2369 probably good to do indexing in small chunks since your concentration
2370 may not last long enough to do everything in one go.
2372 @RefTeX{} will start at the first phrase line and search the phrase
2373 globally in the whole document.  At each match it will stop, compute the
2374 replacement string and offer you the following choices@footnote{Windows
2375 users: Restrict yourself to the described keys during indexing.  Pressing
2376 @key{Help} at the indexing prompt can apparently hang Emacs.}:
2378 @table @kbd
2379 @item y
2380 Replace this match with the proposed string.
2381 @item n
2382 Skip this match.
2383 @item !
2384 Replace this and all further matches in this file.
2385 @item q
2386 Skip this match, start with next file.
2387 @item Q
2388 Skip this match, start with next phrase.
2389 @item o
2390 Select a different indexing macro for this match.
2391 @item 1-9
2392 Select one of multiple index keys (those separated with @samp{||}).
2393 @item e
2394 Edit the replacement text.
2395 @item C-r
2396 Recursive edit.  Use @kbd{C-M-c} to return to the indexing process.
2397 @item s
2398 Save this buffer and ask again about the current match.
2399 @item S
2400 Save all document buffers and ask again about the current match.
2401 @item C-g
2402 Abort the indexing process.
2403 @end table
2405 The @samp{Find and Index in Document} menu in the phrases buffer also
2406 lists a few options for the indexing process.  The options have
2407 associated customization variables to set the defaults (@pxref{Options
2408 (Index Support)}).  Here is a short explanation of what the options do:
2410 @table @i
2411 @item Match Whole Words
2412 When searching for index phrases, make sure whole words are matched.
2413 This should probably always be on.
2414 @item Case Sensitive Search
2415 Search case sensitively for phrases.  I recommend to have this setting
2416 off, in order to match the capitalized words at the beginning of a
2417 sentence, and even typos.  You can always say @emph{no} at a match you
2418 do not like.
2419 @item Wrap Long Lines
2420 Inserting index macros increases the line length.  Turn this option on
2421 to allow @RefTeX{} to wrap long lines.
2422 @item Skip Indexed Matches
2423 When this is on, @RefTeX{} will at each match try to figure out if
2424 this match is already indexed.  A match is considered indexed if it is
2425 either the argument of an index macro, or if an index macro is directly
2426 (without whitespace separation) before or after the match.  Index macros
2427 are those configured in @code{reftex-index-macros}.  Intended for
2428 re-indexing a documents after changes have been made.
2429 @end table
2431 Even though indexing should be the last thing you do to a document, you
2432 are bound to make changes afterwards.  Indexing then has to be applied
2433 to the changed regions.  The command
2434 @code{reftex-index-phrases-apply-to-region} is designed for this
2435 purpose.  When called from a @LaTeX{} document with active region, it will
2436 apply @code{reftex-index-all-phrases} to the current region.
2438 @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
2439 @section Displaying and Editing the Index
2440 @cindex Displaying the Index
2441 @cindex Editing the Index
2442 @cindex Index entries, creating
2443 @cindex Index, displaying
2444 @cindex Index, editing
2445 @kindex C-c >
2446 @findex reftex-display-index
2448 In order to compile and display the index, press @kbd{C-c >}.  If the
2449 document uses multiple indices, @RefTeX{} will ask you to select
2450 one.  Then, all index entries will be sorted alphabetically and
2451 displayed in a special buffer, the @file{*Index*} buffer.  From that
2452 buffer you can check and edit each entry.
2454 The index can be restricted to the current section or the region.  Then
2455 only entries in that part of the document will go into the compiled
2456 index.  To restrict to the current section, use a numeric prefix
2457 @samp{2}, thus press @kbd{C-u 2 C-c >}.  To restrict to the current
2458 region, make the region active and use a numeric prefix @samp{3} (press
2459 @kbd{C-u 3 C-c >}).  From within the @file{*Index*} buffer the
2460 restriction can be moved from one section to the next by pressing the
2461 @kbd{<} and @kbd{>} keys.
2463 One caveat: @RefTeX{} finds the definition point of an index entry
2464 by searching near the buffer position where it had found to macro during
2465 scanning.  If you have several identical index entries in the same
2466 buffer and significant changes have shifted the entries around, you must
2467 rescan the buffer to ensure the correspondence between the
2468 @file{*Index*} buffer and the definition locations.  It is therefore
2469 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2470 frequently while editing the index from the @file{*Index*}
2471 buffer.
2473 @kindex ?
2474 Here is a list of special commands available in the @file{*Index*} buffer.  A
2475 summary of this information is always available by pressing
2476 @kbd{?}.
2478 @table @kbd
2479 @tablesubheading{General}
2480 @item ?
2481 Display a summary of commands.
2483 @item 0-9, -
2484 Prefix argument.
2486 @tablesubheading{Moving around}
2487 @item ! A..Z
2488 Pressing any capital letter will jump to the corresponding section in
2489 the @file{*Index*} buffer.  The exclamation mark is special and jumps to
2490 the first entries alphabetically sorted below @samp{A}.  These are
2491 usually non-alphanumeric characters.
2492 @item n
2493 Go to next entry.
2494 @item p
2495 Go to previous entry.
2497 @tablesubheading{Access to document locations}
2498 @item @key{SPC}
2499 Show the place in the document where this index entry is defined.
2501 @item @key{TAB}
2502 Go to the definition of the current index entry in another
2503 window.
2505 @item @key{RET}
2506 Go to the definition of the current index entry and hide the
2507 @file{*Index*} buffer window.
2509 @item f
2510 @vindex reftex-index-follow-mode
2511 @vindex reftex-revisit-to-follow
2512 Toggle follow mode.  When follow mode is active, the other window will
2513 always show the location corresponding to the line in the @file{*Index*}
2514 buffer at point.  This is similar to pressing @key{SPC} after each
2515 cursor motion.  The default for this flag can be set with the variable
2516 @code{reftex-index-follow-mode}.  Note that only context in files
2517 already visited is shown.  @RefTeX{} will not visit a file just for
2518 follow mode.  See, however, the variable
2519 @code{reftex-revisit-to-follow}.
2521 @tablesubheading{Entry editing}
2522 @item e
2523 Edit the current index entry.  In the minibuffer, you can edit the
2524 index macro which defines this entry.
2526 @item C-k
2527 Kill the index entry.  Currently not implemented because I don't know
2528 how to implement an @code{undo} function for this.
2530 @item *
2531 Edit the @var{key} part of the entry.  This is the initial part of the
2532 entry which determines the location of the entry in the index.
2534 @item |
2535 Edit the @var{attribute} part of the entry.  This is the part after the
2536 vertical bar.  With @code{MakeIndex}, this part is an encapsulating
2537 macro.  With @code{xindy}, it is called @emph{attribute} and is a
2538 property of the index entry that can lead to special formatting.  When
2539 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2540 part.
2542 @item @@
2543 Edit the @var{visual} part of the entry.  This is the part after the
2544 @samp{@@} which is used by @code{MakeIndex} to change the visual
2545 appearance of the entry in the index.  When called with @kbd{C-u}
2546 prefix, kill the entire @var{visual} part.
2548 @item (
2549 Toggle the beginning of page range property @samp{|(} of the
2550 entry.
2552 @item )
2553 Toggle the end of page range property @samp{|)} of the entry.
2555 @item _
2556 Make the current entry a subentry.  This command will prompt for the
2557 superordinate entry and insert it.
2559 @item ^
2560 Remove the highest superordinate entry.  If the current entry is a
2561 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2562 (@samp{bbb!ccc}).
2564 @tablesubheading{Exiting}
2565 @item q
2566 Hide the @file{*Index*} buffer.
2568 @item k
2569 Kill the @file{*Index*} buffer.
2571 @item C-c =
2572 Switch to the Table of Contents buffer of this document.
2574 @tablesubheading{Controlling what gets displayed}
2575 @item c
2576 @vindex reftex-index-include-context
2577 Toggle the display of short context in the @file{*Index*} buffer.  The
2578 default for this flag can be set with the variable
2579 @code{reftex-index-include-context}.
2581 @item @}
2582 Restrict the index to a single document section.  The corresponding
2583 section number will be displayed in the @code{R<>} indicator in the
2584 mode line and in the header of the @file{*Index*} buffer.
2586 @item @{
2587 Widen the index to contain all entries of the document.
2589 @item <
2590 When the index is currently restricted, move the restriction to the
2591 previous section.
2593 @item >
2594 When the index is currently restricted, move the restriction to the
2595 next section.
2597 @tablesubheading{Updating the buffer}
2598 @item g
2599 Rebuild the @file{*Index*} buffer.  This does @emph{not} rescan the
2600 document.  However, it sorts the entries again, so that edited entries
2601 will move to the correct position.
2603 @item r
2604 @vindex reftex-enable-partial-scans
2605 Reparse the @LaTeX{} document and rebuild the @file{*Index*} buffer.  When
2606 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
2607 location is defined in, not the entire document.
2609 @item C-u r
2610 Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*Index*}
2611 buffer.
2613 @item s
2614 Switch to a different index (for documents with multiple
2615 indices).
2616 @end table
2619 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2620 @section Builtin Index Macros
2621 @cindex Builtin index macros
2622 @cindex Index macros, builtin
2623 @vindex reftex-index-macros
2624 @cindex @code{multind}, LaTeX package
2625 @cindex @code{index}, LaTeX package
2626 @cindex LaTeX packages, @code{multind}
2627 @cindex LaTeX packages, @code{index}
2629 @RefTeX{} by default recognizes the @code{\index} and
2630 @code{\glossary} macros which are defined in the @LaTeX{} core.  It has
2631 also builtin support for the re-implementations of @code{\index}
2632 in the @file{multind} and @file{index} packages.  However, since
2633 the different definitions of the @code{\index} macro are incompatible,
2634 you will have to explicitly specify the index style used.
2635 @xref{Creating Index Entries}, for information on how to do that.
2637 @node Defining Index Macros, , Builtin Index Macros, Index Support
2638 @section Defining Index Macros
2639 @cindex  Defining Index Macros
2640 @cindex Index macros, defining
2641 @vindex reftex-index-macros
2643 When writing a document with an index you will probably define
2644 additional macros which make entries into the index.
2645 Let's look at an example.
2647 @example
2648 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2649 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2650 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2651 @end example
2653 The first macro @code{\ix} typesets its argument in the text and places
2654 it into the index.  The second macro @code{\nindex} typesets its
2655 argument in the text and places it into a separate index with the tag
2656 @samp{name}@footnote{We are using the syntax of the @file{index} package
2657 here.}.  The last macro also places its argument into the index, but as
2658 subitems under the main index entry @samp{Astronomical Objects}.  Here
2659 is how to make @RefTeX{} recognize and correctly interpret these
2660 macros, first with Emacs Lisp.
2662 @lisp
2663 (setq reftex-index-macros
2664       '(("\\ix@{*@}" "idx" ?x "" nil nil)
2665         ("\\nindex@{*@}" "name" ?n "" nil nil)
2666         ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2667 @end lisp
2669 Note that the index tag is @samp{idx} for the main index, and
2670 @samp{name} for the name index.  @samp{idx} and @samp{glo} are reserved
2671 for the default index and for the glossary.
2673 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2674 quick identification of these macros when @RefTeX{} inserts new
2675 index entries with @code{reftex-index}.  These codes need to be
2676 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2677 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2678 respectively.
2680 The following string is empty unless your macro adds a superordinate
2681 entry to the index key; this is the case for the @code{\astobj} macro.
2683 The next entry can be a hook function to exclude certain matches, it
2684 almost always can be @code{nil}.
2686 The final element in the list indicates if the text being indexed needs
2687 to be repeated outside the macro.  For the normal index macros, this
2688 should be @code{t}.  Only if the macro typesets the entry in the text
2689 (like @code{\ix} and @code{\nindex} in the example do), this should be
2690 @code{nil}.
2692 To do the same thing with customize, you need to fill in the templates
2693 like this:
2695 @example
2696 Repeat:
2697 [INS] [DEL] List:
2698             Macro with args: \ix@{*@}
2699             Index Tag      : [Value Menu] String: idx
2700             Access Key     : x
2701             Key Prefix     :
2702             Exclusion hook : nil
2703             Repeat Outside : [Toggle]  off (nil)
2704 [INS] [DEL] List:
2705             Macro with args: \nindex@{*@}
2706             Index Tag      : [Value Menu] String: name
2707             Access Key     : n
2708             Key Prefix     :
2709             Exclusion hook : nil
2710             Repeat Outside : [Toggle]  off (nil)
2711 [INS] [DEL] List:
2712             Macro with args: \astobj@{*@}
2713             Index Tag      : [Value Menu] String: idx
2714             Access Key     : o
2715             Key Prefix     : Astronomical Objects!
2716             Exclusion hook : nil
2717             Repeat Outside : [Toggle]  on (non-nil)
2718 [INS]
2719 @end example
2721 With the macro @code{\ix} defined, you may want to change the default
2722 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2723 This would be done like this
2725 @lisp
2726 (setq reftex-index-default-macro '(?x "idx"))
2727 @end lisp
2729 which specifies that the macro identified with the character @code{?x} (the
2730 @code{\ix} macro) should be used for indexing phrases and words already
2731 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2732 The index tag is "idx".
2734 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2735 @chapter Viewing Cross-References
2736 @findex reftex-view-crossref
2737 @findex reftex-mouse-view-crossref
2738 @kindex C-c &
2739 @kindex S-mouse-2
2741 @RefTeX{} can display cross-referencing information.  This means,
2742 if two document locations are linked, @RefTeX{} can display the
2743 matching location(s) in another window.  The @code{\label} and @code{\ref}
2744 macros are one way of establishing such a link.  Also, a @code{\cite}
2745 macro is linked to the corresponding @code{\bibitem} macro or a @BibTeX{}
2746 database entry.
2748 The feature is invoked by pressing @kbd{C-c &}
2749 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2750 of a macro involved in cross-referencing.  You can also click with
2751 @kbd{S-mouse-2} on the macro argument.  Here is what will happen for
2752 individual classes of macros:
2754 @table @asis
2756 @item @code{\ref}
2757 @cindex @code{\ref}
2758 Display the corresponding label definition.  All usual
2759 variants@footnote{all macros that start with @samp{ref} or end with
2760 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2761 cross-reference display.  This works also for labels defined in an
2762 external document when the current document refers to them through the
2763 @code{xr} interface (@pxref{xr (LaTeX package)}).
2765 @item @code{\label}
2766 @cindex @code{\label}
2767 @vindex reftex-label-alist
2768 Display a document location which references this label.  Pressing
2769 @kbd{C-c &} several times moves through the entire document and finds
2770 all locations.  Not only the @code{\label} macro but also other macros
2771 with label arguments (as configured with @code{reftex-label-alist}) are
2772 active for cross-reference display.
2774 @item @code{\cite}
2775 @cindex @code{\cite}
2776 Display the corresponding @BibTeX{} database entry or @code{\bibitem}.
2777 All usual variants@footnote{all macros that either start or end with
2778 @samp{cite}} of the @code{\cite} macro are active for cross-reference
2779 display.
2781 @item @code{\bibitem}
2782 @cindex @code{\bibitem}
2783 Display a document location which cites this article. Pressing
2784 @kbd{C-c &} several times moves through the entire document and finds
2785 all locations.
2787 @item @BibTeX{}
2788 @cindex BibTeX buffer, viewing cite locations from
2789 @cindex Viewing cite locations from BibTeX buffer
2790 @kbd{C-c &} is also active in @BibTeX{} buffers.  All locations in a
2791 document where the database entry at point is cited will be displayed.
2792 On first use, @RefTeX{} will prompt for a buffer which belongs to
2793 the document you want to search.  Subsequent calls will use the same
2794 document, until you break this link with a prefix argument to @kbd{C-c
2797 @item @code{\index}
2798 @cindex @code{\index}
2799 Display other locations in the document which are marked by an index
2800 macro with the same key argument.  Along with the standard @code{\index}
2801 and @code{\glossary} macros, all macros configured in
2802 @code{reftex-index-macros} will be recognized.
2803 @end table
2805 @vindex reftex-view-crossref-extra
2806 While the display of cross referencing information for the above
2807 mentioned macros is hard-coded, you can configure additional relations
2808 in the variable @code{reftex-view-crossref-extra}.
2810 @iftex
2811 @chapter All the Rest
2812 @end iftex
2814 @node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
2815 @section @RefTeX{}'s Menu
2816 @cindex RefTeXs Menu
2817 @cindex Menu, in the menu bar
2819 @RefTeX{} installs a @code{Ref} menu in the menu bar on systems
2820 which support this.  From this menu you can access all of
2821 @RefTeX{}'s commands and a few of its options.  There is also a
2822 @code{Customize} submenu which can be used to access @RefTeX{}'s
2823 entire set of options.
2825 @node Key Bindings, Faces, RefTeXs Menu, Top
2826 @section Default Key Bindings
2827 @cindex Key Bindings, summary
2829 Here is a summary of the available key bindings.
2831 @kindex C-c =
2832 @kindex C-c -
2833 @kindex C-c (
2834 @kindex C-c )
2835 @kindex C-c [
2836 @kindex C-c &
2837 @kindex S-mouse-2
2838 @kindex C-c /
2839 @kindex C-c \
2840 @kindex C-c |
2841 @kindex C-c <
2842 @kindex C-c >
2843 @example
2844 @kbd{C-c =}      @code{reftex-toc}
2845 @kbd{C-c -}      @code{reftex-toc-recenter}
2846 @kbd{C-c (}      @code{reftex-label}
2847 @kbd{C-c )}      @code{reftex-reference}
2848 @kbd{C-c [}      @code{reftex-citation}
2849 @kbd{C-c &}      @code{reftex-view-crossref}
2850 @kbd{S-mouse-2}  @code{reftex-mouse-view-crossref}
2851 @kbd{C-c /}      @code{reftex-index-selection-or-word}
2852 @kbd{C-c \}      @code{reftex-index-phrase-selection-or-word}
2853 @kbd{C-c |}      @code{reftex-index-visit-phrases-buffer}
2854 @kbd{C-c <}      @code{reftex-index}
2855 @kbd{C-c >}      @code{reftex-display-index}
2856 @end example
2858 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2859 not already used by some other package.  @RefTeX{} will not override an
2860 existing binding to @kbd{S-mouse-2}.
2862 Personally, I also bind some functions in the users @kbd{C-c} map for
2863 easier access.
2865 @c FIXME: Do we need bindings for the Index macros here as well?
2866 @c C-c i   C-c I or so????
2867 @c How about key bindings for reftex-reset-mode and reftex-parse-document?
2868 @kindex C-c t
2869 @kindex C-c l
2870 @kindex C-c r
2871 @kindex C-c c
2872 @kindex C-c v
2873 @kindex C-c s
2874 @kindex C-c g
2875 @example
2876 @kbd{C-c t}    @code{reftex-toc}
2877 @kbd{C-c l}    @code{reftex-label}
2878 @kbd{C-c r}    @code{reftex-reference}
2879 @kbd{C-c c}    @code{reftex-citation}
2880 @kbd{C-c v}    @code{reftex-view-crossref}
2881 @kbd{C-c s}    @code{reftex-search-document}
2882 @kbd{C-c g}    @code{reftex-grep-document}
2883 @end example
2885 @noindent These keys are reserved for the user, so I cannot bind them by
2886 default.  If you want to have these key bindings available, set in your
2887 @file{.emacs} file:
2889 @vindex reftex-extra-bindings
2890 @lisp
2891 (setq reftex-extra-bindings t)
2892 @end lisp
2894 @vindex reftex-load-hook
2895 Changing and adding to @RefTeX{}'s key bindings is best done in the hook
2896 @code{reftex-load-hook}.  For information on the keymaps
2897 which should be used to add keys, see @ref{Keymaps and Hooks}.
2899 @node Faces, AUCTeX, Key Bindings, Top
2900 @section Faces
2901 @cindex Faces
2903 @RefTeX{} uses faces when available to structure the selection and
2904 table of contents buffers.  It does not create its own faces, but uses
2905 the ones defined in @file{font-lock.el}.  Therefore, @RefTeX{} will
2906 use faces only when @code{font-lock} is loaded.  This seems to be
2907 reasonable because people who like faces will very likely have it
2908 loaded.  If you wish to turn off fontification or change the involved
2909 faces, see @ref{Options (Fontification)}.
2911 @node Multifile Documents, Language Support, AUCTeX, Top
2912 @section Multifile Documents
2913 @cindex Multifile documents
2914 @cindex Documents, spread over files
2916 The following is relevant when working with documents spread over many
2917 files:
2919 @itemize @bullet
2920 @item
2921 @RefTeX{} has full support for multifile documents.  You can edit parts of
2922 several (multifile) documents at the same time without conflicts.
2923 @RefTeX{} provides functions to run @code{grep}, @code{search} and
2924 @code{query-replace} on all files which are part of a multifile
2925 document.
2927 @item
2928 @vindex tex-main-file
2929 @vindex TeX-master
2930 All files belonging to a multifile document should define a File
2931 Variable (@code{TeX-master} for @AUCTeX{} or @code{tex-main-file} for the
2932 standard Emacs @LaTeX{} mode) containing the name of the master file.  For
2933 example, to set the file variable @code{TeX-master}, include something
2934 like the following at the end of each @TeX{} file:
2936 @example
2937 %%% Local Variables: ***
2938 %%% mode:latex ***
2939 %%% TeX-master: "thesis.tex"  ***
2940 %%% End: ***
2941 @end example
2943 @AUCTeX{} with the setting
2945 @lisp
2946 (setq-default TeX-master nil)
2947 @end lisp
2949 will actually ask you for each new file about the master file and insert
2950 this comment automatically.  For more details see the documentation of
2951 the @AUCTeX{} (@pxref{Multifile,,,auctex, The AUCTeX User Manual}), the
2952 documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2953 The GNU Emacs Manual}) and the Emacs documentation on File Variables
2954 (@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
2956 @item
2957 The context of a label definition must be found in the same file as the
2958 label itself in order to be processed correctly by @RefTeX{}.  The only
2959 exception is that section labels referring to a section statement
2960 outside the current file can still use that section title as
2961 context.
2962 @end itemize
2964 @node Language Support, Finding Files, Multifile Documents, Top
2965 @section Language Support
2966 @cindex Language support
2968 Some parts of @RefTeX{} are language dependent.  The default
2969 settings work well for English.  If you are writing in a different
2970 language, the following hints may be useful:
2972 @itemize @bullet
2973 @item
2974 @vindex reftex-derive-label-parameters
2975 @vindex reftex-abbrev-parameters
2976 The mechanism to derive a label from context includes the abbreviation
2977 of words and omission of unimportant words.  These mechanisms may have
2978 to be changed for other languages.  See the variables
2979 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2981 @item
2982 @vindex reftex-translate-to-ascii-function
2983 @vindex reftex-label-illegal-re
2984 Also, when a label is derived from context, @RefTeX{} clears the
2985 context string from non-ASCII characters in order to make a valid label.
2986 If there should ever be a version of @TeX{} which allows extended
2987 characters @emph{in labels}, then we will have to look at the
2988 variables @code{reftex-translate-to-ascii-function} and
2989 @code{reftex-label-illegal-re}.
2991 @item
2992 When a label is referenced, @RefTeX{} looks at the word before point
2993 to guess which label type is required.  These @emph{magic words} are
2994 different in every language.  For an example of how to add magic words,
2995 see @ref{Adding Magic Words}.
2997 @vindex reftex-multiref-punctuation
2998 @vindex reftex-cite-punctuation
2999 @item
3000 @RefTeX{} inserts ``punctuation'' for multiple references and
3001 for the author list in citations.  Some of this may be language
3002 dependent.  See the variables @code{reftex-multiref-punctuation} and
3003 @code{reftex-cite-punctuation}.
3004 @end itemize
3006 @node Finding Files, Optimizations, Language Support, Top
3007 @section Finding Files
3008 @cindex Finding files
3010 In order to find files included in a document via @code{\input} or
3011 @code{\include}, @RefTeX{} searches all directories specified in the
3012 environment variable @code{TEXINPUTS}.  Similarly, it will search the
3013 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
3014 @BibTeX{} database files.
3016 When searching, @RefTeX{} will also expand recursive path
3017 definitions (directories ending in @samp{//} or @samp{!!}).  But it will
3018 only search and expand directories @emph{explicitly} given in these
3019 variables. This may cause problems under the following circumstances:
3021 @itemize @bullet
3022 @item
3023 Most @TeX{} system have a default search path for both @TeX{} files and @BibTeX{}
3024 files which is defined in some setup file.  Usually this default path is
3025 for system files which @RefTeX{} does not need to see.  But if your
3026 document needs @TeX{} files or @BibTeX{} database files in a directory only
3027 given in the default search path, @RefTeX{} will fail to find them.
3028 @item
3029 Some @TeX{} systems do not use environment variables at all in order to
3030 specify the search path.  Both default and user search path are then
3031 defined in setup files.
3032 @end itemize
3034 @noindent
3035 There are three ways to solve this problem:
3037 @itemize @bullet
3038 @item
3039 Specify all relevant directories explicitly in the environment
3040 variables.  If for some reason you don't want to mess with the default
3041 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
3042 variables and configure @RefTeX{} to use them instead:
3044 @lisp
3045 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
3046 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
3047 @end lisp
3049 @item
3050 Specify the full search path directly in @RefTeX{}'s variables.
3052 @lisp
3053 (setq reftex-texpath-environment-variables
3054       '("./inp:/home/cd/tex//:/usr/local/tex//"))
3055 (setq reftex-bibpath-environment-variables
3056       '("/home/cd/tex/lit/"))
3057 @end lisp
3059 @item
3060 Some @TeX{} systems provide stand-alone programs to do the file search just
3061 like @TeX{} and @BibTeX{}.  E.g., Thomas Esser's @code{teTeX} uses the
3062 @code{kpathsearch} library which provides the command @code{kpsewhich}
3063 to search for files.  @RefTeX{} can be configured to use this
3064 program.  Note that the exact syntax of the @code{kpsewhich}
3065 command depends upon the version of that program.
3067 @lisp
3068 (setq reftex-use-external-file-finders t)
3069 (setq reftex-external-file-finders
3070       '(("tex" . "kpsewhich -format=.tex %f")
3071         ("bib" . "kpsewhich -format=.bib %f")))
3072 @end lisp
3073 @end itemize
3075 @cindex Noweb files
3076 @vindex reftex-file-extensions
3077 @vindex TeX-file-extensions
3078 Some people like to use RefTeX with noweb files, which usually have the
3079 extension @file{.nw}.  In order to deal with such files, the new
3080 extension must be added to the list of valid extensions in the variable
3081 @code{reftex-file-extensions}.  When working with @AUCTeX{} as major mode,
3082 the new extension must also be known to @AUCTeX{} via the variable
3083 @code{TeX-file-extension}.  For example:
3085 @lisp
3086 (setq reftex-file-extensions
3087       '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
3088 (setq TeX-file-extensions
3089       '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
3090 @end lisp
3092 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
3093 @section Optimizations
3094 @cindex Optimizations
3096 @b{Note added 2002.  Computers have gotten a lot faster, so most of the
3097 optimizations discussed below will not be necessary on new machines.  I
3098 am leaving this stuff in the manual for people who want to write thick
3099 books, where some of it still might be useful.}
3101 Implementing the principle of least surprises, the default settings of
3102 @RefTeX{} ensure a safe ride for beginners and casual users.  However,
3103 when using @RefTeX{} for a large project and/or on a small computer,
3104 there are ways to improve speed or memory usage.
3106 @itemize @bullet
3107 @item
3108 @b{Removing Lookup Buffers}@*
3109 @cindex Removing lookup buffers
3110 @RefTeX{} will load other parts of a multifile document as well as @BibTeX{}
3111 database files for lookup purposes.  These buffers are kept, so that
3112 subsequent use of the same files is fast.  If you can't afford keeping
3113 these buffers around, and if you can live with a speed penalty, try
3115 @vindex reftex-keep-temporary-buffers
3116 @lisp
3117 (setq reftex-keep-temporary-buffers nil)
3118 @end lisp
3120 @item
3121 @b{Partial Document Scans}@*
3122 @cindex Partial documents scans
3123 @cindex Document scanning, partial
3124 A @kbd{C-u} prefix on the major @RefTeX{} commands @code{reftex-label}
3125 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
3126 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
3127 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
3128 re-parsing of the entire document in order to update the parsing
3129 information.  For a large document this can be unnecessary, in
3130 particular if only one file has changed.  @RefTeX{} can be configured
3131 to do partial scans instead of full ones.  @kbd{C-u} re-parsing then
3132 does apply only to the current buffer and files included from it.
3133 Likewise, the @kbd{r} key in both the label selection buffer and the
3134 table-of-contents buffer will only prompt scanning of the file in which
3135 the label or section macro near the cursor was defined.  Re-parsing of
3136 the entire document is still available by using @kbd{C-u C-u} as a
3137 prefix, or the capital @kbd{R} key in the menus.  To use this feature,
3140 @vindex reftex-enable-partial-scans
3141 @lisp
3142 (setq reftex-enable-partial-scans t)
3143 @end lisp
3145 @item
3146 @b{Saving Parser Information}@*
3147 @cindex Saving parser information
3148 @cindex Parse information, saving to a file
3149 @vindex reftex-parse-file-extension
3150 Even with partial scans enabled, @RefTeX{} still has to make one full
3151 scan, when you start working with a document.  To avoid this, parsing
3152 information can be stored in a file.  The file @file{MASTER.rel} is used
3153 for storing information about a document with master file
3154 @file{MASTER.tex}.  It is written automatically when you kill a buffer
3155 in @code{reftex-mode} or when you exit Emacs.  The information is
3156 restored when you begin working with a document in a new editing
3157 session.  To use this feature, put into @file{.emacs}:
3159 @vindex reftex-save-parse-info
3160 @lisp
3161 (setq reftex-save-parse-info t)
3162 @end lisp
3164 @item
3165 @b{Identifying label types by prefix}@*
3166 @cindex Parse information, saving to a file
3167 @vindex reftex-trust-label-prefix
3168 @RefTeX{} normally parses around each label to check in which
3169 environment this label is located, in order to assign a label type to
3170 the label.  If your document contains thousands of labels, document
3171 parsing will take considerable time.  If you have been using label prefixes
3172 like tab: and fn: consistently, you can tell @RefTeX{} to get the
3173 label type directly from the prefix, without additional parsing.  This
3174 will be faster and also allow labels to end up in the correct category
3175 if for some reason it is not possible to derive the correct type from
3176 context.  For example, to enable this feature for footnote and
3177 equation labels, use
3179 @lisp
3180 (setq reftex-trust-label-prefix '("fn:" "eq:"))
3181 @end lisp
3183 @item
3184 @b{Automatic Document Scans}@*
3185 @cindex Automatic document scans
3186 @cindex Document scanning, automatic
3187 At rare occasions, @RefTeX{} will automatically rescan a part of the
3188 document.  If this gets into your way, it can be turned off with
3190 @vindex reftex-allow-automatic-rescan
3191 @lisp
3192 (setq reftex-allow-automatic-rescan nil)
3193 @end lisp
3195 @RefTeX{} will then occasionally annotate new labels in the selection
3196 buffer, saying that their position in the label list in uncertain.  A
3197 manual document scan will fix this.
3199 @item
3200 @b{Multiple Selection Buffers}@*
3201 @cindex Multiple selection buffers
3202 @cindex Selection buffers, multiple
3203 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
3204 every selection process.  In documents with very many labels this can
3205 take several seconds.  @RefTeX{} provides an option to create a
3206 separate selection buffer for each label type and to keep this buffer
3207 from one selection to the next.  These buffers are updated automatically
3208 only when a new label has been added in the buffers category with
3209 @code{reftex-label}.  Updating the buffer takes as long as recreating it
3210 - so the time saving is limited to cases where no new labels of that
3211 category have been added.  To turn on this feature, use
3213 @vindex reftex-use-multiple-selection-buffers
3214 @lisp
3215 (setq reftex-use-multiple-selection-buffers t)
3216 @end lisp
3218 @noindent
3219 @cindex Selection buffers, updating
3220 You can also inhibit the automatic updating entirely.  Then the
3221 selection buffer will always pop up very fast, but may not contain the
3222 most recently defined labels.  You can always update the buffer by hand,
3223 with the @kbd{g} key.  To get this behavior, use instead
3225 @vindex reftex-auto-update-selection-buffers
3226 @lisp
3227 (setq reftex-use-multiple-selection-buffers t
3228       reftex-auto-update-selection-buffers nil)
3229 @end lisp
3230 @end itemize
3232 @need 2000
3233 @noindent
3234 @b{As a summary}, here are the settings I recommend for heavy use of
3235 @RefTeX{} with large documents:
3237 @lisp
3238 @group
3239 (setq reftex-enable-partial-scans t
3240       reftex-save-parse-info t
3241       reftex-use-multiple-selection-buffers t)
3242 @end group
3243 @end lisp
3245 @node AUCTeX, Multifile Documents, Faces, Top
3246 @section @AUCTeX{}
3247 @cindex @code{AUCTeX}, Emacs package
3248 @cindex Emacs packages, @code{AUCTeX}
3250 @AUCTeX{} is without doubt the best major mode for editing @TeX{} and @LaTeX{}
3251 files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
3252 If @AUCTeX{} is not part of your Emacs distribution, you can get
3253 it@footnote{XEmacs 21.x users may want to install the corresponding
3254 XEmacs package.} by FTP from the @value{AUCTEXSITE}.
3256 @menu
3257 * AUCTeX-RefTeX Interface::          How both packages work together
3258 * Style Files::                      @AUCTeX{}'s style files can support RefTeX
3259 * Bib-Cite::                         Hypertext reading of a document
3260 @end menu
3262 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
3263 @subsection The @AUCTeX{}-@RefTeX{} Interface
3265 @RefTeX{} contains code to interface with @AUCTeX{}.  When this
3266 interface is turned on, both packages will interact closely.  Instead of
3267 using @RefTeX{}'s commands directly, you can then also use them
3268 indirectly as part of the @AUCTeX{}
3269 environment@footnote{@RefTeX{} 4.0 and @AUCTeX{} 9.10c will be
3270 needed for all of this to work.  Parts of it work also with earlier
3271 versions.}.  The interface is turned on with
3273 @lisp
3274 (setq reftex-plug-into-AUCTeX t)
3275 @end lisp
3277 If you need finer control about which parts of the interface are used
3278 and which not, read the docstring of the variable
3279 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
3280 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
3282 The following list describes the individual parts of the interface.
3284 @itemize @bullet
3285 @item
3286 @findex reftex-label
3287 @vindex LaTeX-label-function, @r{AUCTeX}
3288 @kindex C-c C-e
3289 @kindex C-c C-s
3290 @findex LaTeX-section, @r{AUCTeX}
3291 @findex TeX-insert-macro, @r{AUCTeX}
3292 @b{@AUCTeX{} calls @code{reftex-label} to insert labels}@*
3293 When a new section is created with @kbd{C-c C-s}, or a new environment
3294 is inserted with @kbd{C-c C-e}, @AUCTeX{} normally prompts for a label to
3295 go with it.  With the interface, @code{reftex-label} is called instead.
3296 For example, if you type @kbd{C-c C-e equation @key{RET}}, @AUCTeX{} and
3297 @RefTeX{} will insert
3299 @example
3300 \begin@{equation@}
3301 \label@{eq:1@}
3303 \end@{equation@}
3304 @end example
3306 @noindent
3307 without further prompts.
3309 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @RefTeX{}
3310 will offer its default label which is derived from the section title.
3312 @item
3313 @b{@AUCTeX{} tells @RefTeX{} about new sections}@*
3314 When creating a new section with @kbd{C-c C-s}, @RefTeX{} will not
3315 have to rescan the buffer in order to see it.
3317 @item
3318 @findex reftex-arg-label
3319 @findex TeX-arg-label, @r{AUCTeX function}
3320 @findex reftex-arg-ref
3321 @findex TeX-arg-ref, @r{AUCTeX function}
3322 @findex reftex-arg-cite
3323 @findex TeX-arg-cite, @r{AUCTeX function}
3324 @findex reftex-arg-index
3325 @findex TeX-arg-index, @r{AUCTeX function}
3326 @findex TeX-insert-macro, @r{AUCTeX function}
3327 @kindex C-c @key{RET}
3328 @b{@RefTeX{} supplies macro arguments}@* When you insert a macro
3329 interactively with @kbd{C-c @key{RET}}, @AUCTeX{} normally prompts for
3330 macro arguments.  Internally, it uses the functions
3331 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3332 prompt for arguments which are labels, citation keys and index entries.
3333 The interface takes over these functions@footnote{@code{fset} is used to
3334 do this, which is not reversible.  However, @RefTeX{} implements the
3335 old functionality when you later decide to turn off the interface.} and
3336 supplies the macro arguments with @b{@RefTeX{}'s} mechanisms.  For
3337 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @RefTeX{}
3338 will supply its label selection process (@pxref{Referencing
3339 Labels}).
3341 @item
3342 @b{@RefTeX{} tells @AUCTeX{} about new labels, citation and index keys}@*
3343 @RefTeX{} will add all newly created labels to @AUCTeX{}'s completion list.
3344 @end itemize
3346 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
3347 @subsection Style Files
3348 @cindex Style files, AUCTeX
3349 @findex TeX-add-style-hook, @r{AUCTeX}
3350 Style files are Emacs Lisp files which are evaluated by @AUCTeX{} in
3351 association with the @code{\documentclass} and @code{\usepackage}
3352 commands of a document (@pxref{Style Files,,,auctex}). Support for
3353 @RefTeX{} in such a style file is useful when the @LaTeX{} style
3354 defines macros or environments connected with labels, citations, or the
3355 index.  Many style files (e.g., @file{amsmath.el} or @file{natbib.el})
3356 distributed with @AUCTeX{} already support @RefTeX{} in this
3357 way.
3359 Before calling a @RefTeX{} function, the style hook should always
3360 test for the availability of the function, so that the style file will
3361 also work for people who do not use @RefTeX{}.
3363 Additions made with style files in the way described below remain local
3364 to the current document.  For example, if one package uses AMSTeX, the
3365 style file will make @RefTeX{} switch over to @code{\eqref}, but
3366 this will not affect other documents.
3368 @findex reftex-add-label-environments
3369 @findex reftex-add-to-label-alist
3370 A style hook may contain calls to
3371 @code{reftex-add-label-environments}@footnote{This used to be the
3372 function @code{reftex-add-to-label-alist} which is still available as an
3373 alias for compatibility.}  which defines additions to
3374 @code{reftex-label-alist}.  The argument taken by this function must have
3375 the same format as @code{reftex-label-alist}.  The @file{amsmath.el}
3376 style file of @AUCTeX{} for example contains the following:
3378 @lisp
3379 @group
3380 (TeX-add-style-hook "amsmath"
3381    (lambda ()
3382      (if (fboundp 'reftex-add-label-environments)
3383          (reftex-add-label-environments '(AMSTeX)))))
3384 @end group
3385 @end lisp
3387 @noindent
3388 @findex LaTeX-add-environments, @r{AUCTeX}
3389 while a package @code{myprop} defining a @code{proposition} environment
3390 with @code{\newtheorem} might use
3392 @lisp
3393 @group
3394 (TeX-add-style-hook "myprop"
3395    (lambda ()
3396      (LaTeX-add-environments '("proposition" LaTeX-env-label))
3397      (if (fboundp 'reftex-add-label-environments)
3398          (reftex-add-label-environments
3399           '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3400                            ("Proposition" "Prop.") -3))))))
3401 @end group
3402 @end lisp
3404 @findex reftex-set-cite-format
3405 Similarly, a style hook may contain a call to
3406 @code{reftex-set-cite-format} to set the citation format.  The style
3407 file @file{natbib.el} for the Natbib citation style does switch
3408 @RefTeX{}'s citation format like this:
3410 @lisp
3411 (TeX-add-style-hook "natbib"
3412    (lambda ()
3413      (if (fboundp 'reftex-set-cite-format)
3414          (reftex-set-cite-format 'natbib))))
3415 @end lisp
3417 @findex reftex-add-index-macros
3418 The hook may contain a call to @code{reftex-add-index-macros} to
3419 define additional @code{\index}-like macros.  The argument must have
3420 the same format as @code{reftex-index-macros}.  It may be a symbol, to
3421 trigger support for one of the builtin index packages.  For example,
3422 the style @file{multind.el} contains
3424 @lisp
3425 (TeX-add-style-hook "multind"
3426   (lambda ()
3427     (and (fboundp 'reftex-add-index-macros)
3428          (reftex-add-index-macros '(multind)))))
3429 @end lisp
3431 If you have your own package @file{myindex} which defines the
3432 following macros to be used with the @LaTeX{} @file{index.sty} file
3433 @example
3434 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3435 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3436 @end example
3438 you could write this in the style file @file{myindex.el}:
3440 @lisp
3441 (TeX-add-style-hook "myindex"
3442    (lambda ()
3443      (TeX-add-symbols
3444       '("molec" TeX-arg-index)
3445       '("aindex" TeX-arg-index))
3446      (if (fboundp 'reftex-add-index-macros)
3447          (reftex-add-index-macros
3448           '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3449             ("aindex@{*@}" "author" ?a "" nil nil))))))
3450 @end lisp
3452 @findex reftex-add-section-levels
3453 Finally the hook may contain a call to @code{reftex-add-section-levels}
3454 to define additional section statements.  For example, the FoilTeX class
3455 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}.  Here
3456 is a style file @file{foils.el} that will inform @RefTeX{} about these:
3458 @lisp
3459 (TeX-add-style-hook "foils"
3460    (lambda ()
3461      (if (fboundp 'reftex-add-section-levels)
3462          (reftex-add-section-levels '(("foilhead" . 3)
3463                                       ("rotatefoilhead" . 3))))))
3464 @end lisp
3466 @node Bib-Cite, , Style Files, AUCTeX
3467 @subsection Bib-Cite
3468 @cindex @code{bib-cite}, Emacs package
3469 @cindex Emacs packages, @code{bib-cite}
3471 Once you have written a document with labels, references and citations,
3472 it can be nice to read it like a hypertext document.  @RefTeX{} has
3473 support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3474 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3475 @code{reftex-search-document}.  A somewhat fancier interface with mouse
3476 highlighting is provided (among other things) by Peter S. Galbraith's
3477 @file{bib-cite.el}.  There is some overlap in the functionalities of
3478 Bib-cite and @RefTeX{}.  Bib-cite.el comes bundled with
3479 @AUCTeX{}.
3481 Bib-cite version 3.06 and later can be configured so that bib-cite's
3482 mouse functions use @RefTeX{} for displaying references and citations.
3483 This can be useful in particular when working with the @LaTeX{} @code{xr}
3484 package or with an explicit @code{thebibliography} environment (rather
3485 than @BibTeX{}).  Bib-cite cannot handle those, but @RefTeX{} does.  To
3486 make use of this feature, try
3488 @vindex bib-cite-use-reftex-view-crossref
3489 @lisp
3490 (setq bib-cite-use-reftex-view-crossref t)
3491 @end lisp
3493 @page
3494 @node Problems and Work-Arounds, Imprint, Optimizations, Top
3495 @section Problems and Work-arounds
3496 @cindex Problems and work-arounds
3498 @itemize @bullet
3499 @item
3500 @b{@LaTeX{} commands}@*
3501 @cindex LaTeX commands, not found
3502 @code{\input}, @code{\include}, and @code{\section} (etc.)@: statements
3503 have to be first on a line (except for white space).
3505 @item
3506 @b{Commented regions}@*
3507 @cindex Labels, commented out
3508 @RefTeX{} sees also labels in regions commented out and will refuse to
3509 make duplicates of such labels.  This is considered to be a feature.
3511 @item
3512 @b{Wrong section numbers}@*
3513 @cindex Section numbers, wrong
3514 @vindex reftex-enable-partial-scans
3515 When using partial scans (@code{reftex-enable-partial-scans}), the section
3516 numbers in the table of contents may eventually become wrong.  A full
3517 scan will fix this.
3519 @item
3520 @b{Local settings}@*
3521 @cindex Settings, local
3522 @findex reftex-add-label-environments
3523 @findex reftex-set-cite-format
3524 @findex reftex-add-section-levels
3525 The label environment definitions in @code{reftex-label-alist} are
3526 global and apply to all documents.  If you need to make definitions
3527 local to a document, because they would interfere with settings in other
3528 documents, you should use @AUCTeX{} and set up style files with calls to
3529 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3530 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3531 Settings made with these functions remain local to the current
3532 document. @xref{AUCTeX}.
3534 @item
3535 @b{Funny display in selection buffer}@*
3536 @cindex @code{x-symbol}, Emacs package
3537 @cindex Emacs packages, @code{x-symbol}
3538 @cindex @code{isotex}, Emacs package
3539 @cindex Emacs packages, @code{isotex}
3540 @cindex @code{iso-cvt}, Emacs package
3541 @cindex Emacs packages, @code{iso-cvt}
3542 When using packages which make the buffer representation of a file
3543 different from its disk representation (e.g., x-symbol, isotex,
3544 iso-cvt) you may find that @RefTeX{}'s parsing information sometimes
3545 reflects the disk state of a file.  This happens only in @emph{unvisited}
3546 parts of a multifile document, because @RefTeX{} visits these files
3547 literally for speed reasons.  Then both short context and section
3548 headings may look different from what you usually see on your screen.
3549 In rare cases @code{reftex-toc} may have problems to jump to an affected
3550 section heading.  There are three possible ways to deal with
3551 this:
3552 @itemize @minus
3553 @item
3554 @vindex reftex-keep-temporary-buffers
3555 @code{(setq reftex-keep-temporary-buffers t)}@*
3556 This implies that @RefTeX{} will load all parts of a multifile
3557 document into Emacs (i.e., there won't be any temporary buffers).
3558 @item
3559 @vindex reftex-initialize-temporary-buffers
3560 @code{(setq reftex-initialize-temporary-buffers t)}@*
3561 This means full initialization of temporary buffers.  It involves
3562 a penalty when the same unvisited file is used for lookup often.
3563 @item
3564 Set @code{reftex-initialize-temporary-buffers} to a list of hook
3565 functions doing a minimal initialization.
3566 @end itemize
3567 @vindex reftex-refontify-context
3568 See also the variable @code{reftex-refontify-context}.
3570 @item
3571 @b{Labels as arguments to \begin}@*
3572 @cindex @code{pf}, LaTeX package
3573 @cindex LaTeX packages, @code{pf}
3574 Some packages use an additional argument to a @code{\begin} macro
3575 to specify a label.  E.g., Lamport's @file{pf.sty} uses both
3576 @example
3577 \step@{@var{label}@}@{@var{claim}@}   and      \begin@{step+@}@{@var{label}@}
3578                                   @var{claim}
3579                                \end@{step+@}
3580 @end example
3582 @noindent
3583 We need to trick @RefTeX{} into swallowing this:
3585 @lisp
3586 @group
3587 ;; Configuration for Lamport's pf.sty
3588 (setq reftex-label-alist
3589   '(("\\step@{*@}@{@}"       ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3590     ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3591 @end group
3592 @end lisp
3594 @noindent
3595 The first line is just a normal configuration for a macro.  For the
3596 @code{step+} environment we actually tell @RefTeX{} to look for the
3597 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3598 argument (which really is a second argument to the macro @code{\begin})
3599 as a label of type @code{?p}.  Argument count for this macro starts only
3600 after the @samp{@{step+@}}, also when specifying how to get
3601 context.
3603 @item
3604 @b{Idle timers in XEmacs}@*
3605 @cindex Idle timer restart
3606 @vindex reftex-use-itimer-in-xemacs
3607 In XEmacs, idle timer restart does not work reliably after fast
3608 keystrokes.  Therefore @RefTeX{} currently uses the post command
3609 hook to start the timer used for automatic crossref information.  When
3610 this bug gets fixed, a real idle timer can be requested with
3611 @lisp
3612 (setq reftex-use-itimer-in-xemacs t)
3613 @end lisp
3615 @item
3616 @b{Viper mode}@*
3617 @cindex Viper mode
3618 @cindex Key bindings, problems with Viper mode
3619 @findex viper-harness-minor-mode
3620 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3621 @RefTeX{}'s keymaps with
3623 @lisp
3624 (viper-harness-minor-mode "reftex")
3625 @end lisp
3627 @end itemize
3629 @page
3630 @node Imprint, Commands, Problems and Work-Arounds, Top
3631 @section Imprint
3632 @cindex Imprint
3633 @cindex Maintainer
3634 @cindex Acknowledgments
3635 @cindex Thanks
3636 @cindex Bug reports
3637 @cindex @code{http}, @RefTeX{} home page
3638 @cindex @code{ftp}, @RefTeX{} site
3640 @c dominik@@science.uva.nl
3641 @RefTeX{} was written by @i{Carsten Dominik}, with contributions by @i{Stephen
3642 Eglen}.  @RefTeX{} is currently maintained by @value{MAINTAINER}, see
3643 the @value{MAINTAINERSITE} for detailed information.
3645 If you have questions about @RefTeX{}, you can send email to the
3646 @value{SUPPORTADDRESS}.  If you want to contribute code or ideas, write
3647 to the @value{DEVELADDRESS}.  And in the rare case of finding a bug,
3648 please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a
3649 bug report with useful information about your setup.  Remember to add
3650 essential information like a recipe for reproducing the bug, what you
3651 expected to happen, and what actually happened.  Send the bug report to
3652 the @value{BUGADDRESS}.
3654 There are also several Usenet groups which have competent readers who
3655 might be able to help: @code{comp.emacs}, @code{gnu.emacs.help},
3656 @code{comp.emacs.xemacs}, and @code{comp.text.tex}.
3658 Thanks to the people on the Net who have used @RefTeX{} and helped
3659 developing it with their reports.  In particular thanks to @i{Ralf
3660 Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton,
3661 Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai
3662 Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan
3663 Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz,
3664 Juri Linkov, Wolfgang Mayer, Rory Molinari, Stefan Monnier, Laurent
3665 Mugnier, Dan Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko,
3666 Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph
3667 Wedler, Alan Williams, Roland Winkler, Hans-Christoph Wirth, Eli
3668 Zaretskii}.
3670 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3671 @file{bib-cite.el}.
3673 Finally thanks to @i{Uwe Bolick} who first got me interested in
3674 supporting @LaTeX{} labels and references with an editor (which was
3675 MicroEmacs at the time).
3677 @node Commands, Options, Imprint, Top
3678 @chapter Commands
3679 @cindex Commands, list of
3681 Here is a summary of @RefTeX{}'s commands which can be executed from
3682 @LaTeX{} files.  Command which are executed from the special buffers are
3683 not described here.  All commands are available from the @code{Ref}
3684 menu.  See @xref{Key Bindings}.
3686 @deffn Command reftex-toc
3687 Show the table of contents for the current document.  When called with
3688 one ore two @kbd{C-u} prefixes, rescan the document first.
3689 @end deffn
3691 @deffn Command reftex-label
3692 Insert a unique label.  With one or two @kbd{C-u} prefixes, enforce
3693 document rescan first.
3694 @end deffn
3696 @deffn Command reftex-reference
3697 Start a selection process to select a label, and insert a reference to
3698 it.  With one or two @kbd{C-u} prefixes, enforce document rescan first.
3699 @end deffn
3701 @deffn Command reftex-citation
3702 Make a citation using @BibTeX{} database files.  After prompting for a regular
3703 expression, scans the buffers with @BibTeX{} entries (taken from the
3704 @code{\bibliography} command or a @code{thebibliography} environment)
3705 and offers the matching entries for selection.  The selected entry is
3706 formatted according to @code{reftex-cite-format} and inserted into the
3707 buffer. @*
3708 When called with a @kbd{C-u} prefix, prompt for optional arguments in
3709 cite macros.  When called with a numeric prefix, make that many citations.
3710 When called with point inside the braces of a @code{\cite} command, it
3711 will add another key, ignoring the value of
3712 @code{reftex-cite-format}. @*
3713 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3714 as @code{and}.  Thus, @samp{aaaa&&bbb} matches entries which contain
3715 both @samp{aaaa} and @samp{bbb}.  While entering the regexp, completion
3716 on knows citation keys is possible.  @samp{=} is a good regular
3717 expression to match all entries in all files.
3718 @end deffn
3720 @deffn Command reftex-index
3721 Query for an index macro and insert it along with its arguments.  The
3722 index macros available are those defined in @code{reftex-index-macro} or
3723 by a call to @code{reftex-add-index-macros}, typically from an @AUCTeX{}
3724 style file.  @RefTeX{} provides completion for the index tag and the
3725 index key, and will prompt for other arguments.
3726 @end deffn
3728 @deffn Command reftex-index-selection-or-word
3729 Put current selection or the word near point into the default index
3730 macro.  This uses the information in @code{reftex-index-default-macro}
3731 to make an index entry.  The phrase indexed is the current selection or
3732 the word near point.  When called with one @kbd{C-u} prefix, let the
3733 user have a chance to edit the index entry.  When called with 2
3734 @kbd{C-u} as prefix, also ask for the index macro and other stuff.  When
3735 called inside @TeX{} math mode as determined by the @file{texmathp.el}
3736 library which is part of @AUCTeX{}, the string is first processed with the
3737 @code{reftex-index-math-format}, which see.
3738 @end deffn
3740 @deffn Command reftex-index-phrase-selection-or-word
3741 Add current selection or the word at point to the phrases buffer.
3742 When you are in transient-mark-mode and the region is active, the
3743 selection will be used; otherwise the word at point.
3744 You get a chance to edit the entry in the phrases buffer; to save the
3745 buffer and return to the @LaTeX{} document, finish with @kbd{C-c C-c}.
3746 @end deffn
3748 @deffn Command reftex-index-visit-phrases-buffer
3749 Switch to the phrases buffer, initialize if empty.
3750 @end deffn
3752 @deffn Command reftex-index-phrases-apply-to-region
3753 Index all index phrases in the current region.
3754 This works exactly like global indexing from the index phrases buffer,
3755 but operation is restricted to the current region.
3756 @end deffn
3758 @deffn Command reftex-display-index
3759 Display a buffer with an index compiled from the current document.
3760 When the document has multiple indices, first prompts for the correct one.
3761 When index support is turned off, offer to turn it on.
3762 With one or two @kbd{C-u} prefixes, rescan document first.
3763 With prefix 2, restrict index to current document section.
3764 With prefix 3, restrict index to active region.
3765 @end deffn
3767 @deffn Command reftex-view-crossref
3768 View cross reference of macro at point.  Point must be on the @var{key}
3769 argument.  Works with the macros @code{\label}, @code{\ref},
3770 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3771 these.  Where it makes sense, subsequent calls show additional
3772 locations.  See also the variable @code{reftex-view-crossref-extra} and
3773 the command @code{reftex-view-crossref-from-bibtex}.  With one or two
3774 @kbd{C-u} prefixes, enforce rescanning of the document.  With argument
3775 2, select the window showing the cross reference.
3776 @end deffn
3778 @deffn Command reftex-view-crossref-from-bibtex
3779 View location in a @LaTeX{} document which cites the @BibTeX{} entry at point.
3780 Since @BibTeX{} files can be used by many @LaTeX{} documents, this function
3781 prompts upon first use for a buffer in @RefTeX{} mode.  To reset this
3782 link to a document, call the function with a prefix arg.  Calling
3783 this function several times find successive citation locations.
3784 @end deffn
3786 @deffn Command reftex-create-tags-file
3787 Create TAGS file by running @code{etags} on the current document.  The
3788 TAGS file is also immediately visited with
3789 @code{visit-tags-table}.
3790 @end deffn
3792 @deffn Command reftex-grep-document
3793 Run grep query through all files related to this document.
3794 With prefix arg, force to rescan document.
3795 No active TAGS table is required.
3796 @end deffn
3798 @deffn Command reftex-search-document
3799 Regexp search through all files of the current document.
3800 Starts always in the master file.  Stops when a match is found.
3801 No active TAGS table is required.
3802 @end deffn
3804 @deffn Command reftex-query-replace-document
3805 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3806 document.  With prefix arg, replace only word-delimited matches.  No
3807 active TAGS table is required.
3808 @end deffn
3810 @deffn Command reftex-isearch-minor-mode
3811 Toggle a minor mode which enables incremental search to work globally
3812 on the entire multifile document.  Files will be searched in the
3813 sequence they appear in the document.
3814 @end deffn
3816 @deffn Command reftex-goto-label
3817 Prompt for a label (with completion) and jump to the location of this
3818 label.  Optional prefix argument @var{other-window} goes to the label in
3819 another window.
3820 @end deffn
3823 @deffn Command reftex-change-label
3824 Query replace @var{from} with @var{to} in all @code{\label} and
3825 @code{\ref} commands.  Works on the entire multifile document.  No
3826 active TAGS table is required.
3827 @end deffn
3829 @deffn Command reftex-renumber-simple-labels
3830 Renumber all simple labels in the document to make them sequentially.
3831 Simple labels are the ones created by RefTeX, consisting only of the
3832 prefix and a number.  After the command completes, all these labels will
3833 have sequential numbers throughout the document.  Any references to the
3834 labels will be changed as well.  For this, @RefTeX{} looks at the
3835 arguments of any macros which either start or end with the string
3836 @samp{ref}.  This command should be used with care, in particular in
3837 multifile documents.  You should not use it if another document refers
3838 to this one with the @code{xr} package.
3839 @end deffn
3841 @deffn Command reftex-find-duplicate-labels
3842 Produce a list of all duplicate labels in the document.
3843 @end deffn
3845 @deffn Command reftex-create-bibtex-file
3846 @vindex reftex-create-bibtex-header
3847 @vindex reftex-create-bibtex-footer
3848 Create a new @BibTeX{} database file with all entries referenced in
3849 document.  The command prompts for a filename and writes the collected
3850 entries to that file.  Only entries referenced in the current document
3851 with any @code{\cite}-like macros are used.  The sequence in the new
3852 file is the same as it was in the old database.
3854 Entries referenced from other entries must appear after all referencing
3855 entries.
3857 You can define strings to be used as header or footer for the created
3858 files in the variables @code{reftex-create-bibtex-header} or
3859 @code{reftex-create-bibtex-footer} respectively.
3860 @end deffn
3862 @deffn Command reftex-customize
3863 Run the customize browser on the @RefTeX{} group.
3864 @end deffn
3865 @deffn Command reftex-show-commentary
3866 Show the commentary section from @file{reftex.el}.
3867 @end deffn
3868 @deffn Command reftex-info
3869 Run info on the top @RefTeX{} node.
3870 @end deffn
3871 @deffn Command reftex-parse-document
3872 Parse the entire document in order to update the parsing information.
3873 @end deffn
3874 @deffn Command reftex-reset-mode
3875 Enforce rebuilding of several internal lists and variables.  Also
3876 removes the parse file associated with the current document.
3877 @end deffn
3879 @node Options, Keymaps and Hooks, Commands, Top
3880 @chapter Options, Keymaps, Hooks
3881 @cindex Options, list of
3883 Here is a complete list of @RefTeX{}'s configuration variables.  All
3884 variables have customize support, so if you are not familiar with Emacs
3885 Lisp (and even if you are) you might find it more comfortable to use
3886 @code{customize} to look at and change these variables. @kbd{M-x
3887 reftex-customize} will get you there.
3889 @menu
3890 * Options (Table of Contents)::
3891 * Options (Defining Label Environments)::
3892 * Options (Creating Labels)::
3893 * Options (Referencing Labels)::
3894 * Options (Creating Citations)::
3895 * Options (Index Support)::
3896 * Options (Viewing Cross-References)::
3897 * Options (Finding Files)::
3898 * Options (Optimizations)::
3899 * Options (Fontification)::
3900 * Options (Misc)::
3901 @end menu
3903 @node Options (Table of Contents), Options (Defining Label Environments), ,  Options
3904 @section Table of Contents
3905 @cindex Options, table of contents
3906 @cindex Table of contents, options
3908 @defopt reftex-include-file-commands
3909 List of @LaTeX{} commands which input another file.
3910 The file name is expected after the command, either in braces or separated
3911 by whitespace.
3912 @end defopt
3914 @defopt reftex-max-section-depth
3915 Maximum depth of section levels in document structure.
3916 Standard @LaTeX{} needs 7, default is 12.
3917 @end defopt
3919 @defopt reftex-section-levels
3920 Commands and levels used for defining sections in the document.  The
3921 @code{car} of each cons cell is the name of the section macro.  The
3922 @code{cdr} is a number indicating its level.  A negative level means the
3923 same as the positive value, but the section will never get a number.
3924 The @code{cdr} may also be a function which then has to return the
3925 level.  This list is also used for promotion and demotion of sectioning
3926 commands.  If you are using a document class which has several sets of
3927 sectioning commands, promotion only works correctly if this list is
3928 sorted first by set, then within each set by level.  The promotion
3929 commands always select the nearest entry with the correct new level.
3931 @end defopt
3933 @defopt reftex-toc-max-level
3934 The maximum level of toc entries which will be included in the TOC@.
3935 Section headings with a bigger level will be ignored.  In RefTeX,
3936 chapters are level 1, sections level 2 etc.  This variable can be
3937 changed from within the @file{*toc*} buffer with the @kbd{t} key.
3938 @end defopt
3940 @defopt reftex-part-resets-chapter
3941 Non-@code{nil} means, @code{\part} is like any other sectioning command.
3942 This means, part numbers will be included in the numbering of chapters, and
3943 chapter counters will be reset for each part.
3944 When @code{nil} (the default), parts are special, do not reset the
3945 chapter counter and also do not show up in chapter numbers.
3946 @end defopt
3948 @defopt reftex-auto-recenter-toc
3949 Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
3950 When active, the @file{*TOC*} window will always show the section you
3951 are currently working in.  Recentering happens whenever Emacs is idle for
3952 more than @code{reftex-idle-time} seconds.
3954 Value @code{t} means, turn on immediately when RefTeX gets started.  Then,
3955 recentering will work for any toc window created during the session.
3957 Value @code{frame} (the default) means, turn automatic recentering on
3958 only while the dedicated TOC frame does exist, and do the recentering
3959 only in that frame.  So when creating that frame (with @kbd{d} key in an
3960 ordinary TOC window), the automatic recentering is turned on.  When the
3961 frame gets destroyed, automatic recentering is turned off again.
3963 This feature can be turned on and off from the menu
3964 (Ref->Options).
3965 @end defopt
3967 @defopt reftex-toc-split-windows-horizontally
3968 Non-@code{nil} means, create TOC window by splitting window
3969 horizontally.  The default is to split vertically.
3970 @end defopt
3972 @defopt reftex-toc-split-windows-fraction
3973 Fraction of the width or height of the frame to be used for TOC window.
3974 @end defopt
3976 @defopt reftex-toc-keep-other-windows
3977 Non-@code{nil} means, split the selected window to display the
3978 @file{*toc*} buffer.  This helps to keep the window configuration, but
3979 makes the @file{*toc*} small.  When @code{nil}, all other windows except
3980 the selected one will be deleted, so that the @file{*toc*} window fills
3981 half the frame.
3982 @end defopt
3984 @defopt reftex-toc-include-file-boundaries
3985 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3986 This flag can be toggled from within the @file{*toc*} buffer with the
3987 @kbd{i} key.
3988 @end defopt
3990 @defopt reftex-toc-include-labels
3991 Non-@code{nil} means, include labels in @file{*toc*} buffer.  This flag
3992 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3993 key.
3994 @end defopt
3996 @defopt reftex-toc-include-index-entries
3997 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3998 This flag can be toggled from within the @file{*toc*} buffer with the
3999 @kbd{i} key.
4000 @end defopt
4002 @defopt reftex-toc-include-context
4003 Non-@code{nil} means, include context with labels in the @file{*toc*}
4004 buffer.  Context will only be shown if the labels are visible as well.
4005 This flag can be toggled from within the @file{*toc*} buffer with the
4006 @kbd{c} key.
4007 @end defopt
4009 @defopt reftex-toc-follow-mode
4010 Non-@code{nil} means, point in @file{*toc*} buffer (the
4011 table-of-contents buffer) will cause other window to follow.  The other
4012 window will show the corresponding part of the document.  This flag can
4013 be toggled from within the @file{*toc*} buffer with the @kbd{f}
4014 key.
4015 @end defopt
4017 @deffn {Normal Hook} reftex-toc-mode-hook
4018 Normal hook which is run when a @file{*toc*} buffer is
4019 created.
4020 @end deffn
4022 @deffn Keymap reftex-toc-map
4023 The keymap which is active in the @file{*toc*} buffer.
4024 (@pxref{Table of Contents}).
4025 @end deffn
4027 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
4028 @section Defining Label Environments
4029 @cindex Options, defining label environments
4030 @cindex Defining label environments, options
4032 @defopt reftex-default-label-alist-entries
4033 Default label alist specifications.  It is a list of symbols with
4034 associations in the constant @code{reftex-label-alist-builtin}.
4035 @code{LaTeX} should always be the last entry.
4036 @end defopt
4038 @defopt reftex-label-alist
4039 Set this variable to define additions and changes to the defaults in
4040 @code{reftex-default-label-alist-entries}.  The only things you
4041 @emph{must not} change is that @code{?s} is the type indicator for
4042 section labels, and @key{SPC} for the @code{any} label type.  These are
4043 hard-coded at other places in the code.
4045 The value of the variable must be a list of items.  Each item is a list
4046 itself and has the following structure:
4048 @example
4049  (@var{env-or-macro}  @var{type-key}  @var{label-prefix}  @var{reference-format}
4050     @var{context-method}  (@var{magic-word} ... )  @var{toc-level})
4051 @end example
4053 Each list entry describes either an environment carrying a counter for
4054 use with @code{\label} and @code{\ref}, or a @LaTeX{} macro defining a
4055 label as (or inside) one of its arguments.  The elements of each list
4056 entry are:
4058 @table @asis
4059 @item @var{env-or-macro}
4060 Name of the environment (like @samp{table}) or macro (like
4061 @samp{\myfig}).  For macros, indicate the arguments, as in
4062 @samp{\myfig[]@{@}@{@}@{*@}@{@}}.  Use square brackets for optional
4063 arguments, a star to mark the label argument, if any.  The macro does
4064 not have to have a label argument; you could also use
4065 @samp{\label@{...@}} inside one of its arguments.
4067 Special names: @code{section} for section labels, @code{any} to define a
4068 group which contains all labels.
4070 This may also be a function to do local parsing and identify point to be
4071 in a non-standard label environment.  The function must take an
4072 argument @var{bound} and limit backward searches to this value.  It
4073 should return either nil or a cons cell @code{(@var{function}
4074 . @var{position})} with the function symbol and the position where the
4075 special environment starts.  See the Info documentation for an
4076 example.
4078 Finally this may also be @code{nil} if the entry is only meant to change
4079 some settings associated with the type indicator character (see
4080 below).
4082 @item @var{type-key}
4083 Type indicator character, like @code{?t}, must be a printable ASCII
4084 character.  The type indicator is a single character which defines a
4085 label type.  Any label inside the environment or macro is assumed to
4086 belong to this type.  The same character may occur several times in this
4087 list, to cover cases in which different environments carry the same
4088 label type (like @code{equation} and @code{eqnarray}).  If the type
4089 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
4090 the macro defines neutral labels just like @code{\label}.  In this case
4091 the remainder of this entry is ignored.
4093 @item @var{label-prefix}
4094 Label prefix string, like @samp{tab:}.  The prefix is a short string
4095 used as the start of a label.  It may be the empty string.  The prefix
4096 may contain the following @samp{%} escapes:
4098 @example
4099 %f Current file name, directory and extension stripped.
4100 %F Current file name relative to master file directory.
4101 %m Master file name, directory and extension stripped.
4102 %M Directory name (without path) where master file is located.
4103 %u User login name, on systems which support this.
4104 %S A section prefix derived with variable @code{reftex-section-prefixes}.
4105 @end example
4107 @noindent
4108 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
4109 @samp{eq:intro:}.
4111 @item @var{reference-format}
4112 Format string for reference insertion in buffer.  @samp{%s} will be
4113 replaced by the label.  When the format starts with @samp{~}, this
4114 @samp{~} will only be inserted when the character before point is
4115 @emph{not} a whitespace.
4117 @item @var{context-method}
4118 Indication on how to find the short context.
4119 @itemize @minus
4120 @item
4121 If @code{nil}, use the text following the @samp{\label@{...@}} macro.
4122 @item
4123 If @code{t}, use
4124 @itemize @minus
4125 @item
4126 the section heading for section labels.
4127 @item
4128 text following the @samp{\begin@{...@}} statement of environments (not
4129 a good choice for environments like eqnarray or enumerate, where one has
4130 several labels in a single environment).
4131 @item
4132 text after the macro name (starting with the first arg) for
4133 macros.
4134 @end itemize
4135 @item
4136 If an integer, use the nth argument of the macro.  As a special case,
4137 1000 means to get text after the last macro argument.
4138 @item
4139 If a string, use as regexp to search @emph{backward} from the label.
4140 Context is then the text following the end of the match.  E.g., setting
4141 this to @samp{\\caption[[@{]} will use the caption in a figure or table
4142 environment.  @samp{\\begin@{eqnarray@}\|\\\\} works for
4143 eqnarrays.
4144 @item
4145 If any of @code{caption}, @code{item}, @code{eqnarray-like},
4146 @code{alignat-like}, this symbol will internally be translated into an
4147 appropriate regexp (see also the variable
4148 @code{reftex-default-context-regexps}).
4149 @item
4150 If a function, call this function with the name of the environment/macro
4151 as argument.  On call, point will be just after the @code{\label} macro.
4152 The function is expected to return a suitable context string.  It should
4153 throw an exception (error) when failing to find context.  As an example,
4154 here is a function returning the 10 chars following the label macro as
4155 context:
4157 @example
4158 (defun my-context-function (env-or-mac)
4159    (if (> (point-max) (+ 10 (point)))
4160        (buffer-substring (point) (+ 10 (point)))
4161      (error "Buffer too small")))
4162 @end example
4163 @end itemize
4165 Label context is used in two ways by @RefTeX{}: For display in the label
4166 menu, and to derive a label string.  If you want to use a different
4167 method for each of these, specify them as a dotted pair.
4168 E.g., @code{(nil . t)} uses the text after the label (@code{nil}) for
4169 display, and text from the default position (@code{t}) to derive a label
4170 string.  This is actually used for section labels.
4172 @item @var{magic-word-list}
4173 List of magic words which identify a reference to be of this type.  If
4174 the word before point is equal to one of these words when calling
4175 @code{reftex-reference}, the label list offered will be automatically
4176 restricted to labels of the correct type.  If the first element of this
4177 word list is the symbol `regexp', the strings are interpreted as regular
4178 expressions.
4180 @item @var{toc-level}
4181 The integer level at which this environment should be added to the table
4182 of contents.  See also @code{reftex-section-levels}.  A positive value
4183 will number the entries mixed with the sectioning commands of the same
4184 level.  A negative value will make unnumbered entries.  Useful only for
4185 theorem-like environments which structure the document.  Will be ignored
4186 for macros.  When omitted or @code{nil}, no TOC entries will be
4187 made.
4188 @end table
4190 If the type indicator characters of two or more entries are the same,
4191 @RefTeX{} will use
4192 @itemize @minus
4193 @item
4194 the first non-@code{nil} format and prefix
4195 @item
4196 the magic words of all involved entries.
4197 @end itemize
4199 Any list entry may also be a symbol.  If that has an association in
4200 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
4201 spliced into the list.  However, builtin defaults should normally be set
4202 with the variable @code{reftex-default-label-alist-entries}.
4203 @end defopt
4205 @defopt reftex-section-prefixes
4206 Prefixes for section labels.  When the label prefix given in an entry in
4207 @code{reftex-label-alist} contains @samp{%S}, this list is used to
4208 determine the correct prefix string depending on the current section
4209 level.  The list is an alist, with each entry of the form
4210 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
4211 names like @samp{chapter}, integer section levels (as given in
4212 @code{reftex-section-levels}), and @code{t} for the default.
4213 @end defopt
4215 @defopt reftex-default-context-regexps
4216 Alist with default regular expressions for finding context.  The emacs
4217 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
4218 to calculate the final regular expression, so @samp{%s} will be
4219 replaced with the environment or macro.
4220 @end defopt
4222 @defopt reftex-trust-label-prefix
4223 Non-@code{nil} means, trust the label prefix when determining label type.
4224 It is customary to use special label prefixes to distinguish different label
4225 types.  The label prefixes have no syntactic meaning in @LaTeX{} (unless
4226 special packages like fancyref) are being used.  RefTeX can and by
4227 default does parse around each label to detect the correct label type,
4228 but this process can be slow when a document contains thousands of
4229 labels.  If you use label prefixes consistently, you may speed up
4230 document parsing by setting this variable to a non-nil value.  RefTeX
4231 will then compare the label prefix with the prefixes found in
4232 `reftex-label-alist' and derive the correct label type in this way.
4233 Possible values for this option are:
4235 @example
4236 t       @r{This means to trust any label prefixes found.}
4237 regexp  @r{If a regexp, only prefixes matched by the regexp are trusted.}
4238 list    @r{List of accepted prefixes, as strings.  The colon is part of}
4239         @r{the prefix, e.g., ("fn:" "eqn:" "item:").}
4240 nil     @r{Never trust a label prefix.}
4241 @end example
4242 The only disadvantage of using this feature is that the label context
4243 displayed in the label selection buffer along with each label is
4244 simply some text after the label definition.  This is no problem if you
4245 place labels keeping this in mind (e.g., @i{before} the equation, @i{at
4246 the beginning} of a fig/tab caption ...).  Anyway, it is probably best
4247 to use the regexp or the list value types to fine-tune this feature.
4248 For example, if your document contains thousands of footnotes with
4249 labels fn:xxx, you may want to set this variable to the value "^fn:$" or
4250 ("fn:").  Then RefTeX will still do extensive parsing for any
4251 non-footnote labels.
4252 @end defopt
4254 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
4255 @section Creating Labels
4256 @cindex Options, creating labels
4257 @cindex Creating labels, options
4259 @defopt reftex-insert-label-flags
4260 Flags governing label insertion.  The value has the form
4262 @example
4263 (@var{derive} @var{prompt})
4264 @end example
4266 If @var{derive} is @code{t}, @RefTeX{} will try to derive a sensible
4267 label from context.  A section label for example will be derived from
4268 the section heading.  The conversion of the context to a valid label is
4269 governed by the specifications given in
4270 @code{reftex-derive-label-parameters}.  If @var{derive} is @code{nil},
4271 the default label will consist of the prefix and a unique number, like
4272 @samp{eq:23}.
4274 If @var{prompt} is @code{t}, the user will be prompted for a label
4275 string.  When @var{prompt} is @code{nil}, the default label will be
4276 inserted without query.
4278 So the combination of @var{derive} and @var{prompt} controls label
4279 insertion.  Here is a table describing all four possibilities:
4281 @example
4282 @group
4283 @var{derive} @var{prompt} @var{action}
4284 -----------------------------------------------------------
4285 nil    nil    @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
4286 nil    t      @r{Prompt for label.}
4287 t      nil    @r{Derive a label from context and insert. No query.}
4288 t      t      @r{Derive a label from context, prompt for confirmation.}
4289 @end group
4290 @end example
4292 Each flag may be set to @code{t}, @code{nil}, or a string of label type
4293 letters indicating the label types for which it should be true.  Thus,
4294 the combination may be set differently for each label type.  The default
4295 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
4296 headings (with confirmation).  Prompt for figure and table labels.  Use
4297 simple labels without confirmation for everything else.
4299 The available label types are: @code{s} (section), @code{f} (figure),
4300 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4301 (footnote), @code{N} (endnote) plus any definitions in
4302 @code{reftex-label-alist}.
4303 @end defopt
4305 @deffn Hook reftex-format-label-function
4306 If non-@code{nil}, should be a function which produces the string to
4307 insert as a label definition.  The function will be called with two
4308 arguments, the @var{label} and the @var{default-format} (usually
4309 @samp{\label@{%s@}}).  It should return the string to insert into the
4310 buffer.
4311 @end deffn
4313 @deffn Hook reftex-string-to-label-function
4314 Function to turn an arbitrary string into a valid label.
4315 @RefTeX{}'s default function uses the variable
4316 @code{reftex-derive-label-parameters}.
4317 @end deffn
4319 @deffn Hook reftex-translate-to-ascii-function
4320 Filter function which will process a context string before it is used to
4321 derive a label from it.  The intended application is to convert ISO or
4322 Mule characters into something valid in labels.  The default function
4323 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
4324 characters.  X-Symbol (>=2.6) sets this variable to the much more
4325 general @code{x-symbol-translate-to-ascii}.
4326 @end deffn
4328 @defopt reftex-derive-label-parameters
4329 Parameters for converting a string into a label.  This variable is a
4330 list of the following items:
4331 @table @asis
4332 @item @var{nwords}
4333 Number of words to use.
4334 @item @var{maxchar}
4335 Maximum number of characters in a label string.
4336 @item @var{invalid}
4337 @code{nil}: Throw away any words containing characters invalid in labels.@*
4338 @code{t}:   Throw away only the invalid characters, not the whole word.
4339 @item @var{abbrev}
4340 @code{nil}: Never abbreviate words.@*
4341 @code{t}:   Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
4342 @code{1}:   Abbreviate words if necessary to shorten label string.
4343 @item @var{separator}
4344 String separating different words in the label.
4345 @item @var{ignorewords}
4346 List of words which should not be part of labels.
4347 @item @var{downcase}
4348 @code{t}:   Downcase words before putting them into the label.@*
4349 @end table
4350 @end defopt
4352 @defopt reftex-label-illegal-re
4353 Regexp matching characters not valid in labels.
4354 @end defopt
4356 @defopt reftex-abbrev-parameters
4357 Parameters for abbreviation of words.  A list of four parameters.
4358 @table @asis
4359 @item @var{min-chars}
4360 Minimum number of characters remaining after abbreviation.
4361 @item @var{min-kill}
4362 Minimum number of characters to remove when abbreviating words.
4363 @item @var{before}
4364 Character class before abbrev point in word.
4365 @item @var{after}
4366 Character class after  abbrev point in word.
4367 @end table
4368 @end defopt
4370 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
4371 @section Referencing Labels
4372 @cindex Options, referencing labels
4373 @cindex Referencing labels, options
4375 @defopt reftex-label-menu-flags
4376 List of flags governing the label menu makeup. The flags are:
4377 @table @asis
4378 @item @var{table-of-contents}
4379 Show the labels embedded in a table of context.
4380 @item @var{section-numbers}
4381 Include section numbers (like 4.1.3) in table of contents.
4382 @item @var{counters}
4383 Show counters.  This just numbers the labels in the menu.
4384 @item @var{no-context}
4385 Non-@code{nil} means do @emph{not} show the short context.
4386 @item @var{follow}
4387 Follow full context in other window.
4388 @item @var{show-commented}
4389 Show labels from regions which are commented out.
4390 @item @var{match-everywhere}
4391 Obsolete flag.
4392 @item @var{show-files}
4393 Show begin and end of included files.
4394 @end table
4396 Each of these flags can be set to @code{t} or @code{nil}, or to a string
4397 of type letters indicating the label types for which it should be true.
4398 These strings work like character classes in regular expressions.  Thus,
4399 setting one of the flags to @samp{"sf"} makes the flag true for section
4400 and figure labels, @code{nil} for everything else.  Setting it to
4401 @samp{"^sf"} makes it the other way round.
4403 The available label types are: @code{s} (section), @code{f} (figure),
4404 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4405 (footnote), plus any definitions in @code{reftex-label-alist}.
4407 Most options can also be switched from the label menu itself, so if you
4408 decide here to not have a table of contents in the label menu, you can
4409 still get one interactively during selection from the label menu.
4410 @end defopt
4412 @defopt reftex-multiref-punctuation
4413 Punctuation strings for multiple references.  When marking is used in
4414 the selection buffer to select several references, this variable
4415 associates the 3 marking characters @samp{,-+} with prefix strings to be
4416 inserted into the buffer before the corresponding @code{\ref} macro.
4417 This is used to string together whole reference sets, like
4418 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
4419 @code{reftex-reference}.
4420 @end defopt
4422 @defopt reftex-ref-style-alist
4423 Alist of reference styles.  Each element is a list of the style name,
4424 the name of the @LaTeX{} package associated with the style or @code{t}
4425 for any package, and an alist of macros where the first entry of each
4426 item is the reference macro and the second a key for selecting the macro
4427 when the macro type is being prompted for.  (See also
4428 @code{reftex-ref-macro-prompt}.)  The keys, represented as characters,
4429 have to be unique.
4430 @end defopt
4432 @defopt reftex-ref-style-default-list
4433 List of reference styles to be activated by default.  The order is
4434 significant and controls the order in which macros can be cycled in the
4435 buffer for selecting a label.  The entries in the list have to match the
4436 respective reference style names used in the variable
4437 @code{reftex-ref-style-alist}.
4438 @end defopt
4440 @defopt reftex-ref-macro-prompt
4441 Controls if @code{reftex-reference} prompts for the reference macro.
4442 @end defopt
4444 @deffn Hook reftex-format-ref-function
4445 If non-@code{nil}, should be a function which produces the string to
4446 insert as a reference.  Note that the insertion format can also be
4447 changed with @code{reftex-label-alist}.  This hook also is used by the
4448 special commands to insert, e.g., @code{\vref} and @code{\fref}
4449 references, so even if you set this, your setting will be ignored by the
4450 special commands.  The function will be called with three arguments, the
4451 @var{label}, the @var{default format} which normally is
4452 @samp{~\ref@{%s@}} and the @var{reference style}.  The function should
4453 return the string to insert into the buffer.
4454 @end deffn
4456 @defopt reftex-level-indent
4457 Number of spaces to be used for indentation per section level.
4458 @end defopt
4460 @defopt reftex-guess-label-type
4461 Non-@code{nil} means, @code{reftex-reference} will try to guess the
4462 label type.  To do that, @RefTeX{} will look at the word before the
4463 cursor and compare it with the magic words given in
4464 @code{reftex-label-alist}.  When it finds a match, @RefTeX{} will
4465 immediately offer the correct label menu; otherwise it will prompt you
4466 for a label type.  If you set this variable to @code{nil}, @RefTeX{}
4467 will always prompt for a label type.
4468 @end defopt
4470 @deffn {Normal Hook} reftex-display-copied-context-hook
4471 Normal Hook which is run before context is displayed anywhere.  Designed
4472 for @w{@code{X-Symbol}}, but may have other uses as well.
4473 @end deffn
4475 @deffn Hook reftex-pre-refontification-functions
4476 @code{X-Symbol} specific hook.  Probably not useful for other purposes.
4477 The functions get two arguments, the buffer from where the command
4478 started and a symbol indicating in what context the hook is
4479 called.
4480 @end deffn
4482 @deffn {Normal Hook} reftex-select-label-mode-hook
4483 Normal hook which is run when a selection buffer enters
4484 @code{reftex-select-label-mode}.
4485 @end deffn
4487 @deffn Keymap reftex-select-label-map
4488 The keymap which is active in the labels selection process
4489 (@pxref{Referencing Labels}).
4490 @end deffn
4492 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
4493 @section Creating Citations
4494 @cindex Options, creating citations
4495 @cindex Creating citations, options
4497 @defopt reftex-bibliography-commands
4498 @LaTeX{} commands which specify the @BibTeX{} databases to use with the document.
4499 @end defopt
4501 @defopt reftex-bibfile-ignore-regexps
4502 List of regular expressions to exclude files in
4503 @code{\\bibliography@{..@}}.  File names matched by any of these regexps
4504 will not be parsed.  Intended for files which contain only
4505 @code{@@string} macro definitions and the like, which are ignored by
4506 @RefTeX{} anyway.
4507 @end defopt
4509 @defopt reftex-default-bibliography
4510 List of @BibTeX{} database files which should be used if none are specified.
4511 When @code{reftex-citation} is called from a document with neither
4512 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4513 environment, @RefTeX{} will scan these files instead.  Intended for
4514 using @code{reftex-citation} in non-@LaTeX{} files.  The files will be
4515 searched along the BIBINPUTS or TEXBIB path.
4516 @end defopt
4518 @defopt reftex-sort-bibtex-matches
4519 Sorting of the entries found in @BibTeX{} databases by reftex-citation.
4520 Possible values:
4521 @example
4522 nil          @r{Do not sort entries.}
4523 author       @r{Sort entries by author name.}
4524 year         @r{Sort entries by increasing year.}
4525 reverse-year @r{Sort entries by decreasing year.}
4526 @end example
4527 @end defopt
4529 @defopt reftex-cite-format
4530 The format of citations to be inserted into the buffer.  It can be a
4531 string, an alist or a symbol.  In the simplest case this is just the string
4532 @samp{\cite@{%l@}}, which is also the default.  See the definition of
4533 @code{reftex-cite-format-builtin} for more complex examples.
4535 If @code{reftex-cite-format} is a string, it will be used as the format.
4536 In the format, the following percent escapes will be expanded.
4538 @table @code
4539 @item %l
4540 The @BibTeX{} label of the citation.
4541 @item %a
4542 List of author names, see also @code{reftex-cite-punctuation}.
4543 @item %2a
4544 Like %a, but abbreviate more than 2 authors like Jones et al.
4545 @item %A
4546 First author name only.
4547 @item %e
4548 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4549 @samp{%E} work a well).
4550 @end table
4552 It is also possible to access all other @BibTeX{} database fields:
4554 @example
4555 %b booktitle     %c chapter        %d edition    %h howpublished
4556 %i institution   %j journal        %k key        %m month
4557 %n number        %o organization   %p pages      %P first page
4558 %r address       %s school         %u publisher  %t title
4559 %v volume        %y year
4560 %B booktitle, abbreviated          %T title, abbreviated
4561 @end example
4563 @noindent
4564 Usually, only @samp{%l} is needed.  The other stuff is mainly for the
4565 echo area display, and for @code{(setq reftex-comment-citations t)}.
4567 @samp{%<} as a special operator kills punctuation and space around it
4568 after the string has been formatted.
4570 A pair of square brackets indicates an optional argument, and RefTeX
4571 will prompt for the values of these arguments.
4573 Beware that all this only works with @BibTeX{} database files.  When
4574 citations are made from the @code{\bibitems} in an explicit
4575 @code{thebibliography} environment, only @samp{%l} is available.
4577 If @code{reftex-cite-format} is an alist of characters and strings, the
4578 user will be prompted for a character to select one of the possible
4579 format strings.
4581 In order to configure this variable, you can either set
4582 @code{reftex-cite-format} directly yourself or set it to the
4583 @emph{symbol} of one of the predefined styles.  The predefined symbols
4584 are those which have an association in the constant
4585 @code{reftex-cite-format-builtin})  E.g.: @code{(setq reftex-cite-format
4586 'natbib)}.
4587 @end defopt
4589 @deffn Hook reftex-format-cite-function
4590 If non-@code{nil}, should be a function which produces the string to
4591 insert as a citation.  Note that the citation format can also be changed
4592 with the variable @code{reftex-cite-format}.  The function will be
4593 called with two arguments, the @var{citation-key} and the
4594 @var{default-format} (taken from @code{reftex-cite-format}).  It should
4595 return the string to insert into the buffer.
4596 @end deffn
4598 @defopt reftex-cite-prompt-optional-args
4599 Non-@code{nil} means, prompt for empty optional arguments in cite macros.
4600 When an entry in @code{reftex-cite-format} ist given with square brackets to
4601 indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
4602 prompt for values.  Possible values are:
4603 @example
4604 nil     @r{Never prompt for optional arguments}
4605 t       @r{Always prompt}
4606 maybe   @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}
4607 @end example
4608 Unnecessary empty optional arguments are removed before insertion into
4609 the buffer.  See @code{reftex-cite-cleanup-optional-args}.
4610 @end defopt
4612 @defopt reftex-cite-cleanup-optional-args
4613 Non-@code{nil} means, remove empty optional arguments from cite macros
4614 if possible.
4615 @end defopt
4617 @defopt reftex-comment-citations
4618 Non-@code{nil} means add a comment for each citation describing the full
4619 entry.  The comment is formatted according to
4620 @code{reftex-cite-comment-format}.
4621 @end defopt
4623 @defopt reftex-cite-comment-format
4624 Citation format used for commented citations.  Must @emph{not} contain
4625 @samp{%l}.  See the variable @code{reftex-cite-format} for possible
4626 percent escapes.
4627 @end defopt
4629 @defopt reftex-cite-punctuation
4630 Punctuation for formatting of name lists in citations.  This is a list
4631 of 3 strings.
4632 @enumerate
4633 @item
4634 normal names separator, like @samp{, } in Jones, Brown and Miller
4635 @item
4636 final names separator, like @samp{ and }  in Jones, Brown and Miller
4637 @item
4638 The @samp{et al.} string, like @samp{ @{\it et al.@}} in
4639 Jones @{\it et al.@}
4640 @end enumerate
4641 @end defopt
4643 @deffn {Normal Hook} reftex-select-bib-mode-hook
4644 Normal hook which is run when a selection buffer enters
4645 @code{reftex-select-bib-mode}.
4646 @end deffn
4648 @deffn Keymap reftex-select-bib-map
4649 The keymap which is active in the citation-key selection process
4650 (@pxref{Creating Citations}).
4651 @end deffn
4653 @defopt reftex-cite-key-separator
4654 String used to separate several keys in a single @samp{\\cite} macro.
4655 Per default this is @samp{","} but if you often have to deal with a lot
4656 of entries and need to break the macro across several lines you might
4657 want to change it to @samp{", "}.
4658 @end defopt
4660 @defopt reftex-create-bibtex-header
4661 Header to insert in BibTeX files generated by
4662 @code{reftex-create-bibtex-file}.
4663 @end defopt
4665 @defopt reftex-create-bibtex-footer
4666 Footer to insert in BibTeX files generated by
4667 @code{reftex-create-bibtex-file}.
4668 @end defopt
4671 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations),  Options
4672 @section Index Support
4673 @cindex Options, Index support
4674 @cindex Index support, options
4676 @defopt reftex-support-index
4677 Non-@code{nil} means, index entries are parsed as well.  Index support
4678 is resource intensive and the internal structure holding the parsed
4679 information can become quite big.  Therefore it can be turned off.  When
4680 this is @code{nil} and you execute a command which requires index
4681 support, you will be asked for confirmation to turn it on and rescan the
4682 document.
4683 @end defopt
4685 @defopt reftex-index-special-chars
4686 List of special characters in index entries, given as strings.  These
4687 correspond to the @code{MakeIndex} keywords
4688 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4689 @end defopt
4691 @defopt reftex-index-macros
4692 List of macros which define index entries.  The structure of each entry
4694 @lisp
4695 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4696 @end lisp
4698 @var{macro} is the macro.  Arguments should be denoted by empty braces,
4699 as for example in @samp{\index[]@{*@}}.  Use square brackets to denote
4700 optional arguments.  The star marks where the index key is.
4702 @var{index-tag} is a short name of the index.  @samp{idx} and @samp{glo}
4703 are reserved for the default index and the glossary.  Other indices can
4704 be defined as well.  If this is an integer, the Nth argument of the
4705 macro holds the index tag.
4707 @var{key} is a character which is used to identify the macro for input
4708 with @code{reftex-index}.  @samp{?i}, @samp{?I}, and @samp{?g} are
4709 reserved for default index and glossary.
4711 @var{prefix} can be a prefix which is added to the @var{key} part of the
4712 index entry.  If you have a macro
4713 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4714 should be @samp{Molecules!}.
4716 @var{exclude} can be a function.  If this function exists and returns a
4717 non-@code{nil} value, the index entry at point is ignored.  This was
4718 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4719 in the @LaTeX{}2e @code{index} package.
4721 @var{repeat}, if non-@code{nil}, means the index macro does not typeset
4722 the entry in the text, so that the text has to be repeated outside the
4723 index macro.  Needed for @code{reftex-index-selection-or-word} and for
4724 indexing from the phrase buffer.
4726 The final entry may also be a symbol.  It must have an association in
4727 the variable @code{reftex-index-macros-builtin} to specify the main
4728 indexing package you are using.  Valid values are currently
4729 @example
4730 default         @r{The @LaTeX{} default; unnecessary to specify this one}
4731 multind         @r{The multind.sty package}
4732 index           @r{The index.sty package}
4733 index-shortcut  @r{The index.sty packages with the ^ and _ shortcuts.}
4734                 @r{Should not be used; only for old documents}
4735 @end example
4736 Note that @AUCTeX{} sets these things internally for @RefTeX{} as well,
4737 so with a sufficiently new version of @AUCTeX{}, you should not set the
4738 package here.
4739 @end defopt
4741 @defopt reftex-index-default-macro
4742 The default index macro for @code{reftex-index-selection-or-word}.
4743 This is a list with @code{(@var{macro-key} @var{default-tag})}.
4745 @var{macro-key} is a character identifying an index macro; see
4746 @code{reftex-index-macros}.
4748 @var{default-tag} is the tag to be used if the macro requires a
4749 @var{tag} argument.  When this is @code{nil} and a @var{tag} is needed,
4750 @RefTeX{} will ask for it.  When this is the empty string and the
4751 TAG argument of the index macro is optional, the TAG argument will be
4752 omitted.
4753 @end defopt
4755 @defopt reftex-index-default-tag
4756 Default index tag.  When working with multiple indexes, RefTeX queries
4757 for an index tag when creating index entries or displaying a specific
4758 index.  This variable controls the default offered for these queries.
4759 The default can be selected with @key{RET} during selection or
4760 completion.  Valid values of this variable are:
4761 @example
4762 nil        @r{Do not provide a default index}
4763 "tag"      @r{The default index tag given as a string, e.g., "idx"}
4764 last       @r{The last used index tag will be offered as default}
4765 @end example
4766 @end defopt
4768 @defopt reftex-index-math-format
4769 Format of index entries when copied from inside math mode.  When
4770 @code{reftex-index-selection-or-word} is executed inside @TeX{} math mode,
4771 the index key copied from the buffer is processed with this format
4772 string through the @code{format} function.  This can be used to add the
4773 math delimiters (e.g., @samp{$}) to the string.  Requires the
4774 @file{texmathp.el} library which is part of @AUCTeX{}.
4775 @end defopt
4777 @defopt reftex-index-phrase-file-extension
4778 File extension for the index phrase file.  This extension will be added
4779 to the base name of the master file.
4780 @end defopt
4782 @defopt reftex-index-phrases-logical-and-regexp
4783 Regexp matching the @samp{and} operator for index arguments in phrases
4784 file.  When several index arguments in a phrase line are separated by
4785 this operator, each part will generate an index macro.  So each match of
4786 the search phrase will produce @emph{several} different index entries.
4787 Make sure this does no match things which are not separators.  This
4788 logical @samp{and} has higher priority than the logical @samp{or}
4789 specified in @code{reftex-index-phrases-logical-or-regexp}.
4790 @end defopt
4792 @defopt reftex-index-phrases-logical-or-regexp
4793 Regexp matching the @samp{or} operator for index arguments in phrases
4794 file.  When several index arguments in a phrase line are separated by
4795 this operator, the user will be asked to select one of them at each
4796 match of the search phrase.  The first index arg will be the default.  A
4797 number key @kbd{1}--@kbd{9} must be pressed to switch to another.  Make
4798 sure this does no match things which are not separators.  The logical
4799 @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4800 has higher priority than this logical @samp{or}.
4801 @end defopt
4803 @defopt reftex-index-phrases-search-whole-words
4804 Non-@code{nil} means phrases search will look for whole words, not subwords.
4805 This works by requiring word boundaries at the beginning and end of
4806 the search string.  When the search phrase already has a non-word-char
4807 at one of these points, no word boundary is required there.
4808 @end defopt
4810 @defopt reftex-index-phrases-case-fold-search
4811 Non-@code{nil} means, searching for index phrases will ignore
4812 case.
4813 @end defopt
4815 @defopt reftex-index-verify-function
4816 A function which is called at each match during global indexing.
4817 If the function returns nil, the current match is skipped.
4818 @end defopt
4820 @defopt reftex-index-phrases-skip-indexed-matches
4821 Non-@code{nil} means, skip matches which appear to be indexed already.
4822 When doing global indexing from the phrases buffer, searches for some
4823 phrases may match at places where that phrase was already indexed.  In
4824 particular when indexing an already processed document again, this
4825 will even be the norm.  When this variable is non-@code{nil},
4826 @RefTeX{} checks if the match is an index macro argument, or if an
4827 index macro is directly before or after the phrase.  If that is the
4828 case, that match will be ignored.
4829 @end defopt
4831 @defopt reftex-index-phrases-wrap-long-lines
4832 Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
4833 Inserting indexing commands in a line makes the line longer, often
4834 so long that it does not fit onto the screen.  When this variable is
4835 non-@code{nil}, newlines will be added as necessary before and/or after the
4836 indexing command to keep lines short.  However, the matched text
4837 phrase and its index command will always end up on a single line.
4838 @end defopt
4840 @defopt reftex-index-phrases-sort-prefers-entry
4841 Non-@code{nil} means when sorting phrase lines, the explicit index entry
4842 is used. Phrase lines in the phrases buffer contain a search phrase, and
4843 sorting is normally based on these.  Some phrase lines also have
4844 an explicit index argument specified.  When this variable is
4845 non-@code{nil}, the index argument will be used for sorting.
4846 @end defopt
4848 @defopt reftex-index-phrases-sort-in-blocks
4849 Non-@code{nil} means, empty and comment lines separate phrase buffer
4850 into blocks.  Sorting will then preserve blocks, so that lines are
4851 re-arranged only within blocks.
4852 @end defopt
4854 @defopt reftex-index-phrases-map
4855 Keymap for the Index Phrases buffer.
4856 @end defopt
4858 @defopt reftex-index-phrases-mode-hook
4859 Normal hook which is run when a buffer is put into
4860 @code{reftex-index-phrases-mode}.
4861 @end defopt
4863 @defopt reftex-index-section-letters
4864 The letters which denote sections in the index.  Usually these are all
4865 capital letters.  Don't use any downcase letters.  Order is not
4866 significant, the index will be sorted by whatever the sort function
4867 thinks is correct.  In addition to these letters, @RefTeX{} will
4868 create a group @samp{!} which contains all entries sorted below the
4869 lowest specified letter.  In the @file{*Index*} buffer, pressing any of
4870 these capital letters or @kbd{!} will jump to that section.
4871 @end defopt
4873 @defopt reftex-index-include-context
4874 Non-@code{nil} means, display the index definition context in the
4875 @file{*Index*} buffer.  This flag may also be toggled from the
4876 @file{*Index*} buffer with the @kbd{c} key.
4877 @end defopt
4879 @defopt reftex-index-follow-mode
4880 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4881 window to follow.  The other window will show the corresponding part of
4882 the document.  This flag can be toggled from within the @file{*Index*}
4883 buffer with the @kbd{f} key.
4884 @end defopt
4886 @deffn Keymap reftex-index-map
4887 The keymap which is active in the @file{*Index*} buffer
4888 (@pxref{Index Support}).
4889 @end deffn
4891 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support),  Options
4892 @section Viewing Cross-References
4893 @cindex Options, viewing cross-references
4894 @cindex Viewing cross-references, options
4896 @defopt reftex-view-crossref-extra
4897 Macros which can be used for the display of cross references.
4898 This is used when `reftex-view-crossref' is called with point in an
4899 argument of a macro.  Note that crossref viewing for citations,
4900 references (both ways) and index entries is hard-coded.  This variable
4901 is only to configure additional structures for which crossreference
4902 viewing can be useful.  Each entry has the structure
4903 @example
4904 (@var{macro-re} @var{search-re} @var{highlight}).
4905 @end example
4906 @var{macro-re} is matched against the macro.  @var{search-re} is the
4907 regexp used to search for cross references.  @samp{%s} in this regexp is
4908 replaced with the macro argument at point.  @var{highlight} is an
4909 integer indicating which subgroup of the match should be highlighted.
4910 @end defopt
4912 @defopt reftex-auto-view-crossref
4913 Non-@code{nil} means, initially turn automatic viewing of crossref info
4914 on.  Automatic viewing of crossref info normally uses the echo area.
4915 Whenever point is idle for more than @code{reftex-idle-time} seconds on
4916 the argument of a @code{\ref} or @code{\cite} macro, and no other
4917 message is being displayed, the echo area will display information about
4918 that cross reference.  You can also set the variable to the symbol
4919 @code{window}.  In this case a small temporary window is used for the
4920 display.  This feature can be turned on and off from the menu
4921 (Ref->Options).
4922 @end defopt
4924 @defopt reftex-idle-time
4925 Time (secs) Emacs has to be idle before automatic crossref display
4926 or toc recentering is done.
4927 @end defopt
4929 @defopt reftex-cite-view-format
4930 Citation format used to display citation info in the message area.  See
4931 the variable @code{reftex-cite-format} for possible percent
4932 escapes.
4933 @end defopt
4935 @defopt reftex-revisit-to-echo
4936 Non-@code{nil} means, automatic citation display will revisit files if
4937 necessary.  When nil, citation display in echo area will only be active
4938 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4939 @BibTeX{} database files which are already visited by a live associated
4940 buffers.
4941 @end defopt
4943 @defopt reftex-cache-cite-echo
4944 Non-@code{nil} means, the information displayed in the echo area for
4945 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4946 saved along with the parsing information.  The cache survives document
4947 scans.  In order to clear it, use @kbd{M-x reftex-reset-mode}.
4948 @end defopt
4950 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References),  Options
4951 @section Finding Files
4952 @cindex Options, Finding Files
4953 @cindex Finding files, options
4955 @defopt reftex-texpath-environment-variables
4956 List of specifications how to retrieve the search path for @TeX{} files.
4957 Several entries are possible.
4958 @itemize @minus
4959 @item
4960 If an element is the name of an environment variable, its content is
4961 used.
4962 @item
4963 If an element starts with an exclamation mark, it is used as a command
4964 to retrieve the path.  A typical command with the kpathsearch library
4965 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4966 @item
4967 Otherwise the element itself is interpreted as a path.
4968 @end itemize
4969 Multiple directories can be separated by the system dependent
4970 @code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
4971 be expanded recursively.  See also @code{reftex-use-external-file-finders}.
4972 @end defopt
4974 @defopt reftex-bibpath-environment-variables
4975 List of specifications how to retrieve the search path for @BibTeX{}
4976 files.  Several entries are possible.
4977 @itemize @minus
4978 @item
4979 If an element is the name of an environment variable, its content is
4980 used.
4981 @item
4982 If an element starts with an exclamation mark, it is used as a command
4983 to retrieve the path.  A typical command with the kpathsearch library
4984 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4985 @item
4986 Otherwise the element itself is interpreted as a path.
4987 @end itemize
4988 Multiple directories can be separated by the system dependent
4989 @code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
4990 be expanded recursively.  See also @code{reftex-use-external-file-finders}.
4991 @end defopt
4993 @defopt reftex-file-extensions
4994 Association list with file extensions for different file types.
4995 This is a list of items, each item is like:
4996 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4997 @example
4998 @var{type}:       @r{File type like @code{"bib"} or @code{"tex"}.}
4999 @var{def-ext}:    @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
5000 @var{other-ext}:  @r{Any number of other valid extensions for this file type.}
5001 @end example
5002 When a files is searched and it does not have any of the valid extensions,
5003 we try the default extension first, and then the naked file name.
5004 @end defopt
5006 @defopt reftex-search-unrecursed-path-first
5007 Non-@code{nil} means, search all specified directories before trying
5008 recursion.  Thus, in a path @samp{.//:/tex/}, search first @samp{./},
5009 then @samp{/tex/}, and then all subdirectories of @samp{./}.  If this
5010 option is @code{nil}, the subdirectories of @samp{./} are searched
5011 before @samp{/tex/}.  This is mainly for speed; most of the time the
5012 recursive path is for the system files and not for the user files.  Set
5013 this to @code{nil} if the default makes @RefTeX{} finding files with
5014 equal names in wrong sequence.
5015 @end defopt
5017 @defopt reftex-use-external-file-finders
5018 Non-@code{nil} means, use external programs to find files.  Normally,
5019 @RefTeX{} searches the paths given in the environment variables
5020 @code{TEXINPUTS} and @code{BIBINPUTS} to find @TeX{} files and @BibTeX{}
5021 database files.  With this option turned on, it calls an external
5022 program specified in the option @code{reftex-external-file-finders}
5023 instead.  As a side effect, the variables
5024 @code{reftex-texpath-environment-variables} and
5025 @code{reftex-bibpath-environment-variables} will be ignored.
5026 @end defopt
5028 @defopt reftex-external-file-finders
5029 Association list with external programs to call for finding files.  Each
5030 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
5031 @var{type} is either @code{"tex"} or @code{"bib"}.  @var{program} is a
5032 string containing the external program to use with any arguments.
5033 @code{%f} will be replaced by the name of the file to be found.  Note
5034 that these commands will be executed directly, not via a shell.  Only
5035 relevant when @code{reftex-use-external-file-finders} is
5036 non-@code{nil}.
5037 @end defopt
5039 @page
5040 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
5041 @section Optimizations
5042 @cindex Options, optimizations
5043 @cindex Optimizations, options
5045 @defopt reftex-keep-temporary-buffers
5046 Non-@code{nil} means, keep buffers created for parsing and lookup.
5047 @RefTeX{} sometimes needs to visit files related to the current
5048 document.  We distinguish files visited for
5049 @table @asis
5050 @item PARSING
5051 Parts of a multifile document loaded when (re)-parsing the
5052 document.
5053 @item LOOKUP
5054 @BibTeX{} database files and @TeX{} files loaded to find a reference, to
5055 display label context, etc.
5056 @end table
5057 The created buffers can be kept for later use, or be thrown away
5058 immediately after use, depending on the value of this variable:
5060 @table @code
5061 @item nil
5062 Throw away as much as possible.
5063 @item t
5064 Keep everything.
5065 @item 1
5066 Throw away buffers created for parsing, but keep the ones created for
5067 lookup.
5068 @end table
5070 If a buffer is to be kept, the file is visited normally (which is
5071 potentially slow but will happen only once). If a buffer is to be thrown
5072 away, the initialization of the buffer depends upon the variable
5073 @code{reftex-initialize-temporary-buffers}.
5074 @end defopt
5076 @defopt reftex-initialize-temporary-buffers
5077 Non-@code{nil} means do initializations even when visiting file
5078 temporarily.  When @code{nil}, @RefTeX{} may turn off find-file hooks and
5079 other stuff to briefly visit a file. When @code{t}, the full default
5080 initializations are done (@code{find-file-hook} etc.).  Instead of
5081 @code{t} or @code{nil}, this variable may also be a list of hook
5082 functions to do a minimal initialization.
5083 @end defopt
5085 @defopt reftex-no-include-regexps
5086 List of regular expressions to exclude certain input files from parsing.
5087 If the name of a file included via @code{\include} or @code{\input} is
5088 matched by any of the regular expressions in this list, that file is not
5089 parsed by @RefTeX{}.
5090 @end defopt
5092 @defopt reftex-enable-partial-scans
5093 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
5094 Re-parsing is normally requested with a @kbd{C-u} prefix to many @RefTeX{}
5095 commands, or with the @kbd{r} key in menus.  When this option is
5096 @code{t} in a multifile document, we will only parse the current buffer,
5097 or the file associated with the label or section heading near point in a
5098 menu.  Requesting re-parsing of an entire multifile document then
5099 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
5100 menus.
5101 @end defopt
5103 @defopt reftex-save-parse-info
5104 Non-@code{nil} means, save information gathered with parsing in files.
5105 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
5106 used to save the information.  When this variable is @code{t},
5107 @itemize @minus
5108 @item
5109 accessing the parsing information for the first time in an editing
5110 session will read that file (if available) instead of parsing the
5111 document.
5112 @item
5113 exiting Emacs or killing a buffer in reftex-mode will cause a new
5114 version of the file to be written.
5115 @end itemize
5116 @end defopt
5118 @defopt reftex-parse-file-extension
5119 File extension for the file in which parser information is stored.
5120 This extension is added to the base name of the master file.
5121 @end defopt
5123 @defopt reftex-allow-automatic-rescan
5124 Non-@code{nil} means, @RefTeX{} may rescan the document when this seems
5125 necessary.  Applies (currently) only in rare cases, when a new label
5126 cannot be placed with certainty into the internal label list.
5127 @end defopt
5129 @defopt reftex-use-multiple-selection-buffers
5130 Non-@code{nil} means use a separate selection buffer for each label
5131 type.  These buffers are kept from one selection to the next and need
5132 not be created for each use, so the menu generally comes up faster.
5133 The selection buffers will be erased (and therefore updated)
5134 automatically when new labels in its category are added.  See the
5135 variable @code{reftex-auto-update-selection-buffers}.
5136 @end defopt
5138 @defopt reftex-auto-update-selection-buffers
5139 Non-@code{nil} means, selection buffers will be updated automatically.
5140 When a new label is defined with @code{reftex-label}, all selection
5141 buffers associated with that label category are emptied, in order to
5142 force an update upon next use.  When @code{nil}, the buffers are left
5143 alone and have to be updated by hand, with the @kbd{g} key from the
5144 label selection process.  The value of this variable will only have any
5145 effect when @code{reftex-use-multiple-selection-buffers} is
5146 non-@code{nil}.
5147 @end defopt
5149 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
5150 @section Fontification
5151 @cindex Options, fontification
5152 @cindex Fontification, options
5154 @defopt reftex-use-fonts
5155 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
5156 Font-lock must be loaded as well to actually get fontified
5157 display.  After changing this option, a rescan may be necessary to
5158 activate it.
5159 @end defopt
5161 @defopt reftex-refontify-context
5162 Non-@code{nil} means, re-fontify the context in the label menu with
5163 font-lock.  This slightly slows down the creation of the label menu.  It
5164 is only necessary when you definitely want the context fontified.
5166 This option may have 3 different values:
5167 @table @code
5168 @item nil
5169 Never refontify.
5170 @item t
5171 Always refontify.
5172 @item 1
5173 Refontify when necessary, e.g., with old versions of the x-symbol
5174 package.
5175 @end table
5176 The option is ignored when @code{reftex-use-fonts} is @code{nil}.
5177 @end defopt
5179 @defopt reftex-highlight-selection
5180 Non-@code{nil} means, highlight selected text in selection and
5181 @file{*toc*} buffers.  Normally, the text near the cursor is the
5182 @emph{selected} text, and it is highlighted.  This is the entry most
5183 keys in the selection and @file{*toc*} buffers act on.  However, if you
5184 mainly use the mouse to select an item, you may find it nice to have
5185 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
5186 variable may have one of these values:
5188 @example
5189 nil      @r{No highlighting.}
5190 cursor   @r{Highlighting is cursor driven.}
5191 mouse    @r{Highlighting is mouse driven.}
5192 both     @r{Both cursor and mouse trigger highlighting.}
5193 @end example
5195 Changing this variable requires to rebuild the selection and *toc*
5196 buffers to become effective (keys @kbd{g} or @kbd{r}).
5197 @end defopt
5199 @defopt reftex-cursor-selected-face
5200 Face name to highlight cursor selected item in toc and selection buffers.
5201 See also the variable @code{reftex-highlight-selection}.
5202 @end defopt
5203 @defopt reftex-mouse-selected-face
5204 Face name to highlight mouse selected item in toc and selection buffers.
5205 See also the variable @code{reftex-highlight-selection}.
5206 @end defopt
5207 @defopt reftex-file-boundary-face
5208 Face name for file boundaries in selection buffer.
5209 @end defopt
5210 @defopt reftex-label-face
5211 Face name for labels in selection buffer.
5212 @end defopt
5213 @defopt reftex-section-heading-face
5214 Face name for section headings in toc and selection buffers.
5215 @end defopt
5216 @defopt reftex-toc-header-face
5217 Face name for the header of a toc buffer.
5218 @end defopt
5219 @defopt reftex-bib-author-face
5220 Face name for author names in bib selection buffer.
5221 @end defopt
5222 @defopt reftex-bib-year-face
5223 Face name for year in bib selection buffer.
5224 @end defopt
5225 @defopt reftex-bib-title-face
5226 Face name for article title in bib selection buffer.
5227 @end defopt
5228 @defopt reftex-bib-extra-face
5229 Face name for bibliographic information in bib selection buffer.
5230 @end defopt
5231 @defopt reftex-select-mark-face
5232 Face name for marked entries in the selection buffers.
5233 @end defopt
5234 @defopt reftex-index-header-face
5235 Face name for the header of an index buffer.
5236 @end defopt
5237 @defopt reftex-index-section-face
5238 Face name for the start of a new letter section in the index.
5239 @end defopt
5240 @defopt reftex-index-tag-face
5241 Face name for index names (for multiple indices).
5242 @end defopt
5243 @defopt reftex-index-face
5244 Face name for index entries.
5245 @end defopt
5247 @node Options (Misc), , Options (Fontification), Options
5248 @section Miscellaneous
5249 @cindex Options, misc
5251 @defopt reftex-extra-bindings
5252 Non-@code{nil} means, make additional key bindings on startup.  These
5253 extra bindings are located in the users @samp{C-c letter}
5254 map.  @xref{Key Bindings}.
5255 @end defopt
5257 @defopt reftex-plug-into-AUCTeX
5258 Plug-in flags for @AUCTeX{} interface.  This variable is a list of
5259 5 boolean flags.  When a flag is non-@code{nil}, @RefTeX{}
5260 will
5262 @example
5263 - supply labels in new sections and environments  (flag 1)
5264 - supply arguments for macros like @code{\label}         (flag 2)
5265 - supply arguments for macros like @code{\ref}           (flag 3)
5266 - supply arguments for macros like @code{\cite}          (flag 4)
5267 - supply arguments for macros like @code{\index}         (flag 5)
5268 @end example
5270 You may also set the variable itself to t or nil in order to turn all
5271 options on or off, respectively.@*
5272 Supplying labels in new sections and environments applies when creating
5273 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
5274 Supplying macro arguments applies when you insert such a macro
5275 interactively with @kbd{C-c @key{RET}}.@*
5276 See the @AUCTeX{} documentation for more information.
5277 @end defopt
5279 @defopt reftex-revisit-to-follow
5280 Non-@code{nil} means, follow-mode will revisit files if necessary.
5281 When nil, follow-mode will be suspended for stuff in unvisited files.
5282 @end defopt
5284 @defopt reftex-allow-detached-macro-args
5285 Non-@code{nil} means, allow arguments of macros to be detached by
5286 whitespace.  When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
5287 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}.  Note that
5288 this will be the case even if @code{\bb} is defined with zero or one
5289 argument.
5290 @end defopt
5292 @node Keymaps and Hooks, Changes, Options, Top
5293 @section Keymaps and Hooks
5294 @cindex Keymaps
5296 @RefTeX{} has the usual general keymap, load hook and mode hook.
5298 @deffn Keymap reftex-mode-map
5299 The keymap for @RefTeX{} mode.
5300 @end deffn
5302 @deffn {Normal Hook} reftex-load-hook
5303 Normal hook which is being run when loading @file{reftex.el}.
5304 @end deffn
5306 @deffn {Normal Hook} reftex-mode-hook
5307 Normal hook which is being run when turning on @RefTeX{} mode.
5308 @end deffn
5310 Furthermore, the four modes used for referencing labels, creating
5311 citations, the table of contents buffer and the phrases buffer have
5312 their own keymaps and mode hooks.  See the respective sections.  There
5313 are many more hooks which are described in the relevant sections about
5314 options for a specific part of @RefTeX{}.
5316 @node Changes, GNU Free Documentation License, Keymaps and Hooks, Top
5317 @chapter Changes
5318 @cindex Changes
5320 Here is a list of recent changes to @RefTeX{}.
5322 @noindent @b{Version 4.33}
5324 @itemize @bullet
5325 @item
5326 Update to GPLv3.
5327 @item
5328 Parse files are created in a way that does not interfere with recentf
5329 mode.
5330 @end itemize
5332 @noindent @b{Version 4.32}
5334 @itemize @bullet
5335 @item
5336 First release by @AUCTeX{} project.
5337 @item
5338 Installation routine rewritten after structure of source package
5339 changed.
5340 @item
5341 Activation of @RefTeX{} changed, so make sure you read the installation
5342 instructions and remove obsolete cruft related to @RefTeX{} from your
5343 init file.
5344 @item
5345 Fixed bug where point would end up in the wrong buffer when jumping
5346 between several @LaTeX{} and phrases buffers.
5347 @item
5348 Fixed bug where @BibTeX{} keys with hyphens were parsed incorrectly.
5349 @item
5350 Some performance improvements.
5351 @item
5352 The separator used between multiple citations in a \cite macro can now
5353 be changed by customizing the variable @code{reftex-cite-key-separator}.
5354 @end itemize
5356 @noindent @b{Version 4.28}
5357 @itemize @bullet
5358 @item Support for the Jurabib package.
5359 @item Improvements when selecting several items in a selection buffer.
5360 @end itemize
5362 @noindent @b{Version 4.26}
5363 @itemize @bullet
5364 @item
5365 Support for global incremental search.
5366 @item
5367 Some improvements for XEmacs compatibility.
5368 @end itemize
5370 @noindent @b{Version 4.25}
5371 @itemize @bullet
5372 @item
5373 Fixed bug with @samp{%F} in a label prefix.  Added new escapes
5374 @samp{%m} and @samp{%M} for mater file name and master directory.
5375 @end itemize
5377 @noindent @b{Version 4.24}
5378 @itemize @bullet
5379 @item
5380 Inserting citation commands now prompts for optional arguments
5381 when called with a prefix argument.  Related new options are
5382 @code{reftex-cite-prompt-optional-args} and
5383 @code{reftex-cite-cleanup-optional-args}.
5384 @item
5385 New option @code{reftex-trust-label-prefix}.  Configure this variable
5386 if you'd like RefTeX to base its classification of labels on prefixes.
5387 This can speed-up document parsing, but may in some cases reduce the
5388 quality of the context used by RefTeX to describe a label.
5389 @item
5390 Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
5391 is non-nil.
5392 @item
5393 Fixed bugs in indexing: Case-sensitive search, quotes before and/or
5394 after words.  Disabled indexing in comment lines.
5395 @end itemize
5397 @noindent @b{Version 4.22}
5398 @itemize @bullet
5399 @item
5400 New command @code{reftex-create-bibtex-file} to create a new database
5401 with all entries referenced in the current document.
5402 @item
5403 New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
5404 from entries marked in a citation selection buffer.
5405 @end itemize
5407 @noindent @b{Version 4.21}
5408 @itemize @bullet
5409 @item
5410 Renaming labels from the toc buffer with key @kbd{M-%}.
5411 @end itemize
5413 @noindent @b{Version 4.20}
5414 @itemize @bullet
5415 @item
5416 Structure editing capabilities.  The command keys @kbd{<} and @kbd{>} in
5417 the TOC buffer promote/demote the section at point or all sections in
5418 the current region.
5419 @item
5420 New option @code{reftex-toc-split-windows-fraction} to set the size of
5421 the window used by the TOC@.  This makes the old variable
5422 @code{reftex-toc-split-windows-horizontally-fraction} obsolete.
5423 @item
5424 A dedicated frame can show the TOC with the current section
5425 always automatically highlighted.  The frame is created and
5426 deleted from the toc buffer with the @kbd{d} key.
5427 @end itemize
5429 @noindent @b{Version 4.19}
5430 @itemize @bullet
5431 @item
5432 New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
5433 section in the TOC buffer without selecting the TOC window.
5434 @item
5435 Recentering happens automatically in idle time when the option
5436 @code{reftex-auto-recenter-toc} is turned on.
5437 @item
5438 Fixed several bugs related to automatic cursor positioning in the TOC
5439 buffer.
5440 @item
5441 The highlight in the TOC buffer stays when the focus moves to a
5442 different window.
5443 @item
5444 New command `reftex-goto-label'.
5445 @item
5446 Part numbers are no longer included in chapter numbers, and a new
5447 part does not reset the chapter counter.  See new option
5448 @code{reftex-part-resets-chapter}.
5449 @end itemize
5451 @noindent @b{Version 4.18}
5452 @itemize @bullet
5453 @item
5454 @code{reftex-citation} uses the word before the cursor as a default
5455 search string.
5456 @item
5457 Simplified several regular expressions for speed.
5458 @item
5459 Better support for chapterbib.
5460 @end itemize
5462 @noindent @b{Version 4.17}
5463 @itemize @bullet
5464 @item
5465 The toc window can be split off horizontally.  See new options
5466 @code{reftex-toc-split-windows-horizontally},
5467 @code{reftex-toc-split-windows-horizontally-fraction}.
5468 @item
5469 It is possible to specify a function which verifies an index match
5470 during global indexing.  See new option @code{reftex-index-verify-function}.
5471 @item
5472 The macros which input a file in LaTeX (like \input, \include) can
5473 be configured.  See new option @code{reftex-include-file-commands}.
5474 @item
5475 The macros which specify the bibliography file (like \bibliography) can
5476 be configured.  See new option @code{reftex-bibliography-commands}.
5477 @item
5478 The regular expression used to search for the \bibliography macro has
5479 been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
5480 chapterbib.
5481 @item
5482 Small bug fixes.
5483 @end itemize
5485 @noindent @b{Version 4.15}
5486 @itemize @bullet
5487 @item
5488 Fixed bug with parsing of BibTeX files, when fields contain quotes or
5489 unmatched parenthesis.
5490 @item
5491 Small bug fixes.
5492 @item
5493 Improved interaction with Emacs LaTeX mode.
5494 @end itemize
5496 @noindent @b{Version 4.12}
5497 @itemize @bullet
5498 @item
5499 Support for @file{bibentry} citation style.
5500 @end itemize
5502 @noindent @b{Version 4.11}
5503 @itemize @bullet
5504 @item
5505 Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5506 @end itemize
5508 @noindent @b{Version 4.10}
5509 @itemize @bullet
5510 @item
5511 Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5512 with @file{reftex-vars.el} on DOS machines.
5513 @item
5514 New options @code{reftex-parse-file-extension} and
5515 @code{reftex-index-phrase-file-extension}.
5516 @end itemize
5518 @noindent [.....]
5519 @ignore
5520 @noindent @b{Version 4.09}
5521 @itemize @bullet
5522 @item
5523 New option @code{reftex-toc-max-level} to limit the depth of the toc.
5524 New key binding @kbd{t} in the @file{*toc*} buffer to change this
5525 setting.
5526 @item
5527 RefTeX maintains an @file{Index Phrases} file in which phrases can be
5528 collected.  When the document is ready, RefTeX can search all
5529 these phrases and assist indexing all matches.
5530 @item
5531 The variables @code{reftex-index-macros} and
5532 @code{reftex-index-default-macro} have changed their syntax slightly.
5533 The @var{repeat} parameter has move from the latter to the former.
5534 Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5535 need to be adapted.
5536 @item
5537 The variable @code{reftex-section-levels} no longer contains the
5538 default stuff which has been moved to a constant.
5539 @item
5540 Environments like theorems can be placed into the TOC by putting
5541 entries for @samp{"begin@{theorem@}"} in
5542 @code{reftex-section-levels}.
5543 @end itemize
5545 @noindent @b{Version 4.06}
5546 @itemize @bullet
5547 @item
5548 @code{reftex-section-levels} can contain a function to compute the level
5549 of a sectioning command.
5550 @item
5551 Multiple @code{thebibliography} environments recognized.
5552 @end itemize
5554 @noindent @b{Version 4.04}
5555 @itemize @bullet
5556 @item
5557 New option @code{reftex-index-default-tag} implements a default for queries.
5558 @end itemize
5560 @noindent @b{Version 4.02}
5561 @itemize @bullet
5562 @item
5563 macros ending in @samp{refrange} are considered to contain references.
5564 @item
5565 Index entries made with @code{reftex-index-selection-or-word} in TeX
5566 math mode automatically get enclosing @samp{$} to preserve math mode.  See
5567 new option @code{reftex-index-math-format}.  Requires AUCTeX.
5568 @end itemize
5570 @noindent @b{Version 4.01}
5571 @itemize @bullet
5572 @item
5573 New command @code{reftex-index-globally} to index a word in many
5574 places in the document.  Also available from the index buffer with
5575 @kbd{&}.
5576 @item
5577 The first item in a @code{reftex-label-alist} entry may now also be a parser
5578 function to do non-standard parsing.
5579 @item
5580 @code{reftex-auto-view-crossref} no longer interferes with
5581 @code{pop-up-frames} (patch from Stefan Monnier).
5582 @end itemize
5584 @noindent @b{Version 4.00}
5585 @itemize @bullet
5586 @item
5587 RefTeX has been split into several smaller files which are autoloaded on
5588 demand.
5589 @item
5590 Index support, along with many new options.
5591 @item
5592 The selection of keys for @code{\ref} and @code{\cite} now allows to
5593 select multiple items by marking entries with the @kbd{m} key.
5594 @item
5595 Fancyref support.
5596 @end itemize
5598 @noindent @b{Version 3.43}
5599 @itemize @bullet
5600 @item
5601 Viewing cross-references generalized.  Now works on @code{\label},
5602 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5603 these, and from BibTeX buffers.
5604 @item
5605 New option @code{reftex-view-crossref-extra}.
5606 @item
5607 Support for the additional sectioning commands @code{\addchap} and
5608 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.
5609 @item
5610 Files in @code{reftex-default-bibliography} will be searched along
5611 @code{BIBINPUTS} path.
5612 @item
5613 Reading a parse file now checks consistency.
5614 @end itemize
5616 @noindent @b{Version 3.42}
5617 @itemize @bullet
5618 @item
5619 File search further refined.  New option @code{reftex-file-extensions}.
5620 @item
5621 @file{*toc*} buffer can show the file boundaries of a multifile
5622 document, all labels and associated context.  New keys @kbd{i}, @kbd{l},
5623 and @kbd{c}.  New options @code{reftex-toc-include-labels},
5624 @code{reftex-toc-include-context},
5625 @code{reftex-toc-include-file-boundaries}.
5626 @end itemize
5628 @noindent @b{Version 3.41}
5629 @itemize @bullet
5630 @item
5631 New options @code{reftex-texpath-environment-variables},
5632 @code{reftex-use-external-file-finders},
5633 @code{reftex-external-file-finders},
5634 @code{reftex-search-unrecursed-path-first}.
5635 @item
5636 @emph{kpathsearch} support.  See new options and
5637 @code{reftex-bibpath-environment-variables}.
5638 @end itemize
5640 @noindent @b{Version 3.38}
5641 @itemize @bullet
5642 @item
5643 @code{reftex-view-crossref} no longer moves to find a macro.  Point has
5644 to be on the macro argument.
5645 @end itemize
5647 @noindent @b{Version 3.36}
5648 @itemize @bullet
5649 @item
5650 New value @code{window} for option @code{reftex-auto-view-crossref}.
5651 @end itemize
5653 @noindent @b{Version 3.35}
5654 @itemize @bullet
5655 @item
5656 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5657 This takes back the related changes in 3.34 for safety reasons.
5658 @end itemize
5660 @noindent @b{Version 3.34}
5661 @itemize @bullet
5662 @item
5663 Additional flag in @code{reftex-derive-label-parameters} do make only
5664 lowercase labels (default @code{t}).
5665 @item
5666 All @file{.rel} files have a final newline to avoid queries.
5667 @item
5668 Single byte representations of accented European letters (ISO-8859-1)
5669 are now valid in labels.
5670 @end itemize
5672 @noindent @b{Version 3.33}
5673 @itemize @bullet
5674 @item
5675 Multiple selection buffers are now hidden buffers (they start with a
5676 SPACE).
5677 @item
5678 Fixed bug with file search when TEXINPUTS environment variable is empty.
5679 @end itemize
5681 @noindent @b{Version 3.30}
5682 @itemize @bullet
5683 @item
5684 In @code{reftex-citation}, the regular expression used to scan BibTeX
5685 files can be specified using completion on known citation keys.
5686 @item
5687 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5688 entries.
5689 @item
5690 New command @code{reftex-renumber-simple-labels} to renumber simple
5691 labels like @samp{eq:13} sequentially through a document.
5692 @end itemize
5694 @noindent @b{Version 3.28}
5695 @itemize @bullet
5696 @item
5697 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5698 timer, since itimer restart is not reliable.
5699 @item
5700 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5701 @item
5702 Expansion of recursive tex and bib path rewritten.
5703 @item
5704 Fixed problem where @RefTeX{} did not scan unsaved buffers.
5705 @item
5706 Fixed bug with section numbering after *-red sections.
5707 @end itemize
5709 @noindent @b{Version 3.27}
5710 @itemize @bullet
5711 @item
5712 Macros can define @emph{neutral} labels, just like @code{\label}
5713 itself.
5714 @item
5715 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5716 @end itemize
5718 @noindent @b{Version 3.26}
5719 @itemize @bullet
5720 @item
5721 [X]Emacs 19 no longer supported.  Use 3.22 for Emacs 19.
5722 @item
5723 New hooks @code{reftex-translate-to-ascii-function},
5724 @code{reftex-string-to-label-function}.
5725 @item
5726 Made sure automatic crossref display will not visit/scan files.
5727 @end itemize
5729 @noindent @b{Version 3.25}
5730 @itemize @bullet
5731 @item
5732 Echoing of citation info caches the info for displayed entries.
5733 New option @code{reftex-cache-cite-echo}.
5734 @item
5735 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
5736 info.
5737 @item
5738 Default of @code{reftex-revisit-to-follow} changed to nil.
5739 @end itemize
5741 @noindent @b{Version 3.24}
5742 @itemize @bullet
5743 @item
5744 New option @code{reftex-revisit-to-echo}.
5745 @item
5746 Interface with X-Symbol (>=2.6) is now complete and stable.
5747 @item
5748 Adapted to new outline, which uses overlays.
5749 @item
5750 File names in @code{\bibliography} may now have the @code{.bib}
5751 extension.
5752 @item
5753 Fixed Bug with parsing "single file" from master file buffer.
5754 @end itemize
5756 @noindent @b{Version 3.23}
5757 @itemize @bullet
5758 @item
5759 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5760 @item
5761 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
5762 file.
5763 @item
5764 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5765 automatic display of crossref information in the echo area.  See
5766 variable @code{reftex-auto-view-crossref}.
5767 @item
5768 AUCTeX interface updates:
5769 @itemize @minus
5770 @item
5771 AUCTeX 9.9c and later notifies @RefTeX{} about new sections.
5772 @item
5773 @RefTeX{} notifies AUCTeX about new labels.
5774 @item
5775 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
5776 @item
5777 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5778 @item
5779 Settings added to @RefTeX{} via style files remain local.
5780 @end itemize
5781 @item
5782 Fixed bug with @code{reftex-citation} in non-latex buffers.
5783 @item
5784 Fixed bug with syntax table and context refontification.
5785 @item
5786 Safety-net for name change of @code{font-lock-reference-face}.
5787 @end itemize
5789 @noindent @b{Version 3.22}
5790 @itemize @bullet
5791 @item
5792 Fixed bug with empty context strings.
5793 @item
5794 @code{reftex-mouse-view-crossref} is now bound by default at
5795 @kbd{S-mouse-2}.
5796 @end itemize
5798 @noindent @b{Version 3.21}
5799 @itemize @bullet
5800 @item
5801 New options for all faces used by @RefTeX{}. They're in the
5802 customization group @code{reftex-fontification-configurations}.
5803 @end itemize
5805 @noindent @b{Version 3.19}
5806 @itemize @bullet
5807 @item
5808 Fixed bug with AUCTeX @code{TeX-master}.
5809 @end itemize
5811 @noindent @b{Version 3.18}
5812 @itemize @bullet
5813 @item
5814 The selection now uses a recursive edit, much like minibuffer input.
5815 This removes all restrictions during selection.  E.g., you can now
5816 switch buffers at will, use the mouse etc.
5817 @item
5818 New option @code{reftex-highlight-selection}.
5819 @item
5820 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
5821 buffers.
5822 @item
5823 Fixed some problems regarding the interaction with VIPER mode.
5824 @item
5825 Follow-mode is now only used after point motion.
5826 @item
5827 @RefTeX{} now finally does not fontify temporary files anymore.
5828 @end itemize
5830 @noindent @b{Version 3.17}
5831 @itemize @bullet
5832 @item
5833 Additional bindings in selection and @file{*toc*} buffers.  @kbd{g}
5834 redefined.
5835 @item
5836 New command @code{reftex-save-all-document-buffers}.
5837 @item
5838 Magic word matching made more intelligent.
5839 @item
5840 Selection process can switch to completion (with @key{TAB}).
5841 @item
5842 @code{\appendix} is now recognized and influences section numbering.
5843 @item
5844 File commentary shortened considerably (use Info documentation).
5845 @item
5846 New option @code{reftex-no-include-regexps} to skip some include files.
5847 @item
5848 New option @code{reftex-revisit-to-follow}.
5849 @end itemize
5851 @noindent @b{Version 3.16}
5852 @itemize @bullet
5853 @item
5854 New hooks @code{reftex-format-label-function},
5855 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
5856 @item
5857 TeXInfo documentation completed.
5858 @item
5859 Some restrictions in Label inserting and referencing removed.
5860 @item
5861 New variable @code{reftex-default-bibliography}.
5862 @end itemize
5864 @noindent @b{Version 3.14}
5865 @itemize @bullet
5866 @item
5867 Selection buffers can be kept between selections: this is faster.
5868 See new variable @code{reftex-use-multiple-selection-buffers}.
5869 @item
5870 Prefix interpretation of reftex-view-crossref changed.
5871 @item
5872 Support for the @code{varioref} package (@kbd{v} key in selection
5873 buffer).
5874 @end itemize
5876 @noindent @b{Version 3.12}
5877 @itemize @bullet
5878 @item
5879 There are 3 new keymaps for customization: @code{reftex-toc-map},
5880 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5881 @item
5882 Refontification uses more standard font-lock stuff.
5883 @item
5884 When no BibTeX database files are specified, citations can also use
5885 @code{\bibitem} entries from a @code{thebibliography} environment.
5886 @end itemize
5888 @noindent @b{Version 3.11}
5889 @itemize @bullet
5890 @item
5891 Fixed bug which led to naked label in (e.g.@:) footnotes.
5892 @item
5893 Added scroll-other-window functions to RefTeX-Select.
5894 @end itemize
5896 @noindent @b{Version 3.10}
5897 @itemize @bullet
5898 @item
5899 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5900 @item
5901 Removed unimportant code which caused OS/2 Emacs to crash.
5902 @item
5903 All customization variables now accessible from menu.
5904 @end itemize
5906 @noindent @b{Version 3.07}
5907 @itemize @bullet
5908 @item
5909 @code{Ref} menu improved.
5910 @end itemize
5912 @noindent @b{Version 3.05}
5913 @itemize @bullet
5914 @item
5915 Compatibility code now first checks for XEmacs feature.
5916 @end itemize
5918 @noindent @b{Version 3.04}
5919 @itemize @bullet
5920 @item
5921 Fixed BUG in the @emph{xr} support.
5922 @end itemize
5924 @noindent @b{Version 3.03}
5925 @itemize @bullet
5926 @item
5927 Support for the LaTeX package @code{xr}, for inter-document
5928 references.
5929 @item
5930 A few (minor) Mule-related changes.
5931 @item
5932 Fixed bug which could cause @emph{huge} @file{.rel} files.
5933 @item
5934 Search for input and @file{.bib} files with recursive path definitions.
5935 @end itemize
5937 @noindent @b{Version 3.00}
5938 @itemize @bullet
5939 @item
5940 @RefTeX{} should work better for very large projects:
5941 @item
5942 The new parser works without creating a master buffer.
5943 @item
5944 Rescanning can be limited to a part of a multifile document.
5945 @item
5946 Information from the parser can be stored in a file.
5947 @item
5948 @RefTeX{} can deal with macros having a naked label as an argument.
5949 @item
5950 Macros may have white space and newlines between arguments.
5951 @item
5952 Multiple identical section headings no longer confuse
5953 @code{reftex-toc}.
5954 @item
5955 @RefTeX{} should work correctly in combination with buffer-altering
5956 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
5957 @item
5958 All labeled environments discussed in @emph{The LaTeX Companion} by
5959 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
5960 @RefTeX{}'s defaults.
5961 @end itemize
5963 @noindent @b{Version 2.17}
5964 @itemize @bullet
5965 @item
5966 Label prefix expands % escapes with current file name and other stuff.
5967 @item
5968 Citation format now with % escapes.  This is not backward
5969 compatible!
5970 @item
5971 TEXINPUTS variable recognized when looking for input files.
5972 @item
5973 Context can be the nth argument of a macro.
5974 @item
5975 Searching in the select buffer is now possible (@kbd{C-s} and
5976 @kbd{C-r}).
5977 @item
5978 Display and derive-label can use two different context methods.
5979 @item
5980 AMSmath @code{xalignat} and @code{xxalignat} added.
5981 @end itemize
5983 @noindent @b{Version 2.14}
5984 @itemize @bullet
5985 @item
5986 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
5987 AUCTeX.
5988 @end itemize
5990 @noindent @b{Version 2.11}
5991 @itemize @bullet
5992 @item
5993 Submitted for inclusion to Emacs and XEmacs.
5994 @end itemize
5996 @noindent @b{Version 2.07}
5997 @itemize @bullet
5998 @item
5999 New functions @code{reftex-search-document},
6000 @code{reftex-query-replace-document}.
6001 @end itemize
6003 @noindent @b{Version 2.05}
6004 @itemize @bullet
6005 @item
6006 Support for @file{custom.el}.
6007 @item
6008 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
6009 @end itemize
6011 @noindent @b{Version 2.03}
6012 @itemize @bullet
6013 @item
6014 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
6015 default environments.
6016 @item
6017 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
6018 @item
6019 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
6020 @code{reftex-arg-cite}.
6021 @item
6022 Emacs/XEmacs compatibility reworked.  XEmacs 19.15 now is
6023 required.
6024 @item
6025 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
6026 files).
6027 @item
6028 Finding context with a hook function.
6029 @item
6030 Sorting BibTeX entries (new variable:
6031 @code{reftex-sort-bibtex-matches}).
6032 @end itemize
6034 @noindent @b{Version 2.00}
6035 @itemize @bullet
6036 @item
6037 Labels can be derived from context (default for sections).
6038 @item
6039 Configuration of label insertion and label referencing revised.
6040 @item
6041 Crossref fields in BibTeX database entries.
6042 @item
6043 @code{reftex-toc} introduced (thanks to Stephen Eglen).
6044 @end itemize
6046 @noindent @b{Version 1.09}
6047 @itemize @bullet
6048 @item
6049 Support for @code{tex-main-file}, an analogue for
6050 @code{TeX-master}.
6051 @item
6052 MS-DOS support.
6053 @end itemize
6055 @noindent @b{Version 1.07}
6056 @itemize @bullet
6057 @item
6058 @RefTeX{} gets its own menu.
6059 @end itemize
6061 @noindent @b{Version 1.05}
6062 @itemize @bullet
6063 @item
6064 XEmacs port.
6065 @end itemize
6067 @noindent @b{Version 1.04}
6068 @itemize @bullet
6069 @item
6070 Macros as wrappers, AMSTeX support, delayed context parsing for
6071 new labels.
6072 @end itemize
6073 @end ignore
6075 @noindent @b{Version 1.00}
6076 @itemize @bullet
6077 @item
6078 released on 7 Jan 1997.
6079 @end itemize
6081 @node GNU Free Documentation License, Index, Changes, Top
6082 @appendix GNU Free Documentation License
6083 @include doclicense.texi
6085 @node Index, , GNU Free Documentation License, Top
6086 @unnumbered Index
6087 @printindex cp
6089 @bye