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