*** empty log message ***
[emacs.git] / man / reftex.texi
blob64f66dca4e19de3c18abacd8c50a4586e2876846
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../info/reftex
4 @settitle RefTeX User Manual
5 @dircategory Emacs
6 @direntry
7 * RefTeX: (reftex).     Emacs support for LaTeX cross-references and citations.
8 @end direntry
9 @synindex ky cp
10 @syncodeindex vr cp
11 @syncodeindex fn cp
12 @set VERSION 4.12
13 @set EDITION 4.12
14 @set DATE March 2000
15 @set AUTHOR Carsten Dominik
16 @set AUTHOR-EMAIL dominik@@astro.uva.nl
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINER-EMAIL dominik@@astro.uva.nl
19 @c %**end of header
20 @finalout
22 @c Macro definitions
24 @c Subheadings inside a table.  Need a difference between info and the rest.
25 @macro tablesubheading{text}
26 @ifinfo
27 @subsubheading \text\
28 @end ifinfo
29 @ifnotinfo
30 @item @b{\text\}
31 @end ifnotinfo
32 @end macro
34 @ifinfo
35 This file documents @b{Ref@TeX{}}, a package to do labels, references,
36 citations and indices for LaTeX documents with Emacs.@refill
38 This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
39 @b{Ref@TeX{}} @value{VERSION}@refill
41 Copyright (c) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
43 Permission is granted to make and distribute verbatim
44 copies of this manual provided the copyright notice and
45 this permission notice are preserved on all copies.
46      
47 @ignore
48 Permission is granted to process this file through TeX
49 and print the results, provided the printed document
50 carries a copying permission notice identical to this
51 one except for the removal of this paragraph (this
52 paragraph not being relevant to the printed manual).
53      
54 @end ignore
55 Permission is granted to copy and distribute modified
56 versions of this manual under the conditions for
57 verbatim copying, provided that the entire resulting
58 derive work is distributed under the terms of a permission
59 notice identical to this one.
60      
61 Permission is granted to copy and distribute
62 translations of this manual into another language,
63 under the above conditions for modified versions,
64 except that this permission notice may be stated in a
65 translation approved by the Free Software Foundation.
66 @end ifinfo
68 @titlepage
69 @title Ref@TeX{} User Manual
70 @subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
71 @subtitle Edition @value{EDITION}, @value{DATE}
73 @author by Carsten Dominik
74 @page
75 Copyright @copyright{} 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
77 @sp 2
78 This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
79 @b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
81 @sp 2
83 Permission is granted to make and distribute verbatim
84 copies of this manual provided the copyright notice and
85 this permission notice are preserved on all copies.
86      
87 Permission is granted to copy and distribute modified
88 versions of this manual under the conditions for
89 verbatim copying, provided that the entire resulting
90 derive work is distributed under the terms of a permission
91 notice identical to this one.
92      
93 Permission is granted to copy and distribute
94 translations of this manual into another language,
95 under the above conditions for modified versions,
96 except that this permission notice may be stated in a
97 translation approved by the Free Software Foundation.
99 @end titlepage
100 @page
102 @ifnottex
103 @node Top,,,(dir)
105 @b{Ref@TeX{}} is a package for managing Labels, References,
106 Citations and index entries with GNU Emacs.@refill
108 Don't be discouraged by the size of this manual, which covers
109 @b{Ref@TeX{}} in great depth.  All you need to know to use
110 @b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
111 Nutshell}).  You can go back later to other parts of this document when
112 needed.@refill
114 @menu
115 * Introduction::                     Quick-Start information.
117 * Table of Contents::                A Tool to move around quickly.
118 * Labels and References::            Creating and referencing labels.
119 * Citations::                        Creating Citations.
120 * Index Support::                    Creating and Checking Index Entries.
121 * Viewing Cross-References::         Who references or cites what?
123 * RefTeXs Menu::                     The Ref menu in the menubar.
124 * Keybindings::                      The default keybindings.
125 * Faces::                            Fontification of RefTeX's buffers.
126 * Multifile Documents::              Document spread over many files.
127 * Language Support::                 How to support other languages.
128 * Finding Files::                    Included TeX files and BibTeX .bib files.
129 * AUCTeX::                           Cooperation with AUCTeX.
130 * Optimizations::                    When RefTeX is too slow.
131 * Problems and Work-Arounds::        First Aid.
132 * Imprint::                          Author, Web-site, Thanks
134 * Commands::                         Which are the available commands.
135 * Options::                          How to extend and configure RefTeX.
136 * Keymaps and Hooks::                For customization.
137 * Changes::                          A List of recent changes to RefTeX.
139 The Index
141 * Index::                            The full index.
143 @detailmenu
145 Introduction
147 * Installation::                     How to install and activate RefTeX.
148 * RefTeX in a Nutshell::             A brief summary and quick guide.
150 Labels and References
152 * Creating Labels::
153 * Referencing Labels::
154 * Builtin Label Environments::       The environments RefTeX knows about.
155 * Defining Label Environments::        ... and environments it doesn't.
156 * Reference Info::                   View the label corresponding to a \ref.
157 * xr (LaTeX package)::               References to external documents.
158 * varioref (LaTeX package)::         How to create \vref instead of \ref.
159 * fancyref (LaTeX package)::         How to create \fref instead of \ref.
161 Defining Label Environments
163 * Theorem and Axiom::                Defined with @code{\newenvironment}.
164 * Quick Equation::                   When a macro sets the label type.
165 * Figure Wrapper::                   When a macro argument is a label.
166 * Adding Magic Words::               Other words for other languages.
167 * Using \eqref::                     How to switch to this AMS-LaTeX macro.
168 * Non-Standard Environments::        Environments without \begin and \end
169 * Putting it Together::              How to combine many entries.
171 Citations
173 * Creating Citations::               How to create them.
174 * Citation Styles::                  Natbib, Harvard, Chicago and Co.
175 * Citation Info::                    View the corresponding database entry.
176 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
177 * Citations Outside LaTeX::          How to make citations in Emails etc.
179 Index Support
181 * Creating Index Entries::           Macros and completion of entries.
182 * The Index Phrases File::           A special file for global indexing.
183 * Displaying and Editing the Index:: The index editor.
184 * Builtin Index Macros::             The index macros RefTeX knows about.
185 * Defining Index Macros::                ... and macros it  doesn't.
187 The Index Phrases File
189 * Collecting Phrases::               Collecting from document or external.
190 * Consistency Checks::               Check for duplicates etc.
191 * Global Indexing::                  The interactive indexing process.
193 AUCTeX
195 * AUCTeX-RefTeX Interface::          How both packages work together
196 * Style Files::                      AUCTeX's style files can support RefTeX
197 * Bib-Cite::                         Hypertext reading of a document
199 Options, Keymaps, Hooks
201 * Options (Table of Contents)::
202 * Options (Defining Label Environments)::
203 * Options (Creating Labels)::
204 * Options (Referencing Labels)::
205 * Options (Creating Citations)::
206 * Options (Index Support)::
207 * Options (Viewing Cross-References)::
208 * Options (Finding Files)::
209 * Options (Optimizations)::
210 * Options (Fontification)::
211 * Options (Misc)::
213 @end detailmenu
214 @end menu
216 @end ifnottex
218 @node Introduction, Table of Contents, , Top
219 @chapter Introduction
220 @cindex Introduction
222 @b{Ref@TeX{}} is a specialized package for support of labels,
223 references, citations, and the index in LaTeX.  @b{Ref@TeX{}} wraps
224 itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
225 and @code{\index}.  Using these macros usually requires looking up
226 different parts of the document and searching through BibTeX database
227 files.  @b{Ref@TeX{}} automates these time--consuming tasks almost
228 entirely.  It also provides functions to display the structure of a
229 document and to move around in this structure quickly.@refill
231 @iftex
232 Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
233 in great depth.  All you need to know to use @b{Ref@TeX{}} can be
234 summarized on two pages (@pxref{RefTeX in a Nutshell}).  You can go
235 back later to other parts of this document when needed.
236 @end iftex
238 @xref{Imprint}, for information about who to contact for help, bug
239 reports or suggestions.
241 @menu
242 * Installation::                     How to install and activate RefTeX.
243 * RefTeX in a Nutshell::             A brief summary and quick guide.
244 @end menu
246 @node Installation, RefTeX in a Nutshell, , Introduction
247 @section Installation
248 @cindex Installation
250 @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2.
251 It was also bundled and pre--installed with XEmacs 19.16--20.x.  XEmacs
252 21.x users want to install the corresponding plug-in package which is
253 available from the
254 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}.  See
255 the XEmacs 21.x documentation on package installation for
256 details.@refill
258 Users of earlier Emacs distributions (including Emacs 19) can get a copy
259 of the @b{Ref@TeX{}} distribution from the maintainers web-page.
260 @xref{Imprint}, for more information.@refill
262 @section Environment
263 @cindex Finding files
264 @cindex BibTeX database files, not found
265 @cindex TeX files, not found
266 @cindex @code{TEXINPUTS}, environment variable
267 @cindex @code{BIBINPUTS}, environment variable
269 @b{Ref@TeX{}} needs to access all files which are part of a multifile
270 document, and the BibTeX database files requested by the
271 @code{\bibliography} command.  To find these files, @b{Ref@TeX{}} will
272 require a search path, i.e. a list of directories to check.  Normally
273 this list is stored in the environment variables @code{TEXINPUTS} and
274 @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}.  However, on some
275 systems these variables do not contain the full search path.  If
276 @b{Ref@TeX{}} does not work for you because it cannot find some files,
277 read @ref{Finding Files}.
279 @section Entering @b{Ref@TeX{}} Mode
281 @findex turn-on-reftex
282 @findex reftex-mode
283 @vindex LaTeX-mode-hook
284 @vindex latex-mode-hook
285 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
286 @kbd{M-x reftex-mode}.  To turn on @b{Ref@TeX{}} Mode for all LaTeX
287 files, add the following lines to your @file{.emacs} file:@refill
289 @example
290 (add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
291 (add-hook 'latex-mode-hook 'turn-on-reftex)   ; with Emacs latex mode
292 @end example
294 @page
295 @node RefTeX in a Nutshell, , Installation, Introduction
296 @section @b{Ref@TeX{}} in a Nutshell
297 @cindex Quick-Start
298 @cindex Getting Started
299 @cindex RefTeX in a Nutshell
300 @cindex Nutshell, RefTeX in a
302 @enumerate
303 @item
304 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
305 a table of contents of the document.  This buffer can display sections,
306 labels and index entries defined in the document.  From the buffer, you
307 can jump quickly to every part of your document.  Press @kbd{?} to get
308 help.@refill
310 @item
311 @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
312 and to find the correct key for references quickly.  It distinguishes
313 labels for different environments, knows about all standard
314 environments (and many others), and can be configured to recognize any
315 additional labeled environments you have defined yourself (variable
316 @code{reftex-label-alist}).@refill
318 @itemize @bullet
319 @item
320 @b{Creating Labels}@* 
321 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
322 @b{Ref@TeX{}} will either
323 @itemize @minus
324 @item
325 derive a label from context (default for section labels)
326 @item
327 prompt for a label string (default for figures and tables) or
328 @item 
329 insert a simple label made of a prefix and a number (all other
330 environments)@refill
331 @end itemize
332 @noindent
333 Which labels are created how is configurable with the variable
334 @code{reftex-insert-label-flags}.@refill
336 @item
337 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
338 (@code{reftex-reference}).  This shows an outline of the document with
339 all labels of a certain type (figure, equation,...) and some label
340 context.  Selecting a label inserts a @code{\ref@{@var{label}@}} macro
341 into the original buffer.@refill
342 @end itemize
344 @item
345 @b{Citations}@*
346 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
347 regular expression to search in current BibTeX database files (as
348 specified in the @code{\bibliography} command) and pull out a list of
349 matches for you to choose from.  The list is @emph{formatted} and
350 sorted.  The selected article is referenced as @samp{\cite@{@var{key}@}}
351 (see the variable @code{reftex-cite-format} if you want to insert
352 different macros).@refill
354 @item
355 @b{Index Support}@*
356 @b{Ref@TeX{}} helps to enter index entries.  It also compiles all
357 entries into an alphabetically sorted @file{*Index*} buffer which you
358 can use to check and edit the entries.  @b{Ref@TeX{}} knows about the
359 standard index macros and can be configured to recognize any additional
360 macros you have defined (@code{reftex-index-macros}).  Multiple indices
361 are supported.@refill
363 @itemize @bullet
364 @item
365 @b{Creating Index Entries}@*
366 To index the current selection or the word at point, type @kbd{C-c /}
367 (@code{reftex-index-selection-or-word}).  The default macro
368 @code{reftex-index-default-macro} will be used.  For a more complex entry
369 type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
370 and enter the arguments with completion.@refill
372 @item
373 @b{The Index Phrases File (Delayed Indexing)}@*
374 Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
375 the current word or selection to a special @emph{index phrase file}.
376 @b{Ref@TeX{}} can later search the document for occurrences of these
377 phrases and let you interactively index the matches.@refill
379 @item
380 @b{Displaying and Editing the Index}@*
381 To display the compiled index in a special buffer, type @kbd{C-c >}
382 (@code{reftex-display-index}).  From that buffer you can check and edit
383 all entries.@refill
384 @end itemize
386 @page
387 @item @b{Viewing Cross-References}@*
388 When point is on the @var{key} argument of a cross--referencing macro
389 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
390 @code{\index}, and variations) or inside a BibTeX database entry, you
391 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
392 corresponding locations in the document and associated BibTeX database
393 files.@refill @*
394 When the enclosing macro is @code{\cite} or @code{\ref} and no other
395 message occupies the echo area, information about the citation or label
396 will automatically be displayed in the echo area.@refill
398 @item
399 @b{Multifile Documents}@*
400 Multifile Documents are fully supported.  The included files must have a
401 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
402 master file.  @b{Ref@TeX{}} provides cross-referencing information from
403 all parts of the document, and across document borders
404 (@file{xr.sty}).@refill
406 @item
407 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
408 order to find labels and other information.  It does it automatically
409 once and updates its list internally when @code{reftex-label} and
410 @code{reftex-index} are used.  To enforce reparsing, call any of the
411 commands described above with a raw @kbd{C-u} prefix, or press the
412 @kbd{r} key in the label selection buffer, the table of contents
413 buffer, or the index buffer.@refill
415 @item
416 @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
417 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}).  AUCTeX
418 contains style files which trigger appropriate settings in
419 @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
420 additional customizations will be necessary.@refill
422 @item
423 @b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,
424 try these:@refill
425 @lisp
426 (setq reftex-enable-partial-scans t)
427 (setq reftex-save-parse-info t)
428 (setq reftex-use-multiple-selection-buffers t)
429 @end lisp
431 To integrate with AUCTeX, use
432 @lisp
433 (setq reftex-plug-into-AUCTeX t)
434 @end lisp
436 To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
437 customize the variables@refill
438 @example
439 @code{reftex-label-alist}          @r{(for label macros/environments)}
440 @code{reftex-section-levels}       @r{(for sectioning commands)}
441 @code{reftex-cite-format}          @r{(for @code{\cite}-like macros)}
442 @code{reftex-index-macros}         @r{(for @code{\index}-like macros)}
443 @code{reftex-index-default-macro}  @r{(to set the default macro)}
444 @end example
445 If you have a large number of macros defined, you may want to write
446 an AUCTeX style file to support them with both AUCTeX and
447 @b{Ref@TeX{}}.@refill
449 @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}.  Use its menus
450 until you have picked up the key bindings.  For an overview of what you
451 can do in each of the different special buffers, press @kbd{?}.  Read
452 the manual if you get stuck, of if you are curious what else might be
453 available.  The first part of the manual explains in
454 a tutorial way how to use and customize @b{Ref@TeX{}}.  The second
455 part is a command and variable reference.@refill  
456 @end enumerate
458 @node Table of Contents, Labels and References, Introduction, Top
459 @chapter Table of Contents
460 @cindex @file{*toc*} buffer
461 @cindex Table of contents buffer
462 @findex reftex-toc
463 @kindex C-c =
465 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
466 contents of the document.  By default, this @file{*toc*} buffer shows
467 only the sections of a document.  Using the @kbd{l} and @kbd{i} keys you
468 can display all labels and index entries defined in the document as
469 well.@refill
471 With the cursor in any of the lines denoting a location in the
472 document, simple key strokes will display the corresponding part in
473 another window, jump to that location, or perform other actions.@refill
475 @kindex ?
476 Here is a list of special commands in the @file{*toc*} buffer.  A
477 summary of this information is always available by pressing
478 @kbd{?}.@refill
480 @table @kbd
482 @tablesubheading{General}
483 @item ?
484 Display a summary of commands.
486 @item 0-9, -
487 Prefix argument.
489 @tablesubheading{Moving around}
490 @item n
491 Goto next entry in the table of context.
493 @item p
494 Goto previous entry in the table of context.
496 @item C-c C-n
497 Goto next section heading.  Useful when many labels and index entries
498 separate section headings.@refill
500 @item C-c C-p
501 Goto previous section heading.
503 @tablesubheading{Access to document locations}
504 @item @key{SPC}
505 Show the corresponding location in another window.  This command does
506 @emph{not} select that other window.@refill
508 @item @key{TAB}
509 Goto the location in another window.
511 @item @key{RET}
512 Go to the location and hide the @file{*toc*} buffer.  This will restore
513 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
514 called.@refill
516 @item mouse-2
517 @vindex reftex-highlight-selection
518 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
519 See also variable @code{reftex-highlight-selection}, @ref{Options
520 (Fontification)}.@refill
522 @item f
523 @vindex reftex-toc-follow-mode
524 @vindex reftex-revisit-to-follow
525 Toggle follow mode.  When follow mode is active, the other window will
526 always show the location corresponding to the line at point in the
527 @file{*toc*} buffer.  This is similar to pressing @key{SPC} after each
528 cursor motion.  The default for this flag can be set with the variable
529 @code{reftex-toc-follow-mode}.  Note that only context in files already
530 visited is shown.  @b{Ref@TeX{}} will not visit a file just for follow
531 mode.  See, however, the variable
532 @code{reftex-revisit-to-follow}.@refill
534 @item .
535 Show calling point in another window.  This is the point from where
536 @code{reftex-toc} was last called.
538 @tablesubheading{Exiting}
539 @item q
540 Hide the @file{*toc*} buffer, return to the position where
541 @code{reftex-toc} was last called.@refill
543 @item k
544 Kill the @file{*toc*} buffer, return to the position where
545 @code{reftex-toc} was last called.@refill
547 @item C-c >
548 Switch to the @file{*Index*} buffer of this document.  With prefix
549 @samp{2}, restrict the index to the section at point in the @file{*toc*} 
550 buffer.
552 @tablesubheading{Controlling what gets displayed}
554 @item t
555 @vindex reftex-toc-max-level
556 Change the maximum level of toc entries displayed in the @file{*toc*}
557 buffer.  Without prefix arg, all levels will be included.  With prefix
558 arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
559 @var{arg} (3 in this case).  Chapters are level 1, sections are level 2.
560 The mode line @samp{T<>} indicator shows the current value.  The default
561 depth can be configured with the variable
562 @code{reftex-toc-max-level}.@refill
564 @item F
565 @vindex reftex-toc-include-file-boundaries
566 Toggle the display of the file borders of a multifile document in the
567 @file{*toc*} buffer.  The default for this flag can be set with the
568 variable @code{reftex-toc-include-file-boundaries}.@refill
570 @item l
571 @vindex reftex-toc-include-labels
572 Toggle the display of labels in the @file{*toc*} buffer.  The default
573 for this flag can be set with the variable
574 @code{reftex-toc-include-labels}.  When called with a prefix argument,
575 @b{Ref@TeX{}} will prompt for a label type and include only labels of
576 the selected type in the @file{*toc*} buffer.  The mode line @samp{L<>}
577 indicator shows which labels are included.@refill
579 @item i
580 @vindex reftex-toc-include-index-entries
581 Toggle the display of index entries in the @file{*toc*} buffer.  The
582 default for this flag can be set with the variable
583 @code{reftex-toc-include-index-entries}.  When called with a prefix
584 argument, @b{Ref@TeX{}} will prompt for a specific index and include
585 only entries in the selected index in the @file{*toc*} buffer.  The mode 
586 line @samp{I<>} indicator shows which index is used.@refill
588 @item c
589 @vindex reftex-toc-include-context
590 Toggle the display of label and index context in the @file{*toc*}
591 buffer.  The default for this flag can be set with the variable
592 @code{reftex-toc-include-context}.@refill
594 @tablesubheading{Updating the buffer}
596 @item g
597 Rebuild the @file{*toc*} buffer.  This does @emph{not} rescan the
598 document.@refill
600 @item r
601 @vindex reftex-enable-partial-scans
602 Reparse the LaTeX document and rebuild the @file{*toc*} buffer.  When
603 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
604 location is defined in, not the entire document.@refill
606 @item C-u r
607 Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
608 buffer.@refill
610 @item x
611 Switch to the @file{*toc*} buffer of an external document.  When the
612 current document is using the @code{xr} package (@pxref{xr (LaTeX
613 package)}), @b{Ref@TeX{}} will switch to one of the external
614 documents.@refill
616 @end table
618 @vindex reftex-toc-map
619 In order to define additional commands for the @file{*toc*} buffer, the
620 keymap @code{reftex-toc-map} may be used.@refill
622 @cindex Sectioning commands
623 @cindex KOMA-Script, LaTeX classes
624 @cindex LaTeX classes, KOMA-Script
625 @cindex TOC entries for environments
626 @vindex reftex-section-levels
627 The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
628 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
629 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
630 Additional macros can be configured with the variable
631 @code{reftex-section-levels}.  It is also possible to add certain LaTeX
632 environments to the table of contents.  This is probably only useful for
633 theorem-like environments. @xref{Defining Label Environments}, for an
634 example.
636 @node Labels and References, Citations, Table of Contents, Top
637 @chapter Labels and References
638 @cindex Labels in LaTeX
639 @cindex References in LaTeX
640 @cindex Label category
641 @cindex Label environment
642 @cindex @code{\label}
644 LaTeX provides a powerful mechanism to deal with cross--references in a
645 document.  When writing a document, any part of it can be marked with a
646 label, like @samp{\label@{mark@}}.  LaTeX records the current value of a
647 certain counter when a label is defined.  Later references to this label
648 (like @samp{\ref@{mark@}}) will produce the recorded value of the
649 counter.@refill
651 Labels can be used to mark sections, figures, tables, equations,
652 footnotes, items in enumerate lists etc.  LaTeX is context sensitive in
653 doing this: A label defined in a figure environment automatically
654 records the figure counter, not the section counter.@refill
656 Several different environments can share a common counter and therefore
657 a common label category.  E.g.  labels in both @code{equation} and
658 @code{eqnarray} environments record the value of the same counter - the
659 equation counter.@refill
661 @menu
662 * Creating Labels::
663 * Referencing Labels::
664 * Builtin Label Environments::       The environments RefTeX knows about.
665 * Defining Label Environments::        ... and environments it doesn't.
666 * Reference Info::                   View the label corresponding to a \ref.
667 * xr (LaTeX package)::               References to external documents.
668 * varioref (LaTeX package)::         How to create \vref instead of \ref.
669 * fancyref (LaTeX package)::         How to create \fref instead of \ref.
670 @end menu
672 @node Creating Labels, Referencing Labels, , Labels and References
673 @section Creating Labels
674 @cindex Creating labels
675 @cindex Labels, creating
676 @cindex Labels, deriving from context
677 @kindex C-c (
678 @findex reftex-label
680 In order to create a label in a LaTeX document, press @kbd{C-c (}
681 (@code{reftex-label}).  Just like LaTeX, @b{Ref@TeX{}} is context sensitive
682 and will figure out the environment it currently is in and adapt the
683 label to that environment.  A label usually consists of a short prefix
684 indicating the type of the label and a unique mark.  @b{Ref@TeX{}} has
685 3 different modes to create this mark.@refill
687 @enumerate
688 @item
689 @vindex reftex-translate-to-ascii-function
690 @vindex reftex-derive-label-parameters
691 @vindex reftex-label-illegal-re
692 @vindex reftex-abbrev-parameters
693 A label can be derived from context.  This means, @b{Ref@TeX{}} takes
694 the context of the label definition and constructs a label from
695 that@footnote{Note that the context may contain constructs which are
696 illegal in labels.  @b{Ref@TeX{}} will therefore strip the accent from
697 accented Latin-1 characters and remove everything else which is not
698 legal in labels.  This mechanism is safe, but may not be satisfactory
699 for non-western languages.  Check the following variables if you need to
700 change things: @code{reftex-translate-to-ascii-function},
701 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
702 @code{reftex-abbrev-parameters}.}.  This works best for section labels,
703 where the section heading is used to construct a label.  In fact,
704 @b{Ref@TeX{}}'s default settings use this method only for section
705 labels.  You will be asked to confirm the derived label, or edit
706 it.@refill
708 @item
709 We may also use a simple unique number to identify a label.  This is
710 mostly useful for labels where it is difficult to come up with a very
711 good descriptive name.  @b{Ref@TeX{}}'s default settings use this method
712 for equations, enumerate items and footnotes.  The author of @b{Ref@TeX{}}
713 tends to write documents with many equations and finds it impossible
714 to come up with good names for each of them.  These simple labels are
715 inserted without query, and are therefore very fast.  Good descriptive
716 names are not really necessary as @b{Ref@TeX{}} will provide context to
717 reference a label (@pxref{Referencing Labels}).@refill
719 @item
720 The third method is to ask the user for a label.  This is most
721 useful for things which are easy to describe briefly and do not turn up
722 too frequently in a document.  @b{Ref@TeX{}} uses this for figures and
723 tables.  Of course, one can enter the label directly by typing the full
724 @samp{\label@{mark@}}.  The advantage of using @code{reftex-label}
725 anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
726 It will then not be necessary to rescan the document in order to access
727 this label later.@refill
728 @end enumerate
730 @vindex reftex-insert-label-flags
731 If you want to change the way certain labels are created, check out the
732 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
733 Labels)}).@refill
735 If you are using AUCTeX to write your LaTeX documents, you can
736 set it up to delegate the creation of labels to
737 @b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
739 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
740 @section Referencing Labels
741 @cindex Referencing labels
742 @cindex Labels, referencing
743 @cindex Selection buffer, labels
744 @cindex Selection process
745 @cindex @code{\ref}
746 @kindex C-c )
747 @findex reftex-reference
749 Referencing Labels is really at the heart of @b{Ref@TeX{}}.  Press @kbd{C-c
750 )} in order to reference a label (reftex-reference).  This will start a
751 selection process and finally insert the complete @samp{\ref@{label@}}
752 into the buffer.@refill
754 First, @b{Ref@TeX{}} will determine the label category which is required.
755 Often that can be figured out from context.  For example, if you
756 write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
757 that an equation label is going to be referenced.  If it cannot figure
758 out what label category is needed, it will query for one.@refill
760 You will then be presented with a label selection menu.  This is a
761 special buffer which contains an outline of the document along with all
762 labels of the given label category.  In addition, next to the label
763 there will be one line of context of the label definition, which is some
764 text in the buffer near the label definition.  Usually this is
765 sufficient to identify the label.  If you are unsure about a certain
766 label, pressing @key{SPC} will show the label definition point in
767 another window.@refill
769 In order to reference a label, move to cursor to the correct label and
770 press @key{RET}.  You can also reference several labels with a single
771 call to @code{reftex-reference} by marking entries with the @kbd{m}
772 key (see below).
774 @kindex ?
775 Here is a list of special commands in the selection buffer.  A summary
776 of this information is always available from the selection process by
777 pressing @kbd{?}.@refill
781 @table @kbd
782 @tablesubheading{General}
783 @item ?
784 Show a summary of available commands.
786 @item 0-9,-
787 Prefix argument.
789 @tablesubheading{Moving around}
790 @item n
791 Go to next label.
793 @item p
794 Go to previous label.
796 @item b
797 Jump back to the position where you last left the selection buffer.
798 Normally this should get you back to the last referenced label.@refill
800 @item C-c C-n
801 Goto next section heading.
803 @item C-c C-p
804 Goto previous section heading.
806 @tablesubheading{Displaying Context}
807 @item @key{SPC}
808 Show the surroundings of the definition of the current label in another
809 window.  See also the @kbd{f} key.@refill
811 @item f
812 @vindex reftex-revisit-to-follow
813 Toggle follow mode.  When follow mode is active, the other window will
814 always display the full context of the current label.  This is similar
815 to pressing @key{SPC} after each cursor motion.  Note that only context
816 in files already visited is shown.  @b{RefTeX} will not visit a file
817 just for follow mode.  See, however, the variable
818 @code{reftex-revisit-to-follow}.@refill
820 @item .
821 Show insertion point in another window.  This is the point from where you
822 called @code{reftex-reference}.@refill
824 @tablesubheading{Selecting a label and creating the reference}
825 @item @key{RET}
826 Insert a reference to the label at point into the buffer from which the
827 selection process was started.  When entries have been marked, @key{RET}
828 references all marked labels.@refill
830 @item mouse-2
831 @vindex reftex-highlight-selection
832 Clicking with mouse button 2 on a label will accept it like @key{RET}
833 would. See also variable @code{reftex-highlight-selection}, @ref{Options
834 (Misc)}.@refill
836 @vindex reftex-multiref-punctuation
837 @item m - + ,
838 Mark the current entry.  When several entries have been marked, pressing
839 @kbd{RET} will accept all of them and place them into several
840 @code{\ref} macros.  The special markers @samp{,-+} also store a
841 separator to be inserted before the corresponding reference.  So marking
842 six entries with the keys @samp{m , , - , +} will give a reference list
843 like this (see the variable @code{reftex-multiref-punctuation})
844 @example
845 In eqs. (1), (2), (3)--(4), (5) and (6)
846 @end example
848 @item u
849 Unmark a marked entry.
851 @c FIXME: Do we need `A' as well for consistency?
852 @cindex LaTeX packages, @code{saferef}
853 @cindex @code{saferef}, LaTeX package
854 @item a
855 Accept the marked entries and put all labels as a comma-separated list
856 into one @emph{single} @code{\ref} macro.  Some packages like
857 @file{saferef.sty} support multiple references in this way.@refill
859 @item l
860 Use the last referenced label(s) again.  This is equivalent to moving to
861 that label and pressing @key{RET}.@refill
863 @item @key{TAB}
864 Enter a label with completion.  This may also be a label which does not
865 yet exist in the document.
867 @item v
868 @cindex @code{varioref}, LaTeX package
869 @cindex @code{\vref}
870 @cindex LaTeX packages, @code{varioref}
871 Toggle between @code{\ref} and @code{\vref} macro for references.  The
872 @code{\vref} macro is defined in the @code{varioref} LaTeX package.
873 With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
874 macro.  The current state of this flag is displayed by the @samp{S<>}
875 indicator in the mode line of the selection buffer.@refill
877 @item V
878 @cindex @code{fancyref}, LaTeX package
879 @cindex @code{\fref}
880 @cindex @code{\Fref}
881 @cindex LaTeX packages, @code{fancyref}
882 Cycle between @code{\ref}, @code{\fref} and @code{\Fref}.  The
883 @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
884 LaTeX package.  With this key you can force @b{Ref@TeX{}} to insert a
885 @code{\fref} or @code{\Fref} macro.  The current state of this flag is
886 displayed by the @samp{S<>} indicator in the mode line of the
887 selection buffer.
889 @tablesubheading{Exiting}
891 @item q
892 Exit the selection process without inserting any reference into the
893 buffer.@refill
895 @tablesubheading{Controlling what gets displayed}
896 @vindex reftex-label-menu-flags
897 The defaults for the following flags can be configured with the variable 
898 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
900 @item c
901 Toggle the display of the one-line label definition context in the
902 selection buffer.@refill
904 @item F
905 Toggle the display of the file borders of a multifile document in the
906 selection buffer.@refill
908 @item t
909 Toggle the display of the table of contents in the selection buffer.
910 With prefix @var{arg}, change the maximum level of toc entries displayed 
911 to @var{arg}.  Chapters are level 1, section are level 2.@refill
913 @item #
914 Toggle the display of a label counter in the selection buffer.@refill
916 @item %
917 Toggle the display of labels hidden in comments in the selection
918 buffers.  Sometimes, you may have commented out parts of your document.
919 If these parts contain label definitions, @b{Ref@TeX{}} can still display
920 and reference these labels.@refill
922 @tablesubheading{Updating the buffer}
923 @item g
924 Update the menu.  This will rebuilt the menu from the internal label
925 list, but not reparse the document (see @kbd{r}).@refill
927 @item r
928 @vindex reftex-enable-partial-scans
929 Reparse the document to update the information on all labels and rebuild
930 the menu.  If the variable @code{reftex-enable-partial-scans} is
931 non-@code{nil} and your document is a multifile document, this will
932 reparse only a part of the document (the file in which the label at
933 point was defined).@refill
935 @item C-u r
936 Reparse the @emph{entire} document.
938 @item s
939 Switch the label category.  After prompting for another label category,
940 a menu for that category will be shown.@refill
942 @item x
943 Reference a label from an external document.  With the LaTeX package
944 @code{xr} it is possible to reference labels defined in another
945 document.  This key will switch to the label menu of an external
946 document and let you select a label from there (@pxref{xr (LaTeX
947 package),,xr}).@refill
949 @end table
951 @vindex reftex-select-label-map
952 In order to define additional commands for the selection process, the
953 keymap @code{reftex-select-label-map} may be used.@refill
955 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
956 @section Builtin Label Environments
957 @cindex Builtin label environments
958 @cindex Label environments, builtin
959 @cindex Environments, builtin
960 @vindex reftex-label-alist
961 @vindex reftex-label-alist-builtin
963 @b{Ref@TeX{}} needs to be aware of the environments which can be referenced
964 with a label (i.e. which carry their own counters).  By default, @b{Ref@TeX{}}
965 recognizes all labeled environments and macros discussed in @cite{The
966 LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
967 1994.}.  These are:@refill
969 @itemize @minus
970 @item
971 @cindex @code{figure}, LaTeX environment
972 @cindex @code{figure*}, LaTeX environment
973 @cindex @code{table}, LaTeX environment
974 @cindex @code{table*}, LaTeX environment
975 @cindex @code{equation}, LaTeX environment
976 @cindex @code{eqnarray}, LaTeX environment
977 @cindex @code{enumerate}, LaTeX environment
978 @cindex @code{\footnote}, LaTeX macro
979 @cindex LaTeX macro @code{footnote}
980 @cindex LaTeX core
981 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
982 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
983 the LaTeX core stuff)@refill
984 @item
985 @cindex AMS-LaTeX
986 @cindex @code{amsmath}, LaTeX package
987 @cindex LaTeX packages, @code{amsmath}
988 @cindex @code{align}, AMS-LaTeX environment
989 @cindex @code{gather}, AMS-LaTeX environment
990 @cindex @code{multline}, AMS-LaTeX environment
991 @cindex @code{flalign}, AMS-LaTeX environment
992 @cindex @code{alignat}, AMS-LaTeX environment
993 @cindex @code{xalignat}, AMS-LaTeX environment
994 @cindex @code{xxalignat}, AMS-LaTeX environment
995 @cindex @code{subequations}, AMS-LaTeX environment
996 @code{align}, @code{gather}, @code{multline}, @code{flalign},
997 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
998 (from AMS-LaTeX's @file{amsmath.sty} package)@refill
999 @item
1000 @cindex @code{endnote}, LaTeX package
1001 @cindex LaTeX packages, @code{endnote}
1002 @cindex @code{\endnote}, LaTeX macro
1003 the @code{\endnote} macro (from @file{endnotes.sty})
1004 @item
1005 @cindex @code{fancybox}, LaTeX package
1006 @cindex LaTeX packages, @code{fancybox}
1007 @cindex @code{Beqnarray}, LaTeX environment
1008 @code{Beqnarray} (@file{fancybox.sty})
1009 @item
1010 @cindex @code{floatfig}, LaTeX package
1011 @cindex LaTeX packages, @code{floatfig}
1012 @cindex @code{floatingfig}, LaTeX environment
1013 @code{floatingfig} (@file{floatfig.sty})
1014 @item
1015 @cindex @code{longtable}, LaTeX package
1016 @cindex LaTeX packages, @code{longtable}
1017 @cindex @code{longtable}, LaTeX environment
1018 @code{longtable} (@file{longtable.sty})
1019 @item
1020 @cindex @code{picinpar}, LaTeX package
1021 @cindex LaTeX packages, @code{picinpar}
1022 @cindex @code{figwindow}, LaTeX environment
1023 @cindex @code{tabwindow}, LaTeX environment
1024 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1025 @item
1026 @cindex @code{sidecap}, LaTeX package
1027 @cindex LaTeX packages, @code{sidecap}
1028 @cindex @code{SCfigure}, LaTeX environment
1029 @cindex @code{SCtable}, LaTeX environment
1030 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1031 @item
1032 @cindex @code{rotating}, LaTeX package
1033 @cindex LaTeX packages, @code{rotating}
1034 @cindex @code{sidewaysfigure}, LaTeX environment
1035 @cindex @code{sidewaystable}, LaTeX environment
1036 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1037 @item
1038 @cindex @code{subfig}, LaTeX package
1039 @cindex LaTeX packages, @code{subfigure}
1040 @cindex @code{subfigure}, LaTeX environment
1041 @cindex @code{subfigure*}, LaTeX environment
1042 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1043 (@file{subfigure.sty})@refill
1044 @item
1045 @cindex @code{supertab}, LaTeX package
1046 @cindex LaTeX packages, @code{supertab}
1047 @cindex @code{supertabular}, LaTeX environment
1048 @code{supertabular} (@file{supertab.sty})
1049 @item
1050 @cindex @code{wrapfig}, LaTeX package
1051 @cindex LaTeX packages, @code{wrapfig}
1052 @cindex @code{wrapfigure}, LaTeX environment
1053 @code{wrapfigure} (@file{wrapfig.sty})
1054 @end itemize
1056 If you want to use other labeled environments, defined with
1057 @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
1058 them (@pxref{Defining Label Environments}).@refill
1060 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1061 @section Defining Label Environments
1062 @cindex Label environments, defining
1064 @vindex reftex-label-alist
1065 @b{Ref@TeX{}} can be configured to recognize additional labeled
1066 environments and macros.  This is done with the variable
1067 @code{reftex-label-alist} (@pxref{Options (Defining Label
1068 Environments)}).  If you are not familiar with Lisp, you can use the
1069 @code{custom} library to configure this rather complex variable.  To do
1070 this, use
1072 @example
1073 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1074 @end example
1076 @vindex reftex-label-alist-builtin
1077 Here we will discuss a few examples, in order to make things clearer.
1078 It can also be instructive to look at the constant
1079 @code{reftex-label-alist-builtin} which contains the entries for
1080 all the builtin environments and macros (@pxref{Builtin Label
1081 Environments}).@refill
1083 @menu
1084 * Theorem and Axiom::                Defined with @code{\newenvironment}.
1085 * Quick Equation::                   When a macro sets the label type.
1086 * Figure Wrapper::                   When a macro argument is a label.
1087 * Adding Magic Words::               Other words for other languages.
1088 * Using \eqref::                     How to switch to this AMS-LaTeX macro.
1089 * Non-Standard Environments::        Environments without \begin and \end
1090 * Putting it Together::              How to combine many entries.
1091 @end menu
1093 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1094 @subsection Theorem and Axiom Environments
1095 @cindex @code{theorem}, newtheorem
1096 @cindex @code{axiom}, newtheorem
1097 @cindex @code{\newtheorem}
1099 Suppose you are using @code{\newtheorem} in LaTeX in order to define two
1100 new environments, @code{theorem} and @code{axiom}@refill
1102 @example
1103 \newtheorem@{axiom@}@{Axiom@}
1104 \newtheorem@{theorem@}@{Theorem@}
1105 @end example
1107 @noindent
1108 to be used like this:
1110 @example
1111 \begin@{axiom@}
1112 \label@{ax:first@}
1113   ....
1114 \end@{axiom@}
1115 @end example
1117 So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
1118 labeled environments which define their own label categories.  We can
1119 either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
1120 library.  With Lisp it would look like this
1122 @lisp
1123 (setq reftex-label-alist
1124    '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
1125      ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "th.") -3)))
1126 @end lisp
1128 The type indicator characters @code{?a} and @code{?h} are used for
1129 prompts when @b{Ref@TeX{}} queries for a label type.  @code{?h}
1130 was chosen for @code{theorem} since @code{?t} is already taken by
1131 @code{table}.  Note that also @code{?s}, @code{?f}, @code{?e},
1132 @code{?i}, @code{?n} are already used for standard environments.@refill
1134 @noindent
1135 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1136 @samp{thr:}, respectively.  @xref{AUCTeX}, for information on how
1137 AUCTeX can use @b{Ref@TeX{}} to automatically create labels when a new
1138 environment is inserted into a buffer.@refill
1140 @noindent
1141 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1142 references to these labels.@refill
1144 @noindent
1145 The next item indicates how to grab context of the label definition.@refill
1146 @itemize @minus
1147 @item
1148 @code{t} means to get it from a default location (from the beginning of
1149 a @code{\macro} or after the @code{\begin} statement).  @code{t} is
1150 @emph{not} a good choice for eqnarray and similar environments.@refill
1151 @item
1152 @code{nil} means to use the text right after the label definition.@refill
1153 @item
1154 For more complex ways of getting context, see the variable
1155 @code{reftex-label-alist} (@ref{Options (Defining Label
1156 Environments)}).@refill
1157 @end itemize
1159 The following list of strings is used to guess the correct label type
1160 from the word before point when creating a reference.  E.g. if you
1161 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1162 @b{Ref@TeX{}} will know that you are looking for a theorem label and
1163 restrict the menu to only these labels without even asking.@refill
1165 The final item in each entry is the level at which the environment
1166 should produce entries in the table of context buffer.  If the number is
1167 positive, the environment will produce numbered entries (like
1168 @code{\section}), if it is negative the entries will be unnumbered (like
1169 @code{\section*}).  Use this only for environments which structure the
1170 document similar to sectioning commands.  For everything else, omit the
1171 item.@refill
1173 To do the same configuration with @code{customize}, you need to click on
1174 the @code{[INS]} button twice to create two templates and fill them in
1175 like this:@refill
1177 @example
1178 Reftex Label Alist: [Hide]
1179 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1180             Environment or \macro : [Value Menu] String: axiom
1181             Type specification    : [Value Menu] Char  : a
1182             Label prefix string   : [Value Menu] String: ax:
1183             Label reference format: [Value Menu] String: ~\ref@{%s@}
1184             Context method        : [Value Menu] After label
1185             Magic words:
1186               [INS] [DEL] String: axiom
1187               [INS] [DEL] String: ax.
1188               [INS]
1189             [X] Make TOC entry    : [Value Menu] Level: -2
1190 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1191             Environment or \macro : [Value Menu] String: theorem
1192             Type specification    : [Value Menu] Char  : h
1193             Label prefix string   : [Value Menu] String: thr:
1194             Label reference format: [Value Menu] String: ~\ref@{%s@}
1195             Context method        : [Value Menu] Default position
1196             Magic words:
1197               [INS] [DEL] String: theorem
1198               [INS] [DEL] String: theor.
1199               [INS] [DEL] String: th.
1200               [INS]
1201             [X] Make TOC entry    : [Value Menu] Level: -3
1202 @end example
1204 @vindex reftex-insert-label-flags
1205 @vindex reftex-label-menu-flags
1206 Depending on how you would like the label insertion and selection for
1207 the new environments to work, you might want to add the letters @samp{a}
1208 and @samp{h} to some of the flags in the variables
1209 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1210 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1211 Labels)}).@refill
1214 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1215 @subsection Quick Equation Macro
1216 @cindex Quick equation macro
1217 @cindex Macros as environment wrappers
1219 Suppose you would like to have a macro for quick equations.  It
1220 could be defined like this:
1222 @example
1223 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1224 @end example
1226 @noindent
1227 and used like this:
1229 @example
1230 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1231 @end example
1233 We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
1234 @code{\quickeq} is an equation label.  Here is how to do this with lisp:
1236 @lisp
1237 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1238 @end lisp
1240 The first element in this list is now the macro with empty braces as an
1241 @emph{image} of the macro arguments.  @code{?e} indicates that this is
1242 an equation label, the different @code{nil} elements indicate to use the
1243 default values for equations.  The @samp{1} as the fifth element
1244 indicates that the context of the label definition should be the 1st
1245 argument of the macro.@refill
1247 Here is again how this would look in the customization buffer:
1249 @example
1250 Reftex Label Alist: [Hide]
1251 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1252             Environment or \macro : [Value Menu] String: \quickeq@{@}
1253             Type specification    : [Value Menu] Char  : e
1254             Label prefix string   : [Value Menu] Default
1255             Label reference format: [Value Menu] Default
1256             Context method        : [Value Menu] Macro arg nr: 1
1257             Magic words:
1258               [INS]
1259             [ ] Make TOC entry    : [Value Menu] No entry
1260 @end example
1262 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1263 @subsection Figure Wrapping Macro
1264 @cindex Macros as environment wrappers
1265 @cindex Figure wrapping macro
1267 Suppose you want to make figures not directly with the figure
1268 environment, but with a macro like
1270 @example
1271 \newcommand@{\myfig@}[5][tbp]@{%
1272   \begin@{figure@}[#1]
1273     \epsimp[#5]@{#2@}
1274     \caption@{#3@}
1275     \label@{#4@}
1276   \end@{figure@}@}
1277 @end example
1279 @noindent
1280 which would be called like
1282 @example
1283 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1284 @end example
1286 Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
1287 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1288 the context.@refill
1290 @lisp
1291 (setq reftex-label-alist
1292       '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1293 @end lisp
1295 The empty pairs of brackets indicate the different arguments of the
1296 @code{\myfig} macro. The @samp{*} marks the label argument.  @code{?f}
1297 indicates that this is a figure label which will be listed together with
1298 labels from normal figure environments.  The @code{nil} entries for
1299 prefix and reference format mean to use the defaults for figure labels.
1300 The @samp{3} for the context method means to grab the 3rd macro argument
1301 - the caption.@refill
1303 As a side effect of this configuration, @code{reftex-label} will now
1304 insert the required naked label (without the @code{\label} macro) when
1305 point is directly after the opening parenthesis of a @code{\myfig} macro
1306 argument.@refill
1308 Again, here the configuration in the customization buffer:
1310 @example
1311 [INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
1312             Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1313             Type specification    : [Value Menu] Char  : f 
1314             Label prefix string   : [Value Menu] Default
1315             Label reference format: [Value Menu] Default
1316             Context method        : [Value Menu] Macro arg nr: 3
1317             Magic words:
1318               [INS]
1319             [ ] Make TOC entry    : [Value Menu] No entry
1320 @end example
1322 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1323 @subsection Adding Magic Words
1324 @cindex Magic words
1325 @cindex German magic words
1326 @cindex Label category
1328 Sometimes you don't want to define a new label environment or macro, but
1329 just change the information associated with a label category.  Maybe you
1330 want to add some magic words, for another language.  Changing only the
1331 information associated with a label category is done by giving
1332 @code{nil} for the environment name and then specify the items you want
1333 to define.  Here is an example which adds German magic words to all
1334 predefined label categories.@refill
1336 @lisp
1337 (setq reftex-label-alist
1338   '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1339     (nil ?e nil nil nil ("Gleichung" "Gl."))
1340     (nil ?t nil nil nil ("Tabelle"))
1341     (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1342     (nil ?n nil nil nil ("Anmerkung" "Anm."))
1343     (nil ?i nil nil nil ("Punkt"))))
1344 @end lisp
1346 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1347 @subsection Using @code{\eqref}
1348 @cindex @code{\eqref}, AMS-LaTeX macro
1349 @cindex AMS-LaTeX
1350 @cindex Label category
1352 Another case where one only wants to change the information associated
1353 with the label category is to change the macro which is used for
1354 referencing the label.  When working with the AMS-LaTeX stuff, you might
1355 prefer @code{\eqref} for doing equation references.  Here is how to
1356 do this:
1358 @lisp
1359 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1360 @end lisp
1362 @b{Ref@TeX{}} has also a predefined symbol for this special purpose.  The
1363 following is equivalent to the line above.@refill
1365 @lisp
1366 (setq reftex-label-alist '(AMSTeX))
1367 @end lisp
1369 Note that this is automatically done by the @file{amsmath.el} style file
1370 of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
1371 this configuration will not be necessary.@refill
1373 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1374 @subsection Non-standard Environments
1375 @cindex Non-standard environments
1376 @cindex Environments without @code{\begin}
1377 @cindex Special parser functions
1378 @cindex Parser functions, for special environments
1380 Some LaTeX packages define environment-like structures without using the
1381 standard @samp{\begin..\end} structure.  @b{Ref@TeX{}} cannot parse
1382 these directly, but you can write your own special-purpose parser and
1383 use it instead of the name of an environment in an entry for
1384 @code{reftex-label-alist}.  The function should check if point is
1385 currently in the special environment it was written to detect.  If so,
1386 it must return a buffer position indicating the start of this
1387 environment.  The return value must be @code{nil} on failure to detect
1388 the environment.  The function is called with one argument @var{bound}.
1389 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1390 which should be observed.  We will discuss two examples.@refill
1392 @cindex LaTeX commands, abbreviated
1394 Some people define abbreviations for
1395 environments, like @code{\be} for @code{\begin@{equation@}}, and
1396 @code{\ee} for @code{\end@{equation@}}.  The parser function would have
1397 to search backward for these macros.  When the first match is
1398 @code{\ee}, point is not in this environment.  When the first match is
1399 @code{\be}, point is in this environment and the function must return
1400 the beginning of the match.  To avoid scanning too far, we can also look
1401 for empty lines which cannot occure inside an equation environment.
1402 Here is the setup:@refill
1404 @lisp
1405 ;; Setup entry in reftex-label-alist, using all defaults for equations
1406 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1408 (defun detect-be-ee (bound)
1409   ;; Search backward for the macros or an empty line
1410   (if (re-search-backward 
1411        "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1412       (if (match-beginning 2)
1413           (match-beginning 2)  ; Return start of environment
1414         nil)                   ; Return nil because env is closed
1415     nil))                      ; Return nil for not found
1416 @end lisp
1418 @cindex @code{linguex}, LaTeX package
1419 @cindex LaTeX packages, @code{linguex}
1420 A more complex example is the @file{linguex.sty} package which defines
1421 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1422 terminated by @samp{\z.} or by an empty line.@refill
1424 @example
1425 \ex.  \label@{ex:12@} Some text in an exotic language ...
1426       \a. \label@{ex:13@} more stuff
1427       \b. \label@{ex:14@} still more stuff
1428           \a. List on a deeper level
1429           \b. Another item
1430           \b. and the third one
1431       \z.
1432       \b. Third item on this level.
1434 ... text after the empty line terminating all lists
1435 @end example
1437 The difficulty is that the @samp{\a.} lists can nest and that an empty
1438 line terminates all list levels in one go.  So we have to count nesting
1439 levels between @samp{\a.} and @samp{\z.}.  Here is the implementation
1440 for @b{Ref@TeX{}}.
1442 @lisp
1443 (setq reftex-label-alist
1444       '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1446 (defun detect-linguex (bound)
1447   (let ((cnt 0))
1448     (catch 'exit
1449       (while 
1450           ;; Search backward for all possible delimiters
1451           (re-search-backward
1452            (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1453                    "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1454            nil t)
1455         ;; Check which delimiter was matched.
1456         (cond 
1457          ((match-beginning 1)
1458           ;; empty line terminates all - return nil
1459           (throw 'exit nil))
1460          ((match-beginning 2)
1461           ;; \z. terminates one list level - decrease nesting count
1462           (decf cnt))
1463          ((match-beginning 3)
1464           ;; \ex. : return match unless there was a \z. on this level
1465           (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1466          ((match-beginning 4)
1467           ;; \a. : return match when on level 0, otherwise
1468           ;;       increment nesting count
1469           (if (>= cnt 0)
1470               (throw 'exit (match-beginning 4))
1471             (incf cnt))))))))
1472 @end lisp
1474 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1475 @subsection Putting it all together
1477 When you have to put several entries into @code{reftex-label-alist}, just
1478 put them after each other in a list, or create that many templates in
1479 the customization buffer.  Here is a lisp example which uses several of
1480 the entries described above:
1482 @lisp
1483 (setq reftex-label-alist
1484   '(("axiom"   ?a "ax:"  "~\\ref@{%s@}" nil ("axiom"   "ax.") -2)
1485     ("theorem" ?h "thr:" "~\\ref@{%s@}" t   ("theorem" "theor." "th.") -3)
1486     ("\\quickeq@{@}" ?e nil nil 1 nil)
1487     AMSTeX
1488     ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1489     (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1490 @end lisp
1492 @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
1493 @section Reference Info
1494 @findex reftex-view-crossref
1495 @findex reftex-mouse-view-crossref
1496 @cindex Cross-references, displaying
1497 @cindex Reference info
1498 @cindex Displaying cross-references
1499 @cindex Viewing cross-references
1500 @kindex C-c &
1501 @kindex S-mouse-2
1503 When point is idle on the argument of a @code{\ref} macro, the echo area
1504 will display some information about the label referenced there.  Note
1505 that the information is only displayed if the echo area is not occupied
1506 by a different message.  
1508 @b{Ref@TeX{}} can also display the label definition corresponding to a
1509 @code{\ref} macro, or all reference locations corresponding to a
1510 @code{\label} macro.  @xref{Viewing Cross-References}, for more
1511 information.@refill
1513 @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
1514 @section @code{xr}: Cross-Document References
1515 @cindex @code{xr}, LaTeX package
1516 @cindex LaTeX packages, @code{xr}
1517 @cindex @code{\externaldocument}
1518 @cindex External documents
1519 @cindex References to external documents
1520 @cindex Cross-document references
1522 The LaTeX package @code{xr} makes it possible to create references to
1523 labels defined in external documents.  The preamble of a document using
1524 @code{xr} will contain something like this:@refill
1526 @example
1527 \usepackage@{xr@}
1528 \externaldocument[V1-]@{volume1@}
1529 \externaldocument[V3-]@{volume3@}
1530 @end example
1532 @noindent
1533 and we can make references to any labels defined in these
1534 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1535 respectively.@refill
1537 @b{Ref@TeX{}} can be used to create such references as well.  Start the
1538 referencing process normally, by pressing @kbd{C-c )}.  Select a label
1539 type if necessary.  When you see the label selection buffer, pressing
1540 @kbd{x} will switch to the label selection buffer of one of the external
1541 documents.  You may then select a label as before and @b{Ref@TeX{}} will
1542 insert it along with the required prefix.@refill
1544 For this kind of inter-document cross-references, saving of parsing
1545 information and the use of multiple selection buffers can mean a large
1546 speed-up (@pxref{Optimizations}).@refill
1548 @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
1549 @section @code{varioref}: Variable Page References
1550 @cindex @code{varioref}, LaTeX package
1551 @cindex @code{\vref}
1552 @cindex LaTeX packages, @code{varioref}
1553 @vindex reftex-vref-is-default
1554 @code{varioref} is a frequently used LaTeX package to create
1555 cross--references with page information.  When you want to make a
1556 reference with the @code{\vref} macro, just press the @kbd{v} key in the
1557 selection buffer to toggle between @code{\ref} and @code{\vref}
1558 (@pxref{Referencing Labels}).  The mode line of the selection buffer
1559 shows the current status of this switch.  If you find that you almost
1560 always use @code{\vref}, you may want to make it the default by
1561 customizing the variable @code{reftex-vref-is-default}.  If this
1562 toggling seems too inconvenient, you can also use the command
1563 @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
1564 Or use AUCTeX to create your macros (@pxref{AUCTeX}).@refill
1566 @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
1567 @section @code{fancyref}: Fancy Cross References
1568 @cindex @code{fancyref}, LaTeX package
1569 @cindex @code{\fref}
1570 @cindex @code{\Fref}
1571 @cindex LaTeX packages, @code{fancyref}
1572 @vindex reftex-fref-is-default
1573 @code{fancyref} is a LaTeX package where a macro call like
1574 @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
1575 the referenced counter but also the complete text around it, like
1576 @samp{Figure 3 on the preceding page}.  In order to make it work you
1577 need to use label prefixes like @samp{fig:} consistently - something
1578 @b{Ref@TeX{}} does automatically.  When you want to make a reference
1579 with the @code{\fref} macro, just press the @kbd{V} key in the selection
1580 buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
1581 (@pxref{Referencing Labels}).  The mode line of the selection buffer
1582 shows the current status of this switch.  If this cycling seems
1583 inconvenient, you can also use the commands @code{reftex-fancyref-fref}
1584 and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
1585 f} and @kbd{C-c F}.}.  Or use AUCTeX to create your macros
1586 (@pxref{AUCTeX}).@refill
1588 @node Citations, Index Support, Labels and References, Top
1589 @chapter Citations
1590 @cindex Citations
1591 @cindex @code{\cite}
1593 Citations in LaTeX are done with the @code{\cite} macro or variations of
1594 it.  The argument of the macro is a citation key which identifies an
1595 article or book in either a BibTeX database file or in an explicit
1596 @code{thebibliography} environment in the document.  @b{Ref@TeX{}}'s
1597 support for citations helps to select the correct key quickly.@refill
1599 @menu
1600 * Creating Citations::               How to create them.
1601 * Citation Styles::                  Natbib, Harvard, Chicago and Co.
1602 * Citation Info::                    View the corresponding database entry.
1603 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
1604 * Citations Outside LaTeX::          How to make citations in Emails etc.
1605 @end menu
1607 @node Creating Citations, Citation Styles, , Citations
1608 @section Creating Citations
1609 @cindex Creating citations
1610 @cindex Citations, creating
1611 @findex reftex-citation
1612 @kindex C-c [
1613 @cindex Selection buffer, citations
1614 @cindex Selection process
1616 In order to create a citation, press @kbd{C-c [}.  @b{Ref@TeX{}} then
1617 prompts for a regular expression which will be used to search through
1618 the database and present the list of matches to choose from in a
1619 selection process similar to that for selecting labels
1620 (@pxref{Referencing Labels}).@refill
1622 The regular expression uses an extended syntax: @samp{&&} defines a
1623 logic @code{and} for regular expressions. For example
1624 @samp{Einstein&&Bose} will match all articles which mention
1625 Bose-Einstein condensation, or which are co-authored by Bose and
1626 Einstein.  When entering the regular expression, you can complete on
1627 known citation keys.@refill
1629 @cindex @code{\bibliography}
1630 @cindex @code{thebibliography}, LaTeX environment
1631 @cindex @code{BIBINPUTS}, environment variable
1632 @cindex @code{TEXBIB}, environment variable
1633 @b{Ref@TeX{}} prefers to use BibTeX database files specified with a
1634 @code{\bibliography} macro to collect its information.  Just like
1635 BibTeX, it will search for the specified files in the current directory
1636 and along the path given in the environment variable @code{BIBINPUTS}.
1637 If you do not use BibTeX, but the document contains an explicit
1638 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
1639 information from there.  Note that in this case the information
1640 presented in the selection buffer will just be a copy of relevant
1641 @code{\bibitem} entries, not the structured listing available with
1642 BibTeX database files.@refill
1644 @kindex ?
1645 In the selection buffer, the following keys provide special commands.  A
1646 summary of this information is always available from the selection
1647 process by pressing @kbd{?}.@refill
1649 @table @kbd
1650 @tablesubheading{General}
1651 @item ?
1652 Show a summary of available commands.
1654 @item 0-9,-
1655 Prefix argument.
1657 @tablesubheading{Moving around}
1658 @item n
1659 Go to next article.
1661 @item p
1662 Go to previous article.
1664 @tablesubheading{Access to full database entries}
1665 @item @key{SPC}
1666 Show the database entry corresponding to the article at point, in
1667 another window.  See also the @kbd{f} key.@refill
1669 @item f
1670 Toggle follow mode.  When follow mode is active, the other window will
1671 always display the full database entry of the current article.  This is
1672 equivalent to pressing @key{SPC} after each cursor motion.  With BibTeX
1673 entries, follow mode can be rather slow.@refill
1675 @tablesubheading{Selecting entries and creating the citation}
1676 @item @key{RET}
1677 Insert a citation referencing the article at point into the buffer from
1678 which the selection process was started.@refill
1680 @item mouse-2
1681 @vindex reftex-highlight-selection
1682 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1683 would.  See also variable @code{reftex-highlight-selection}, @ref{Options
1684 (Misc)}.@refill
1686 @item m
1687 Mark the current entry.  When one or several entries are marked,
1688 pressing @kbd{a} or @kbd{A} accepts all marked entries.  Also,
1689 @key{RET} behaves like the @kbd{a} key.
1691 @item u
1692 Unmark a marked entry.
1694 @item a
1695 Accept all (marked) entries in the selection buffer and create a single
1696 @code{\cite} macro referring to them.@refill
1698 @item A
1699 Accept all (marked) entries in the selection buffer and create a
1700 separate @code{\cite} macro for each of it.@refill
1702 @item @key{TAB}
1703 Enter a citation key with completion.  This may also be a key which does
1704 not yet exist.
1706 @item .
1707 Show insertion point in another window.  This is the point from where you
1708 called @code{reftex-citation}.@refill
1710 @tablesubheading{Exiting}
1711 @item q
1712 Exit the selection process without inserting a citation into the
1713 buffer.@refill
1715 @tablesubheading{Updating the buffer}
1717 @item g
1718 Start over with a new regular expression.  The full database will be
1719 rescanned with the new expression (see also @kbd{r}).@refill
1721 @c FIXME: Should we use something else here? r is usually rescan!
1722 @item r
1723 Refine the current selection with another regular expression.  This will
1724 @emph{not} rescan the entire database, but just the already selected
1725 entries.@refill
1727 @end table
1729 @vindex reftex-select-bib-map
1730 In order to define additional commands for this selection process, the
1731 keymap @code{reftex-select-bib-map} may be used.@refill
1733 @node Citation Styles, Citation Info, Creating Citations, Citations
1734 @section Citation Styles
1735 @cindex Citation styles
1736 @cindex Citation styles, @code{natbib}
1737 @cindex Citation styles, @code{harvard}
1738 @cindex Citation styles, @code{chicago}
1739 @cindex @code{natbib}, citation style
1740 @cindex @code{harvard}, citation style
1741 @cindex @code{chicago}, citation style
1743 @vindex reftex-cite-format
1744 The standard LaTeX macro @code{\cite} works well with numeric or simple
1745 key citations.  To deal with the more complex task of author-year
1746 citations as used in many natural sciences, a variety of packages has
1747 been developed which define derived forms of the @code{\cite} macro.
1748 @b{Ref@TeX{}} can be configured to produce these citation macros as well by
1749 setting the variable @code{reftex-cite-format}.  For the most commonly
1750 used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
1751 be done from the menu, under @code{Ref->Citation Styles}.  Since there
1752 are usually several macros to create the citations, executing
1753 @code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
1754 macro.  For the Natbib style, this looks like this:
1756 @example
1757 SELECT A CITATION FORMAT
1759 [^M]   \cite@{%l@}
1760 [t]    \citet@{%l@}
1761 [T]    \citet*@{%l@}
1762 [p]    \citep@{%l@}
1763 [P]    \citep*@{%l@}
1764 [e]    \citep[e.g.][]@{%l@}
1765 [s]    \citep[see][]@{%l@}
1766 [a]    \citeauthor@{%l@}
1767 [A]    \citeauthor*@{%l@}
1768 [y]    \citeyear@{%l@}
1769 @end example
1771 Following the most generic of these packages, @code{natbib}, the builtin
1772 citation packages always accept the @kbd{t} key for a @emph{textual}
1773 citation (like: @code{Jones et al. (1997) have shown...})  as well as 
1774 the @kbd{p} key for a parenthetical citation (like: @code{As shown
1775 earlier (Jones et al, 1997)}).@refill
1777 To make one of these styles the default, customize the variable
1778 @code{reftex-cite-format} or put into @file{.emacs}:
1780 @lisp
1781 (setq reftex-cite-format 'natbib)
1782 @end lisp
1784 You can also use AUCTeX style files to automatically set the
1785 citation style based on the @code{usepackage} commands in a given
1786 document.  @xref{Style Files}, for information on how to set up the style
1787 files correctly.@refill
1789 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
1790 @section Citation Info
1791 @cindex Displaying citations
1792 @cindex Citations, displaying
1793 @cindex Citation info
1794 @cindex Viewing citations
1795 @kindex C-c &
1796 @kindex S-mouse-2
1797 @findex reftex-view-crossref
1798 @findex reftex-mouse-view-crossref
1800 When point is idle on the argument of a @code{\cite} macro, the echo area
1801 will display some information about the article cited there.  Note
1802 that the information is only displayed if the echo area is not occupied
1803 by a different message.  
1805 @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
1806 entry corresponding to a @code{\cite} macro, or all citation locations
1807 corresponding to a @code{\bibitem} or BibTeX database entry.
1808 @xref{Viewing Cross-References}.@refill
1810 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
1811 @section Chapterbib and Bibunits
1812 @cindex @code{chapterbib}, LaTeX package
1813 @cindex @code{bibunits}, LaTeX package
1814 @cindex Bibliographies, multiple
1816 @code{chapterbib} and @code{bibunits} are two LaTeX packages which
1817 produce multiple bibliographies in a document.  This is no problem for
1818 @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
1819 files.  If they do not, it is best to have each document part in a
1820 separate file (as it is required for @code{chapterbib} anyway).  Then
1821 @b{Ref@TeX{}} will still scan the locally relevant databases correctly.  If
1822 you have multiple bibliographies within a @emph{single file}, this may
1823 or may not be the case.
1825 @node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations
1826 @section Citations outside LaTeX
1827 @cindex Citations outside LaTeX
1828 @vindex reftex-default-bibliography
1830 The command @code{reftex-citation} can also be executed outside a LaTeX
1831 buffer.  This can be useful to reference articles in the mail buffer and
1832 other documents.  You should @emph{not} enter @code{reftex-mode} for
1833 this, just execute the command.  The list of BibTeX files will in this
1834 case be taken from the variable @code{reftex-default-bibliography}.
1835 Setting the variable @code{reftex-cite-format} to the symbol
1836 @code{locally} does a decent job of putting all relevant information
1837 about a citation directly into the buffer.  Here is the lisp code to add
1838 the @kbd{C-c [} binding to the mail buffer.  It also provides a local
1839 binding for @code{reftex-cite-format}.@refill
1841 @lisp
1842 (add-hook 'mail-setup-hook
1843           (lambda () (define-key mail-mode-map "\C-c["
1844                        (lambda () (interactive)
1845                          (require 'reftex)
1846                          (let ((reftex-cite-format 'locally))
1847                            (reftex-citation))))))
1848 @end lisp
1850 @node Index Support, Viewing Cross-References, Citations, Top
1851 @chapter Index Support
1852 @cindex Index Support
1853 @cindex @code{\index}
1855 LaTeX has builtin support for creating an Index.  The LaTeX core
1856 supports two different indices, the standard index and a glossary.  With
1857 the help of special LaTeX packages (@file{multind.sty} or
1858 @file{index.sty}), any number of indices can be supported.
1860 Index entries are created with the @code{\index@{@var{entry}@}} macro.
1861 All entries defined in a document are written out to the @file{.aux}
1862 file.  A separate tool must be used to convert this information into a
1863 nicely formatted index.  Tools used with LaTeX include @code{MakeIndex}
1864 and @code{xindy}.@refill
1866 Indexing is a very difficult task.  It must follow strict conventions to
1867 make the index consistent and complete.  There are basically two
1868 approaches one can follow, and both have their merits.
1870 @enumerate
1871 @item
1872 Part of the indexing should already be done with the markup.  The
1873 document structure should be reflected in the index, so when starting
1874 new sections, the basic topics of the section should be indexed.  If the
1875 document contains definitions, theorems or the like, these should all
1876 correspond to appropriate index entries.  This part of the index can
1877 very well be developed along with the document.  Often it is worthwhile
1878 to define special purpose macros which define an item and at the same
1879 time make an index entry, possibly with special formatting to make the
1880 reference page in the index bold or underlined.  To make @b{Ref@TeX{}}
1881 support for indexing possible, these special macros must be added to
1882 @b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}).@refill
1884 @item
1885 The rest of the index is often just a collection of where in the
1886 document certain words or phrases are being used.  This part is
1887 difficult to develop along with the document, because consistent entries
1888 for each occurrence are needed and are best selected when the document
1889 is ready.  @b{Ref@TeX{}} supports this with an @emph{index phrases file}
1890 which collects phrases and helps indexing the phrases globally.@refill
1891 @end enumerate
1893 Before you start, you need to make sure that @b{Ref@TeX{}} knows about
1894 the index style being used in the current document.  @b{Ref@TeX{}} has
1895 builtin support for the default @code{\index} and @code{\glossary}
1896 macros.  Other LaTeX packages, like the @file{multind} or @file{index}
1897 package, redefine the @code{\index} macro to have an additional
1898 argument, and @b{Ref@TeX{}} needs to be configured for those.  A
1899 sufficiently new version of AUCTeX (9.10c or later) will do this
1900 automatically.  If you really don't use AUCTeX (you should!), this
1901 configuration needs to be done by hand with the menu (@code{Ref->Index
1902 Style}), or globally for all your documents with@refill
1904 @lisp
1905 (setq reftex-index-macros '(multind))     @r{or}
1906 (setq reftex-index-macros '(index))
1907 @end lisp
1909 @menu
1910 * Creating Index Entries::           Macros and completion of entries.
1911 * The Index Phrases File::           A special file for global indexing.
1912 * Displaying and Editing the Index:: The index editor.
1913 * Builtin Index Macros::             The index macros RefTeX knows about.
1914 * Defining Index Macros::                ... and macros it  doesn't.
1915 @end menu
1917 @node Creating Index Entries, The Index Phrases File, , Index Support
1918 @section Creating Index Entries
1919 @cindex Creating index entries
1920 @cindex Index entries, creating
1921 @kindex C-c <
1922 @findex reftex-index
1923 @kindex C-c /
1924 @findex reftex-index-selection-or-word
1926 In order to index the current selection or the word at the cursor press
1927 @kbd{C-c /} (@code{reftex-index-selection-or-word}).  This causes the
1928 selection or word @samp{@var{word}} to be replaced with
1929 @samp{\index@{@var{word}@}@var{word}}.  The macro which is used
1930 (@code{\index} by default) can be configured with the variable
1931 @code{reftex-index-default-macro}.  When the command is called with a
1932 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
1933 generated index entry.  Use this to change the case of the word or to
1934 make the entry a subentry, for example by entering
1935 @samp{main!sub!@var{word}}.  When called with two raw @kbd{C-u} prefixes
1936 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
1937 When there is nothing selected and no word at point, this command will
1938 just call @code{reftex-index}, described below.
1940 In order to create a general index entry, press @kbd{C-c <}
1941 (@code{reftex-index}).  @b{Ref@TeX{}} will prompt for one of the
1942 available index macros and for its arguments.  Completion will be
1943 available for the index entry and, if applicable, the index tag.  The
1944 index tag is a string identifying one of multiple indices.  With the
1945 @file{multind} and @file{index} packages, this tag is the first argument
1946 to the redefined @code{\index} macro.@refill
1948 @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
1949 @section The Index Phrases File
1950 @cindex Index phrase file
1951 @cindex Phrase file
1952 @kindex C-c |
1953 @findex reftex-index-visit-phrases-buffer
1954 @cindex Macro definition lines, in phrase buffer
1956 @b{Ref@TeX{}} maintains a file in which phrases can be collected for
1957 later indexing.  The file is located in the same directory as the master
1958 file of the document and has the extension @file{.rip} (@b{R}eftex
1959 @b{I}ndex @b{P}hrases).  You can create or visit the file with @kbd{C-c
1960 |} (@code{reftex-index-visit-phrases-buffer}).  If the file is empty it
1961 is initialized by inserting a file header which contains the definition
1962 of the available index macros.  This list is initialized from
1963 @code{reftex-index-macros} (@pxref{Defining Index Macros}).  You can
1964 edit the header as needed, but if you define new LaTeX indexing macros,
1965 don't forget to add them to @code{reftex-index-macros} as well.  Here is
1966 a phrase file header example:@refill
1968 @example
1969 % -*- mode: reftex-index-phrases -*-
1970 %                           Key   Macro Format       Repeat
1971 %----------------------------------------------------------
1972 >>>INDEX_MACRO_DEFINITION:   i    \index@{%s@}          t
1973 >>>INDEX_MACRO_DEFINITION:   I    \index*@{%s@}         nil
1974 >>>INDEX_MACRO_DEFINITION:   g    \glossary@{%s@}       t
1975 >>>INDEX_MACRO_DEFINITION:   n    \index*[name]@{%s@}   nil
1976 %----------------------------------------------------------
1977 @end example
1979 The macro definition lines consist of a unique letter identifying a
1980 macro, a format string and the @var{repeat} flag, all separated by
1981 @key{TAB}.  The format string shows how the macro is to be applied, the
1982 @samp{%s} will be replaced with the index entry.  The repeat flag
1983 indicates if @var{word} is indexed by the macro as
1984 @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
1985 @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}).  In the
1986 above example it is assumed that the macro @code{\index*@{@var{word}@}}
1987 already typesets its argument in the text, so that it is unnecessary to
1988 repeat @var{word} outside the macro.@refill
1990 @menu
1991 * Collecting Phrases::               Collecting from document or external.
1992 * Consistency Checks::               Check for duplicates etc.
1993 * Global Indexing::                  The interactive indexing process.
1994 @end menu
1996 @node Collecting Phrases, Consistency Checks, , The Index Phrases File
1997 @subsection Collecting Phrases
1998 @cindex Collecting index phrases
1999 @cindex Index phrases, collection
2000 @cindex Phrases, collecting
2002 Phrases for indexing can be collected while writing the document.  The
2003 command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2004 copies the current selection (if active) or the word near point into the 
2005 phrases buffer.  It then selects this buffer, so that the phrase line
2006 can be edited.  To return to the LaTeX document, press @kbd{C-c C-c}
2007 (@code{reftex-index-phrases-save-and-return}).
2009 You can also prepare the list of index phrases in a different way and
2010 copy it into the phrases file.  For example you might want to start from 
2011 a word list of the document and remove all words which should not be
2012 indexed.
2014 The phrase lines in the phrase buffer must have a specific format.
2015 @b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
2016 format.  A phrase line looks like this:
2018 @example
2019 [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...] 
2020 @end example
2022 @code{<TABs>} stands for white space containing at least one @key{TAB}.
2023 @var{key} must be at the start of the line and is the character
2024 identifying one of the macros defined in the file header.  It is
2025 optional - when omitted, the first macro definition line in the file
2026 will be used for this phrase.  The @var{phrase} is the phrase to be
2027 searched for when indexing.  It may contain several words separated by
2028 spaces.  By default the search phrase is also the text entered as
2029 argument of the index macro.  If you want the index entry to be
2030 different from the search phrase, enter another @key{TAB} and the index
2031 argument @var{arg}.  If you want to have each match produce several
2032 index entries, separate the different index arguments with @samp{ &&
2033 }@footnote{@samp{&&} with optional spaces, see
2034 @code{reftex-index-phrases-logical-and-regexp}.}.  If you want to be
2035 able to choose at each match between several different index arguments,
2036 separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2037 see @code{reftex-index-phrases-logical-or-regexp}.}.  Here is an
2038 example:@refill
2040 @example
2041 %--------------------------------------------------------------------
2042 I     Sun
2043 i     Planet         Planets
2044 i     Vega           Stars!Vega
2045       Jupiter        Planets!Jupiter
2046 i     Mars           Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2047 i     Pluto          Planets!Pluto && Kuiper Belt Objects!Pluto
2048 @end example
2051 So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2052 @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2053 @samp{Vega} will be indexed as a subitem of @samp{Stars}.  The
2054 @samp{Jupiter} line will also use the @samp{i} macro as it was the first
2055 macro definition in the file header (see above example).  At each
2056 occurrence of @samp{Mars} you will be able choose between indexing it as
2057 a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2058 Finally, every occurrence of @samp{Pluto} will be indexed as
2059 @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2060 and will therefore create two different index entries.@refill
2062 @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
2063 @subsection Consistency Checks
2064 @cindex Index phrases, consistency checks
2065 @cindex Phrases, consistency checks
2066 @cindex Consistency check for index phrases
2068 @kindex C-c C-s
2069 Before indexing the phrases in the phrases buffer, they should be
2070 checked carefully for consistency.  A first step is to sort the phrases
2071 alphabetically - this is done with the command @kbd{C-c C-s}
2072 (@code{reftex-index-sort-phrases}).  It will sort all phrases in the
2073 buffer alphabetically by search phrase.  If you want to group certain
2074 phrases and only sort within the groups, insert empty lines between the
2075 groups.  Sorting will only change the sequence of phrases within each
2076 group (see the variable @code{reftex-index-phrases-sort-in-blocks}).@refill
2078 @kindex C-c C-i
2079 A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2080 which lists information about the phrase at point, including an example
2081 of how the index entry will look like and the number of expected matches
2082 in the document.@refill
2084 @kindex C-c C-t
2085 Another important check is to find out if there are double or
2086 overlapping entries in the buffer.  For example if you are first
2087 searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2088 second phrase will not match because of the index macro inserted before
2089 @samp{Mars} earlier.  The command @kbd{C-c C-t}
2090 (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2091 the buffer which is either duplicate or a subphrase of another phrase.
2092 In order to check the whole buffer like this, start at the beginning and
2093 execute this command repeatedly.@refill
2095 @node Global Indexing, , Consistency Checks, The Index Phrases File
2096 @subsection Global Indexing
2097 @cindex Global indexing
2098 @cindex Indexing, global
2099 @cindex Indexing, from @file{phrases} buffer
2101 Once the index phrases have been collected and organized, you are set
2102 for global indexing.  I recommend to do this only on an otherwise
2103 finished document.  Global indexing starts from the phrases buffer.
2104 There are several commands which start indexing: @kbd{C-c C-x} acts on
2105 the current phrase line, @kbd{C-c C-r} on all lines in the current
2106 region and @kbd{C-c C-a} on all phrase lines in the buffer.  It is
2107 probably good to do indexing in small chunks since your concentration
2108 may not last long enough to do everything in one go.@refill
2110 @b{Ref@TeX{}} will start at the first phrase line and search the phrase
2111 globally in the whole document.  At each match it will stop, compute the
2112 replacement string and offer you the following choices@footnote{Windows
2113 users: Restrict yourself to the described keys during indexing.  Pressing 
2114 @key{Help} at the indexing prompt can apparently hang Emacs.}:@refill
2116 @table @kbd
2117 @item y
2118 Replace this match with the proposed string.
2119 @item n
2120 Skip this match.
2121 @item !
2122 Replace this and all further matches in this file.
2123 @item q
2124 Skip this match, start with next file.
2125 @item Q
2126 Skip this match, start with next phrase.
2127 @item o
2128 Select a different indexing macro for this match.
2129 @item 1-9
2130 Select one of multiple index keys (those separated with @samp{||}).
2131 @item e
2132 Edit the replacement text.
2133 @item C-r
2134 Recursive edit.  Use @kbd{M-C-c} to return to the indexing process.
2135 @item s
2136 Save this buffer and ask again about the current match.
2137 @item S
2138 Save all document buffers and ask again about the current match.
2139 @item C-g
2140 Abort the indexing process.
2141 @end table
2143 The @samp{Find and Index in Document} menu in the phrases buffer also
2144 lists a few options for the indexing process.  The options have
2145 associated customization variables to set the defaults (@pxref{Options
2146 (Index Support)}).  Here is a short explanation of what the options do:
2148 @table @i
2149 @item Match Whole Words
2150 When searching for index phrases, make sure whole words are matched.
2151 This should probably always be on.
2152 @item Case Sensitive Search
2153 Search case sensitively for phrases.  I recommend to have this setting
2154 off, in order to match the capitalized words at the beginning of a
2155 sentence, and even typos.  You can always say @emph{no} at a match you
2156 do not like.
2157 @item Wrap Long Lines
2158 Inserting index macros increases the line length.  Turn this option on
2159 to allow @b{Ref@TeX{}} to wrap long lines.
2160 @item Skip Indexed Matches
2161 When this is on, @b{Ref@TeX{}} will at each match try to figure out if
2162 this match is already indexed.  A match is considered indexed if it is
2163 either the argument of an index macro, or if an index macro is directly
2164 (without whitespace separation) before or after the match.  Index macros
2165 are those configured in @code{reftex-index-macros}.  Intended for
2166 re-indexing a documents after changes have been made.@refill
2167 @end table
2169 Even though indexing should be the last thing you do to a document, you
2170 are bound to make changes afterwards.  Indexing then has to be applied
2171 to the changed regions.  The command
2172 @code{reftex-index-phrases-apply-to-region} is designed for this
2173 purpose.  When called from a LaTeX document with active region, it will
2174 apply @code{reftex-index-all-phrases} to the current region.@refill
2176 @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
2177 @section Displaying and Editing the Index
2178 @cindex Displaying the Index
2179 @cindex Editing the Index
2180 @cindex Index entries, creating
2181 @cindex Index, displaying
2182 @cindex Index, editing
2183 @kindex C-c >
2184 @findex reftex-display-index
2186 In order to compile and display the index, press @kbd{C-c >}.  If the
2187 document uses multiple indices, @b{Ref@TeX{}} will ask you to select
2188 one.  Then, all index entries will be sorted alphabetically and
2189 displayed in a special buffer, the @file{*Index*} buffer.  From that
2190 buffer you can check and edit each entry.@refill
2192 The index can be restricted to the current section or the region.  Then
2193 only entries in that part of the document will go into the compiled
2194 index.  To restrict to the current section, use a numeric prefix
2195 @samp{2}, thus press @kbd{C-u 2 C-c >}.  To restrict to the current
2196 region, make the region active and use a numeric prefix @samp{3} (press
2197 @kbd{C-u 3 C-c >}).  From within the @file{*Index*} buffer the
2198 restriction can be moved from one section to the next by pressing the
2199 @kbd{<} and @kbd{>} keys.@refill
2201 One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
2202 by searching near the buffer position where it had found to macro during
2203 scanning.  If you have several identical index entries in the same
2204 buffer and significant changes have shifted the entries around, you must
2205 rescan the buffer to ensure the correspondence between the
2206 @file{*Index*} buffer and the definition locations.  It is therefore
2207 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2208 frequently while editing the index from the @file{*Index*}
2209 buffer.@refill
2211 @kindex ?
2212 Here is a list of special commands available in the @file{*Index*} buffer.  A
2213 summary of this information is always available by pressing
2214 @kbd{?}.@refill
2216 @table @kbd
2217 @tablesubheading{General}
2218 @item ?
2219 Display a summary of commands.
2221 @item 0-9, -
2222 Prefix argument.
2224 @tablesubheading{Moving around}
2225 @item ! A..Z
2226 Pressing any capital letter will jump to the corresponding section in
2227 the @file{*Index*} buffer.  The exclamation mark is special and jumps to 
2228 the first entries alphabetically sorted below @samp{A}.  These are
2229 usually non-alphanumeric characters.@refill
2230 @item n
2231 Go to next entry.@refill
2232 @item p
2233 Go to previous entry.@refill
2235 @tablesubheading{Access to document locations}
2236 @item @key{SPC}
2237 Show the place in the document where this index entry is defined.@refill 
2239 @item @key{TAB}
2240 Go to the definition of the current index entry in another
2241 window.@refill
2243 @item @key{RET}
2244 Go to the definition of the current index entry and hide the
2245 @file{*Index*} buffer window.@refill
2247 @item f
2248 @vindex reftex-index-follow-mode
2249 @vindex reftex-revisit-to-follow
2250 Toggle follow mode.  When follow mode is active, the other window will
2251 always show the location corresponding to the line in the @file{*Index*}
2252 buffer at point.  This is similar to pressing @key{SPC} after each
2253 cursor motion.  The default for this flag can be set with the variable
2254 @code{reftex-index-follow-mode}.  Note that only context in files
2255 already visited is shown.  @b{Ref@TeX{}} will not visit a file just for
2256 follow mode.  See, however, the variable
2257 @code{reftex-revisit-to-follow}.@refill
2259 @tablesubheading{Entry editing}
2260 @item e
2261 Edit the current index entry.  In the minibuffer, you can edit the
2262 index macro which defines this entry.@refill
2264 @item C-k
2265 Kill the index entry.  Currently not implemented because I don't know
2266 how to implement an @code{undo} function for this.@refill
2268 @item *
2269 Edit the @var{key} part of the entry.  This is the initial part of the
2270 entry which determines the location of the entry in the index.@refill
2272 @item |
2273 Edit the @var{attribute} part of the entry.  This is the part after the
2274 vertical bar.  With @code{MakeIndex}, this part is an encapsulating
2275 macro.  With @code{xindy}, it is called @emph{attribute} and is a
2276 property of the index entry that can lead to special formatting.  When
2277 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2278 part.@refill
2280 @item @@
2281 Edit the @var{visual} part of the entry.  This is the part after the
2282 @samp{@@} which is used by @code{MakeIndex} to change the visual
2283 appearance of the entry in the index.  When called with @kbd{C-u}
2284 prefix, kill the entire @var{visual} part.@refill
2286 @item (
2287 Toggle the beginning of page range property @samp{|(} of the
2288 entry.@refill 
2290 @item )
2291 Toggle the end of page range property @samp{|)} of the entry.@refill 
2293 @item _
2294 Make the current entry a subentry.  This command will prompt for the
2295 superordinate entry and insert it.@refill
2297 @item ^
2298 Remove the highest superordinate entry.  If the current entry is a 
2299 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2300 (@samp{bbb!ccc}).@refill 
2302 @tablesubheading{Exiting}
2303 @item q
2304 Hide the @file{*Index*} buffer.@refill
2306 @item k
2307 Kill the @file{*Index*} buffer.@refill
2309 @item C-c =
2310 Switch to the Table of Contents buffer of this document.@refill
2312 @tablesubheading{Controlling what gets displayed}
2313 @item c
2314 @vindex reftex-index-include-context
2315 Toggle the display of short context in the @file{*Index*} buffer.  The
2316 default for this flag can be set with the variable
2317 @code{reftex-index-include-context}.@refill
2319 @item @}
2320 Restrict the index to a single document section.  The corresponding
2321 section number will be displayed in the @code{R<>} indicator in the
2322 mode line and in the header of the @file{*Index*} buffer.@refill
2324 @item @{
2325 Widen the index to contain all entries of the document.@refill
2327 @item <
2328 When the index is currently restricted, move the restriction to the
2329 previous section.@refill
2331 @item >
2332 When the index is currently restricted, move the restriction to the
2333 next section.@refill
2335 @tablesubheading{Updating the buffer}
2336 @item g
2337 Rebuild the @file{*Index*} buffer.  This does @emph{not} rescan the
2338 document.  However, it sorts the entries again, so that edited entries
2339 will move to the correct position.@refill
2341 @item r
2342 @vindex reftex-enable-partial-scans
2343 Reparse the LaTeX document and rebuild the @file{*Index*} buffer.  When
2344 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
2345 location is defined in, not the entire document.@refill
2347 @item C-u r
2348 Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
2349 buffer.@refill
2351 @item s
2352 Switch to a different index (for documents with multiple
2353 indices).@refill 
2354 @end table
2357 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2358 @section Builtin Index Macros
2359 @cindex Builtin index macros
2360 @cindex Index macros, builtin
2361 @vindex reftex-index-macros
2362 @cindex @code{multind}, LaTeX package
2363 @cindex @code{index}, LaTeX package
2364 @cindex LaTeX packages, @code{multind}
2365 @cindex LaTeX packages, @code{index}
2367 @b{Ref@TeX{}} by default recognizes the @code{\index} and
2368 @code{\glossary} macros which are defined in the LaTeX core.  It has
2369 also builtin support for the re-implementations of @code{\index}
2370 in the @file{multind} and @file{index} packages.  However, since
2371 the different definitions of the @code{\index} macro are incompatible,
2372 you will have to explicitly specify the index style used.
2373 @xref{Creating Index Entries}, for information on how to do that.
2375 @node Defining Index Macros, , Builtin Index Macros, Index Support
2376 @section Defining Index Macros
2377 @cindex  Defining Index Macros
2378 @cindex Index macros, defining
2379 @vindex reftex-index-macros
2381 When writing a document with an index you will probably define
2382 additional macros which make entries into the index.
2383 Let's look at an example.
2385 @example
2386 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2387 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2388 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2389 @end example
2391 The first macro @code{\ix} typesets its argument in the text and places
2392 it into the index.  The second macro @code{\nindex} typesets its
2393 argument in the text and places it into a separate index with the tag
2394 @samp{name}@footnote{We are using the syntax of the @file{index} package
2395 here.}.  The last macro also places its argument into the index, but as
2396 subitems under the main index entry @samp{Astronomical Objects}.  Here
2397 is how to make @b{Ref@TeX{}} recognize and correctly interpret these
2398 macros, first with Emacs Lisp.
2400 @lisp
2401 (setq reftex-index-macros
2402       '(("\\ix@{*@}" "idx" ?x "" nil nil)
2403         ("\\nindex@{*@}" "name" ?n "" nil nil)
2404         ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2405 @end lisp
2407 Note that the index tag is @samp{idx} for the main index, and
2408 @samp{name} for the name index.  @samp{idx} and @samp{glo} are reserved
2409 for the default index and for the glossary.
2411 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2412 quick identification of these macros when @b{Ref@TeX{}} inserts new
2413 index entries with @code{reftex-index}.  These codes need to be
2414 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2415 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2416 respectively. 
2418 The following string is empty unless your macro adds a superordinate
2419 entry to the index key - this is the case for the @code{\astobj} macro.
2421 The next entry can be a hook function to exclude certain matches, it
2422 almost always can be @code{nil}.
2424 The final element in the list indicates if the text being indexed needs
2425 to be repeated outside the macro.  For the normal index macros, this
2426 should be @code{t}.  Only if the macro typesets the entry in the text
2427 (like @code{\ix} and @code{\nindex} in the example do), this should be
2428 @code{nil}.
2430 To do the same thing with customize, you need to fill in the templates
2431 like this:
2433 @example
2434 Repeat:
2435 [INS] [DEL] List:
2436             Macro with args: \ix@{*@}
2437             Index Tag      : [Value Menu] String: idx
2438             Access Key     : x
2439             Key Prefix     : 
2440             Exclusion hook : nil
2441             Repeat Outside : [Toggle]  off (nil)
2442 [INS] [DEL] List:
2443             Macro with args: \nindex@{*@}
2444             Index Tag      : [Value Menu] String: name
2445             Access Key     : n
2446             Key Prefix     : 
2447             Exclusion hook : nil
2448             Repeat Outside : [Toggle]  off (nil)
2449 [INS] [DEL] List:
2450             Macro with args: \astobj@{*@}
2451             Index Tag      : [Value Menu] String: idx
2452             Access Key     : o
2453             Key Prefix     : Astronomical Objects!
2454             Exclusion hook : nil
2455             Repeat Outside : [Toggle]  on (non-nil)
2456 [INS]
2457 @end example
2459 With the macro @code{\ix} defined, you may want to change the default
2460 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2461 This would be done like this
2463 @lisp
2464 (setq reftex-index-default-macro '(?x "idx"))
2465 @end lisp
2467 which specifies that the macro identified with the character @code{?x} (the
2468 @code{\ix} macro) should be used for indexing phrases and words already
2469 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2470 The index tag is "idx".@refill
2472 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2473 @chapter Viewing Cross--References
2474 @findex reftex-view-crossref
2475 @findex reftex-mouse-view-crossref
2476 @kindex C-c &
2477 @kindex S-mouse-2
2479 @b{Ref@TeX{}} can display cross--referencing information.  This means,
2480 if two document locations are linked, @b{Ref@TeX{}} can display the
2481 matching location(s) in another window.  The @code{\label} and @code{\ref}
2482 macros are one way of establishing such a link.  Also, a @code{\cite}
2483 macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
2484 database entry.@refill
2486 The feature is invoked by pressing @kbd{C-c &}
2487 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2488 of a macro involved in cross--referencing.  You can also click with
2489 @kbd{S-mouse-2} on the macro argument.  Here is what will happen for
2490 individual classes of macros:@refill
2492 @table @asis
2494 @item @code{\ref}
2495 @cindex @code{\ref}
2496 Display the corresponding label definition.  All usual
2497 variants@footnote{all macros that start with @samp{ref} or end with
2498 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2499 cross--reference display.  This works also for labels defined in an
2500 external document when the current document refers to them through the
2501 @code{xr} interface (@pxref{xr (LaTeX package)}).@refill
2503 @item @code{\label}
2504 @cindex @code{\label}
2505 @vindex reftex-label-alist
2506 Display a document location which references this label.  Pressing
2507 @kbd{C-c &} several times moves through the entire document and finds
2508 all locations.  Not only the @code{\label} macro but also other macros
2509 with label arguments (as configured with @code{reftex-label-alist}) are
2510 active for cross--reference display.@refill
2512 @item @code{\cite}
2513 @cindex @code{\cite}
2514 Display the corresponding BibTeX database entry or @code{\bibitem}.
2515 All usual variants@footnote{all macros that either start or end with
2516 @samp{cite}} of the @code{\cite} macro are active for cross--reference
2517 display.@refill
2519 @item @code{\bibitem}
2520 @cindex @code{\bibitem}
2521 Display a document location which cites this article. Pressing
2522 @kbd{C-c &} several times moves through the entire document and finds
2523 all locations.@refill
2525 @item BibTeX
2526 @cindex BibTeX buffer, viewing cite locations from
2527 @cindex Viewing cite locations from BibTeX buffer
2528 @kbd{C-c &} is also active in BibTeX buffers.  All locations in a
2529 document where the database entry at point is cited will be displayed.
2530 On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
2531 the document you want to search.  Subsequent calls will use the same
2532 document, until you break this link with a prefix argument to @kbd{C-c
2533 &}.@refill
2535 @item @code{\index}
2536 @cindex @code{\index}
2537 Display other locations in the document which are marked by an index
2538 macro with the same key argument.  Along with the standard @code{\index}
2539 and @code{\glossary} macros, all macros configured in
2540 @code{reftex-index-macros} will be recognized.@refill
2541 @end table
2543 @vindex reftex-view-crossref-macros
2544 While the display of cross referencing information for the above
2545 mentioned macros is hard--coded, you can configure additional relations
2546 in the variable @code{reftex-view-crossref-macros}.
2547     
2548 @iftex
2549 @chapter All the Rest
2550 @end iftex
2552 @node RefTeXs Menu, Keybindings, Viewing Cross-References, Top
2553 @section @b{Ref@TeX{}}'s Menu
2554 @cindex RefTeXs Menu
2555 @cindex Menu, in the menu bar
2557 @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
2558 which support this.  From this menu you can access all of
2559 @b{Ref@TeX{}}'s commands and a few of its options.  There is also a
2560 @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
2561 entire set of options.@refill
2563 @node Keybindings, Faces, RefTeXs Menu, Top
2564 @section Default Keybindings
2565 @cindex Keybindings, summary
2567 Here is a summary of the available keybindings.
2569 @kindex C-c =
2570 @kindex C-c (
2571 @kindex C-c )
2572 @kindex C-c [
2573 @kindex C-c &
2574 @kindex S-mouse-2
2575 @kindex C-c /
2576 @kindex C-c \
2577 @kindex C-c |
2578 @kindex C-c <
2579 @kindex C-c >
2580 @example
2581 @kbd{C-c =}      @code{reftex-toc}
2582 @kbd{C-c (}      @code{reftex-label}
2583 @kbd{C-c )}      @code{reftex-reference}
2584 @kbd{C-c [}      @code{reftex-citation}
2585 @kbd{C-c &}      @code{reftex-view-crossref}
2586 @kbd{S-mouse-2}  @code{reftex-mouse-view-crossref}
2587 @kbd{C-c /}      @code{reftex-index-selection-or-word}
2588 @kbd{C-c \}      @code{reftex-index-phrase-selection-or-word}
2589 @kbd{C-c |}      @code{reftex-index-visit-phrases-buffer}
2590 @kbd{C-c <}      @code{reftex-index}
2591 @kbd{C-c >}      @code{reftex-display-index}
2592 @end example
2594 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2595 not already used by some other package.  @b{Ref@TeX{}} will not override an
2596 existing binding to @kbd{S-mouse-2}.@refill
2598 Personally, I also bind some functions in the users @kbd{C-c} map for
2599 easier access.@refill
2601 @c FIXME: Do we need bindings for the Index macros here as well?
2602 @c C-c i   C-c I or so????
2603 @c How about keybindings for reftex-reset-mode and reftex-parse-document?
2604 @kindex C-c t
2605 @kindex C-c l
2606 @kindex C-c r
2607 @kindex C-c c
2608 @kindex C-c v
2609 @kindex C-c s
2610 @kindex C-c g
2611 @example
2612 @kbd{C-c t}    @code{reftex-toc}
2613 @kbd{C-c l}    @code{reftex-label}
2614 @kbd{C-c r}    @code{reftex-reference}
2615 @kbd{C-c c}    @code{reftex-citation}
2616 @kbd{C-c v}    @code{reftex-view-crossref}
2617 @kbd{C-c s}    @code{reftex-search-document}
2618 @kbd{C-c g}    @code{reftex-grep-document}
2619 @end example
2621 @noindent These keys are reserved for the user, so I cannot bind them by
2622 default.  If you want to have these keybindings available, set in your
2623 @file{.emacs} file:
2625 @vindex reftex-extra-bindings
2626 @lisp
2627 (setq reftex-extra-bindings t)
2628 @end lisp
2630 @vindex reftex-load-hook
2631 Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook
2632 @code{reftex-load-hook}.  For information on the keymaps
2633 which should be used to add keys, see @ref{Keymaps and Hooks}.
2635 @node Faces, AUCTeX, Keybindings, Top
2636 @section Faces
2637 @cindex Faces
2639 @b{Ref@TeX{}} uses faces when available to structure the selection and
2640 table of contents buffers.  It does not create its own faces, but uses
2641 the ones defined in @file{font-lock.el}.  Therefore, @b{Ref@TeX{}} will
2642 use faces only when @code{font-lock} is loaded.  This seems to be
2643 reasonable because people who like faces will very likely have it
2644 loaded.  If you wish to turn off fontification or change the involved
2645 faces, see @ref{Options (Fontification)}.@refill
2647 @node Multifile Documents, Language Support, AUCTeX, Top
2648 @section Multifile Documents
2649 @cindex Multifile documents
2650 @cindex Documents, spread over files
2652 The following is relevant when working with documents spread over many
2653 files:@refill
2655 @itemize @bullet
2656 @item
2657 @b{Ref@TeX{}} has full support for multifile documents.  You can edit parts of
2658 several (multifile) documents at the same time without conflicts.
2659 @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
2660 @code{query-replace} on all files which are part of a multifile
2661 document.@refill
2663 @item
2664 @vindex tex-main-file
2665 @vindex TeX-master
2666 All files belonging to a multifile document should define a File
2667 Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
2668 standard Emacs LaTeX mode) containing the name of the master file.  For
2669 example, to set the file variable @code{TeX-master}, include something
2670 like the following at the end of each TeX file:@refill
2672 @example
2673 %%% Local Variables: ***
2674 %%% mode:latex ***
2675 %%% TeX-master: "thesis.tex"  ***
2676 %%% End: ***
2677 @end example
2679 AUCTeX with the setting
2681 @lisp
2682 (setq-default TeX-master nil)
2683 @end lisp
2685 will actually ask you for each new file about the master file and insert
2686 this comment automatically.  For more details see the documentation of
2687 the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
2688 documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2689 The GNU Emacs Manual}) and the Emacs documentation on File Variables
2690 (@pxref{File Variables,,,emacs, The GNU Emacs Manual}).@refill
2692 @item
2693 The context of a label definition must be found in the same file as the
2694 label itself in order to be processed correctly by @b{Ref@TeX{}}.  The only
2695 exception is that section labels referring to a section statement
2696 outside the current file can still use that section title as
2697 context.@refill
2698 @end itemize
2700 @node Language Support, Finding Files, Multifile Documents, Top
2701 @section Language Support
2702 @cindex Language support
2704 Some parts of @b{Ref@TeX{}} are language dependent.  The default
2705 settings work well for English.  If you are writing in a different
2706 language, the following hints may be useful:
2708 @itemize @bullet
2709 @item
2710 @vindex reftex-derive-label-parameters
2711 @vindex reftex-abbrev-parameters
2712 The mechanism to derive a label from context includes the abbreviation
2713 of words and omission of unimportant words.  These mechanisms may have
2714 to be changed for other languages.  See the variables
2715 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2717 @item
2718 @vindex reftex-translate-to-ascii-function
2719 @vindex reftex-label-illegal-re
2720 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
2721 context string from non-ASCII characters in order to make a legal label.
2722 If there should ever be a version of @TeX{} which allows extended
2723 characters @emph{in labels}, then we will have to look at the
2724 variables @code{reftex-translate-to-ascii-function} and
2725 @code{reftex-label-illegal-re}.
2727 @item
2728 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
2729 to guess which label type is required.  These @emph{magic words} are
2730 different in every language.  For an example of how to add magic words,
2731 see @ref{Adding Magic Words}.
2733 @vindex reftex-multiref-punctuation
2734 @vindex reftex-cite-punctuation
2735 @item 
2736 @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
2737 for the author list in citations.  Some of this may be language
2738 dependent.  See the variables @code{reftex-multiref-punctuation} and
2739 @code{reftex-cite-punctuation}.
2740 @end itemize
2742 @node Finding Files, Optimizations, Language Support, Top
2743 @section Finding Files
2744 @cindex Finding files
2746 In order to find files included in a document via @code{\input} or
2747 @code{\include}, @b{Ref@TeX{}} searches all directories specified in the
2748 environment variable @code{TEXINPUTS}.  Similarly, it will search the
2749 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
2750 BibTeX database files.
2752 When searching, @b{Ref@TeX{}} will also expand recursive path
2753 definitions (directories ending in @samp{//} or @samp{!!}).  But it will
2754 only search and expand directories @emph{explicitly} given in these
2755 variables. This may cause problems under the following circumstances:
2757 @itemize @bullet
2758 @item
2759 Most TeX system have a default search path for both TeX files and BibTeX
2760 files which is defined in some setup file.  Usually this default path is
2761 for system files which @b{Ref@TeX{}} does not need to see.  But if your
2762 document needs TeX files or BibTeX database files in a directory only
2763 given in the default search path, @b{Ref@TeX{}} will fail to find them.
2764 @item
2765 Some TeX systems do not use environment variables at all in order to
2766 specify the search path.  Both default and user search path are then
2767 defined in setup files.
2768 @end itemize
2770 @noindent
2771 There are three ways to solve this problem:
2773 @itemize @bullet
2774 @item
2775 Specify all relevant directories explicitly in the environment
2776 variables.  If for some reason you don't want to mess with the default
2777 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
2778 variables and configure @b{Ref@TeX{}} to use them instead:
2780 @lisp
2781 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
2782 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
2783 @end lisp
2785 @item
2786 Specify the full search path directly in @b{Ref@TeX{}}'s variables.
2788 @lisp
2789 (setq reftex-texpath-environment-variables 
2790       '("./inp:/home/cd/tex//:/usr/local/tex//"))
2791 (setq reftex-bibpath-environment-variables
2792       '("/home/cd/tex/lit/"))
2793 @end lisp
2795 @item
2796 Some TeX systems provide stand--alone programs to do the file search just
2797 like TeX and BibTeX.  E.g. Thomas Esser's @code{teTeX} uses the
2798 @code{kpathsearch} library which provides the command @code{kpsewhich}
2799 to search for files.  @b{Ref@TeX{}} can be configured to use this
2800 program.  Note that the exact syntax of the @code{kpsewhich}
2801 command depends upon the version of that program.
2803 @lisp
2804 (setq reftex-use-external-file-finders t)
2805 (setq reftex-external-file-finders
2806       '(("tex" "kpsewhich -format=.tex %f")
2807         ("bib" "kpsewhich -format=.bib %f")))      
2808 @end lisp
2809 @end itemize
2811 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
2812 @section Optimizations
2813 @cindex Optimizations
2815 Implementing the principle of least surprises, the default settings of
2816 @b{Ref@TeX{}} ensure a safe ride for beginners and casual users.  However,
2817 when using @b{Ref@TeX{}} for a large project and/or on a small computer,
2818 there are ways to improve speed or memory usage.@refill
2820 @itemize @bullet
2821 @item
2822 @b{Removing Lookup Buffers}@*
2823 @cindex Removing lookup buffers
2824 @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
2825 database files for lookup purposes.  These buffers are kept, so that
2826 subsequent use of the same files is fast.  If you can't afford keeping
2827 these buffers around, and if you can live with a speed penalty, try
2829 @vindex reftex-keep-temporary-buffers
2830 @lisp
2831 (setq reftex-keep-temporary-buffers nil)
2832 @end lisp
2834 @item
2835 @b{Partial Document Scans}@*
2836 @cindex Partial documents scans
2837 @cindex Document scanning, partial
2838 A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
2839 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
2840 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
2841 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
2842 re-parsing of the entire document in order to update the parsing
2843 information.  For a large document this can be unnecessary, in
2844 particular if only one file has changed.  @b{Ref@TeX{}} can be configured
2845 to do partial scans instead of full ones.  @kbd{C-u} re-parsing then
2846 does apply only to the current buffer and files included from it.
2847 Likewise, the @kbd{r} key in both the label selection buffer and the
2848 table-of-contents buffer will only prompt scanning of the file in which
2849 the label or section macro near the cursor was defined.  Re-parsing of
2850 the entire document is still available by using @kbd{C-u C-u} as a
2851 prefix, or the capital @kbd{R} key in the menus.  To use this feature,
2852 try@refill
2854 @vindex reftex-enable-partial-scans
2855 @lisp
2856 (setq reftex-enable-partial-scans t)
2857 @end lisp
2859 @item
2860 @b{Saving Parser Information}@*
2861 @cindex Saving parser information
2862 @cindex Parse information, saving to a file
2863 @vindex reftex-parse-file-extension
2864 Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
2865 scan, when you start working with a document.  To avoid this, parsing
2866 information can be stored in a file.  The file @file{MASTER.rel} is used
2867 for storing information about a document with master file
2868 @file{MASTER.tex}.  It is written automatically when you kill a buffer
2869 in @code{reftex-mode} or when you exit Emacs.  The information is
2870 restored when you begin working with a document in a new editing
2871 session.  To use this feature, put into @file{.emacs}:@refill
2873 @vindex reftex-save-parse-info
2874 @lisp
2875 (setq reftex-save-parse-info t)
2876 @end lisp
2878 @item
2879 @b{Automatic Document Scans}@*
2880 @cindex Automatic document scans
2881 @cindex Document scanning, automatic
2882 At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
2883 document.  If this gets into your way, it can be turned off with
2885 @vindex reftex-allow-automatic-rescan
2886 @lisp
2887 (setq reftex-allow-automatic-rescan nil)
2888 @end lisp
2890 @b{Ref@TeX{}} will then occasionally annotate new labels in the selection
2891 buffer, saying that their position in the label list in uncertain.  A
2892 manual document scan will fix this.@refill
2894 @item
2895 @b{Multiple Selection Buffers}@*
2896 @cindex Multiple selection buffers
2897 @cindex Selection buffers, multiple
2898 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
2899 every selection process.  In documents with very many labels this can
2900 take several seconds.  @b{Ref@TeX{}} provides an option to create a
2901 separate selection buffer for each label type and to keep this buffer
2902 from one selection to the next.  These buffers are updated automatically
2903 only when a new label has been added in the buffers category with
2904 @code{reftex-label}.  Updating the buffer takes as long as recreating it
2905 - so the time saving is limited to cases where no new labels of that
2906 category have been added.  To turn on this feature, use@refill
2908 @vindex reftex-use-multiple-selection-buffers
2909 @lisp
2910 (setq reftex-use-multiple-selection-buffers t)
2911 @end lisp
2913 @noindent
2914 @cindex Selection buffers, updating
2915 You can also inhibit the automatic updating entirely.  Then the
2916 selection buffer will always pop up very fast, but may not contain the
2917 most recently defined labels.  You can always update the buffer by hand,
2918 with the @kbd{g} key.  To get this behavior, use instead@refill
2920 @vindex reftex-auto-update-selection-buffers
2921 @lisp
2922 (setq reftex-use-multiple-selection-buffers t
2923       reftex-auto-update-selection-buffers nil)
2924 @end lisp
2925 @end itemize
2927 @need 2000
2928 @noindent
2929 @b{As a summary}, here are the settings I recommend for heavy use of
2930 @b{Ref@TeX{}} with large documents:
2932 @lisp
2933 @group
2934 (setq reftex-enable-partial-scans t
2935       reftex-save-parse-info t
2936       reftex-use-multiple-selection-buffers t)
2937 @end group
2938 @end lisp
2940 @page
2941 @node AUCTeX, Multifile Documents, Faces, Top
2942 @section @w{AUC @TeX{}}
2943 @cindex @code{AUCTeX}, Emacs package
2944 @cindex Emacs packages, @code{AUCTeX}
2946 AUCTeX is without doubt the best major mode for editing TeX and LaTeX
2947 files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
2948 If AUCTeX is not part of you Emacs distribution, you can get
2949 it@footnote{XEmacs 21.x users may want to install the corresponding
2950 XEmacs package.} by ftp from the
2951 @uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.
2953 @menu
2954 * AUCTeX-RefTeX Interface::          How both packages work together
2955 * Style Files::                      AUCTeX's style files can support RefTeX
2956 * Bib-Cite::                         Hypertext reading of a document
2957 @end menu
2959 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
2960 @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
2962 @b{Ref@TeX{}} contains code to interface with AUCTeX.  When this
2963 interface is turned on, both packages will interact closely.  Instead of
2964 using @b{Ref@TeX{}}'s commands directly, you can then also use them
2965 indirectly as part of the AUCTeX
2966 environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
2967 needed for all of this to work.  Parts of it work also with earlier
2968 versions.}.  The interface is turned on with@refill
2970 @lisp
2971 (setq reftex-plug-into-AUCTeX t)
2972 @end lisp
2974 If you need finer control about which parts of the interface are used
2975 and which not, read the docstring of the variable
2976 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
2977 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
2979 The following list describes the individual parts of the interface.
2981 @itemize @bullet
2982 @item
2983 @findex reftex-label
2984 @vindex LaTeX-label-function, @r{AUCTeX}
2985 @kindex C-c C-e
2986 @kindex C-c C-s
2987 @findex LaTeX-section, @r{AUCTeX}
2988 @findex TeX-insert-macro, @r{AUCTeX}
2989 @b{AUCTeX calls @code{reftex-label} to insert labels}@*
2990 When a new section is created with @kbd{C-c C-s}, or a new environment
2991 is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
2992 go with it.  With the interface, @code{reftex-label} is called instead.
2993 For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
2994 @b{Ref@TeX{}} will insert
2996 @example
2997 \begin@{equation@}
2998 \label@{eq:1@}
3000 \end@{equation@}
3001 @end example
3003 @noindent
3004 without further prompts.
3006 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
3007 will offer its default label which is derived from the section title.
3009 @item
3010 @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
3011 When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
3012 have to rescan the buffer in order to see it.@refill
3014 @item
3015 @findex reftex-arg-label
3016 @findex TeX-arg-label, @r{AUCTeX function}
3017 @findex reftex-arg-ref
3018 @findex TeX-arg-ref, @r{AUCTeX function}
3019 @findex reftex-arg-cite
3020 @findex TeX-arg-cite, @r{AUCTeX function}
3021 @findex reftex-arg-index
3022 @findex TeX-arg-index, @r{AUCTeX function}
3023 @findex TeX-insert-macro, @r{AUCTeX function}
3024 @kindex C-c @key{RET}
3025 @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
3026 interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
3027 macro arguments.  Internally, it uses the functions
3028 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3029 prompt for arguments which are labels, citation keys and index entries.
3030 The interface takes over these functions@footnote{@code{fset} is used to
3031 do this, which is not reversible.  However, @b{Ref@TeX{}} implements the
3032 old functionality when you later decide to turn off the interface.} and
3033 supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms.  For
3034 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
3035 will supply its label selection process (@pxref{Referencing
3036 Labels}).@refill
3038 @item
3039 @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
3040 @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
3041 @end itemize
3043 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
3044 @subsection Style Files
3045 @cindex Style files, AUCTeX
3046 @findex TeX-add-style-hook, @r{AUCTeX}
3047 Style files are Emacs Lisp files which are evaluated by AUCTeX in
3048 association with the @code{\documentclass} and @code{\usepackage}
3049 commands of a document (@pxref{Style Files,,,auctex}). Support for
3050 @b{Ref@TeX{}} in such a style file is useful when the LaTeX style
3051 defines macros or environments connected with labels, citations, or the
3052 index.  Many style files (e.g. @file{amsmath.el} or @file{natbib.el})
3053 distributed with AUCTeX already support @b{Ref@TeX{}} in this
3054 way.@refill
3056 Before calling a @b{Ref@TeX{}} function, the style hook should always
3057 test for the availability of the function, so that the style file will
3058 also work for people who do not use @b{Ref@TeX{}}. @refill
3060 Additions made with style files in the way described below remain local
3061 to the current document.  For example, if one package uses AMSTeX, the
3062 style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
3063 this will not affect other documents.@refill
3065 @findex reftex-add-label-environments
3066 @findex reftex-add-to-label-alist
3067 A style hook may contain calls to
3068 @code{reftex-add-label-environments}@footnote{This used to be the
3069 function @code{reftex-add-to-label-alist} which is still available as an
3070 alias for compatibility.}  which defines additions to
3071 @code{reftex-label-alist}.  The argument taken by this function must have
3072 the same format as @code{reftex-label-alist}.  The @file{amsmath.el}
3073 style file of AUCTeX for example contains the following:@refill
3075 @lisp
3076 @group
3077 (TeX-add-style-hook "amsmath"
3078    (lambda ()
3079      (if (fboundp 'reftex-add-label-environments)
3080          (reftex-add-label-environments '(AMSTeX)))))
3081 @end group
3082 @end lisp
3084 @noindent
3085 @findex LaTeX-add-environments, @r{AUCTeX}
3086 while a package @code{myprop} defining a @code{proposition} environment
3087 with @code{\newtheorem} might use@refill
3089 @lisp
3090 @group
3091 (TeX-add-style-hook "myprop"
3092    (lambda ()
3093      (LaTeX-add-environments '("proposition" LaTeX-env-label))
3094      (if (fboundp 'reftex-add-label-environments)
3095          (reftex-add-label-environments
3096           '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3097                            ("Proposition" "Prop.") -3))))))
3098 @end group
3099 @end lisp
3101 @findex reftex-set-cite-format
3102 Similarly, a style hook may contain a call to
3103 @code{reftex-set-cite-format} to set the citation format.  The style
3104 file @file{natbib.el} for the Natbib citation style does switch
3105 @b{Ref@TeX{}}'s citation format like this:@refill
3107 @lisp
3108 (TeX-add-style-hook "natbib"
3109    (lambda ()
3110      (if (fboundp 'reftex-set-cite-format)
3111          (reftex-set-cite-format 'natbib))))
3112 @end lisp
3114 @findex reftex-add-index-macros 
3115 The hook may contain a call to @code{reftex-add-index-macros} to
3116 define additional @code{\index}-like macros.  The argument must have
3117 the same format as @code{reftex-index-macros}.  It may be a symbol, to
3118 trigger support for one of the builtin index packages.  For example,
3119 the style @file{multind.el} contains
3121 @lisp
3122 (TeX-add-style-hook "multind"
3123   (lambda ()
3124     (and (fboundp 'reftex-add-index-macros)
3125          (reftex-add-index-macros '(multind)))))
3126 @end lisp
3128 If you have your own package @file{myindex} which defines the
3129 following macros to be used with the LaTeX @file{index.sty} file
3130 @example
3131 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3132 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3133 @end example
3135 you could write this in the style file @file{myindex.el}:
3137 @lisp
3138 (TeX-add-style-hook "myindex"
3139    (lambda ()
3140      (TeX-add-symbols
3141       '("molec" TeX-arg-index)
3142       '("aindex" TeX-arg-index))
3143      (if (fboundp 'reftex-add-index-macros)
3144          (reftex-add-index-macros
3145           '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3146             ("aindex@{*@}" "author" ?a "" nil nil))))))
3147 @end lisp
3149 @findex reftex-add-section-levels
3150 Finally the hook may contain a call to @code{reftex-add-section-levels}
3151 to define additional section statements.  For example, the FoilTeX class
3152 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}.  Here
3153 is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
3155 @lisp
3156 (TeX-add-style-hook "foils"
3157    (lambda ()
3158      (if (fboundp 'reftex-add-section-levels)
3159          (reftex-add-section-levels '(("foilhead" . 3)
3160                                       ("rotatefoilhead" . 3))))))
3161 @end lisp
3163 @node Bib-Cite, , Style Files, AUCTeX
3164 @subsection Bib-Cite
3165 @cindex @code{bib-cite}, Emacs package
3166 @cindex Emacs packages, @code{bib-cite}
3168 Once you have written a document with labels, references and citations,
3169 it can be nice to read it like a hypertext document.  @b{Ref@TeX{}} has
3170 support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3171 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3172 @code{reftex-search-document}.  A somewhat fancier interface with mouse
3173 highlighting is provided (among other things) by Peter S. Galbraith's
3174 @file{bib-cite.el}.  There is some overlap in the functionalities of
3175 Bib-cite and @b{Ref@TeX{}}.  Bib-cite.el comes bundled with
3176 AUCTeX.@refill
3178 Bib-cite version 3.06 and later can be configured so that bib-cite's
3179 mouse functions use @b{Ref@TeX{}} for displaying references and citations.
3180 This can be useful in particular when working with the LaTeX @code{xr}
3181 package or with an explicit @code{thebibliography} environment (rather
3182 than BibTeX).  Bib-cite cannot handle those, but @b{Ref@TeX{}} does.  To
3183 make use of this feature, try@refill
3185 @vindex bib-cite-use-reftex-view-crossref
3186 @lisp
3187 (setq bib-cite-use-reftex-view-crossref t)
3188 @end lisp
3190 @page
3191 @node Problems and Work-Arounds, Imprint, Optimizations, Top
3192 @section Problems and Work-arounds
3193 @cindex Problems and work-arounds
3195 @itemize @bullet
3196 @item
3197 @b{LaTeX commands}@*
3198 @cindex LaTeX commands, not found
3199 @code{\input}, @code{\include}, @code{\bibliography} and @code{\section}
3200 (etc.) statements have to be first on a line (except for white space).@refill
3202 @item
3203 @b{Commented regions}@*
3204 @cindex Labels, commented out
3205 @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
3206 make duplicates of such labels.  This is considered to be a feature.@refill
3208 @item
3209 @b{Wrong section numbers}@*
3210 @cindex Section numbers, wrong
3211 @vindex reftex-enable-partial-scans
3212 When using partial scans (@code{reftex-enable-partial-scans}), the section
3213 numbers in the table of contents may eventually become wrong.  A full
3214 scan will fix this.@refill
3216 @item
3217 @b{Local settings}@*
3218 @cindex Settings, local
3219 @findex reftex-add-label-environments
3220 @findex reftex-set-cite-format
3221 @findex reftex-add-section-levels
3222 The label environment definitions in @code{reftex-label-alist} are
3223 global and apply to all documents.  If you need to make definitions
3224 local to a document, because they would interfere with settings in other
3225 documents, you should use AUCTeX and set up style files with calls to
3226 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3227 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3228 Settings made with these functions remain local to the current
3229 document. @xref{AUCTeX}.@refill
3231 @item
3232 @b{Funny display in selection buffer}@*
3233 @cindex @code{x-symbol}, Emacs package
3234 @cindex Emacs packages, @code{x-symbol}
3235 @cindex @code{isotex}, Emacs package
3236 @cindex Emacs packages, @code{isotex}
3237 @cindex @code{iso-cvt}, Emacs package
3238 @cindex Emacs packages, @code{iso-cvt}
3239 When using packages which make the buffer representation of a file
3240 different from its disk representation (e.g. x-symbol, isotex,
3241 iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
3242 reflects the disk state of a file.  This happens only in @emph{unvisited}
3243 parts of a multifile document, because @b{Ref@TeX{}} visits these files
3244 literally for speed reasons.  Then both short context and section
3245 headings may look different from what you usually see on your screen.
3246 In rare cases @code{reftex-toc} may have problems to jump to an affected
3247 section heading.  There are three possible ways to deal with
3248 this:@refill 
3249 @itemize @minus
3250 @item
3251 @vindex reftex-keep-temporary-buffers
3252 @code{(setq reftex-keep-temporary-buffers t)}@*
3253 This implies that @b{Ref@TeX{}} will load all parts of a multifile
3254 document into Emacs (i.e. there won't be any temporary buffers).@refill
3255 @item
3256 @vindex reftex-initialize-temporary-buffers
3257 @code{(setq reftex-initialize-temporary-buffers t)}@*
3258 This means full initialization of temporary buffers.  It involves
3259 a penalty when the same unvisited file is used for lookup often.@refill
3260 @item
3261 Set @code{reftex-initialize-temporary-buffers} to a list of hook
3262 functions doing a minimal initialization.@refill
3263 @end itemize
3264 @vindex reftex-refontify-context
3265 See also the variable @code{reftex-refontify-context}.
3267 @item
3268 @b{Labels as arguments to \begin}@*
3269 @cindex @code{pf}, LaTeX package
3270 @cindex LaTeX packages, @code{pf}
3271 Some packages use an additional argument to a @code{\begin} macro
3272 to specify a label.  E.g. Lamport's @file{pf.sty} uses both
3273 @example
3274 \step@{@var{label}@}@{@var{claim}@}   and      \begin@{step+@}@{@var{label}@}
3275                                   @var{claim}
3276                                \end@{step+@}
3277 @end example
3279 @noindent
3280 We need to trick @b{Ref@TeX{}} into swallowing this:
3282 @lisp
3283 @group
3284 ;; Configuration for Lamport's pf.sty
3285 (setq reftex-label-alist
3286   '(("\\step@{*@}@{@}"       ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3287     ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3288 @end group
3289 @end lisp
3291 @noindent
3292 The first line is just a normal configuration for a macro.  For the
3293 @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
3294 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3295 argument (which really is a second argument to the macro @code{\begin})
3296 as a label of type @code{?p}.  Argument count for this macro starts only
3297 after the @samp{@{step+@}}, also when specifying how to get
3298 context.@refill 
3300 @item
3301 @b{Idle timers in XEmacs}@*
3302 @cindex Idle timer restart
3303 @vindex reftex-use-itimer-in-xemacs
3304 In XEmacs, idle timer restart does not work reliably after fast
3305 keystrokes.  Therefore @b{Ref@TeX{}} currently uses the post command
3306 hook to start the timer used for automatic crossref information.  When
3307 this bug gets fixed, a real idle timer can be requested with
3308 @lisp
3309 (setq reftex-use-itimer-in-xemacs t)
3310 @end lisp
3312 @item
3313 @b{Viper mode}@*
3314 @cindex Viper mode
3315 @cindex Keybindings, problems with Viper mode
3316 @findex viper-harness-minor-mode
3317 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3318 @b{Ref@TeX{}}'s keymaps with@refill
3320 @lisp
3321 (viper-harness-minor-mode "reftex")
3322 @end lisp
3324 @end itemize
3326 @page
3327 @node Imprint, Commands, Problems and Work-Arounds, Top
3328 @section Imprint
3329 @cindex Imprint
3330 @cindex Maintainer
3331 @cindex Acknowledgments
3332 @cindex Thanks
3333 @cindex Bug reports
3334 @cindex @code{http}, @b{Ref@TeX{}} home page
3335 @cindex @code{ftp}, @b{Ref@TeX{}} site
3337 @b{Ref@TeX{}} was written by @i{@value{AUTHOR}}
3338 @email{@value{AUTHOR-EMAIL}}, with contributions by @i{Stephen
3339 Eglen}.  @b{Ref@TeX{}} is currently maintained by @refill
3341 @noindent
3342 @value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}}
3344 If you have questions about @b{Ref@TeX{}}, there are several Usenet
3345 groups which have competent readers: @code{comp.emacs},
3346 @code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}.
3347 You can also write directly to the maintainer.
3349 If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
3350 to contribute code or ideas, please
3351 @uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}.  Remember
3352 to provide all necessary information such as version numbers of Emacs
3353 and @b{Ref@TeX{}}, and the relevant part of your configuration in
3354 @file{.emacs}.  When reporting a bug which throws an exception, please
3355 include a backtrace if you know how to produce one.
3357 @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
3358 It was also bundled and pre-installed with XEmacs 19.16--20.x.  XEmacs
3359 21.x users want to install the corresponding plugin package which is
3360 available from the XEmacs @code{ftp} site.  See the XEmacs 21.x
3361 documentation on package installation for details.@refill
3363 Users of earlier Emacs distributions (including Emacs 19) can get a
3364 @b{Ref@TeX{}} distribution from the
3365 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainers
3366 webpage}.  Note that the Emacs 19 version supports many but not all
3367 features described in this manual.@refill
3369 Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
3370 developing it with their reports.  In particular thanks to @i{Fran
3371 Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl Eichwalder,
3372 Peter Galbraith, Kai Grossjohann, Frank Harrell, Dieter Kraft, Adrian
3373 Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar
3374 Palat, Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan
3375 Vroonhof, Christoph Wedler, Alan Williams}.@refill
3377 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3378 @file{bib-cite.el}.@refill
3380 Finally thanks to @i{Uwe Bolick} who first got me (some years ago) into
3381 supporting LaTeX labels and references with an editor (which was
3382 MicroEmacs at the time).@refill
3384 @node Commands, Options, Imprint, Top
3385 @chapter Commands
3386 @cindex Commands, list of
3388 Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
3389 LaTeX files.  Command which are executed from the special buffers are
3390 not described here.  All commands are available from the @code{Ref}
3391 menu.  For keybindings, @pxref{Keybindings}.
3393 @deffn Command reftex-toc
3394 Show the table of contents for the current document.  When called with
3395 one ore two @kbd{C-u} prefixes, rescan the document first.@refill
3396 @end deffn
3398 @deffn Command reftex-label
3399 Insert a unique label.  With one or two @kbd{C-u} prefixes, enforce
3400 document rescan first.
3401 @end deffn
3403 @deffn Command reftex-reference
3404 Start a selection process to select a label, and insert a reference to
3405 it.  With one or two @kbd{C-u} prefixes, enforce document rescan first.
3406 @end deffn
3408 @deffn Command reftex-citation
3409 Make a citation using BibTeX database files.  After prompting for a regular
3410 expression, scans the buffers with BibTeX entries (taken from the
3411 @code{\bibliography} command or a @code{thebibliography} environment)
3412 and offers the matching entries for selection.  The selected entry is
3413 formated according to @code{reftex-cite-format} and inserted into the
3414 buffer.@refill @*
3415 When called with one or two @kbd{C-u} prefixes, first rescans the
3416 document.  When called with a numeric prefix, make that many citations.
3417 When called with point inside the braces of a @code{\cite} command, it
3418 will add another key, ignoring the value of
3419 @code{reftex-cite-format}.@refill @* 
3420 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3421 as @code{and}.  Thus, @samp{aaaa&&bbb} matches entries which contain
3422 both @samp{aaaa} and @samp{bbb}.  While entering the regexp, completion
3423 on knows citation keys is possible.  @samp{=} is a good regular
3424 expression to match all entries in all files.@refill
3425 @end deffn
3427 @deffn Command reftex-index
3428 Query for an index macro and insert it along with its arguments.  The
3429 index macros available are those defined in @code{reftex-index-macro} or
3430 by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
3431 style file.  @b{Ref@TeX{}} provides completion for the index tag and the
3432 index key, and will prompt for other arguments.@refill
3433 @end deffn
3435 @deffn Command reftex-index-selection-or-word
3436 Put current selection or the word near point into the default index
3437 macro.  This uses the information in @code{reftex-index-default-macro}
3438 to make an index entry.  The phrase indexed is the current selection or
3439 the word near point.  When called with one @kbd{C-u} prefix, let the
3440 user have a chance to edit the index entry.  When called with 2
3441 @kbd{C-u} as prefix, also ask for the index macro and other stuff.  When
3442 called inside TeX math mode as determined by the @file{texmathp.el}
3443 library which is part of AUCTeX, the string is first processed with the
3444 @code{reftex-index-math-format}, which see.@refill
3445 @end deffn
3447 @deffn Command reftex-index-phrase-selection-or-word
3448 Add current selection or the word at point to the phrases buffer.
3449 When you are in transient-mark-mode and the region is active, the
3450 selection will be used - otherwise the word at point.
3451 You get a chance to edit the entry in the phrases buffer - to save the
3452 buffer and return to the LaTeX document, finish with @kbd{C-c C-c}.
3453 @end deffn
3455 @deffn Command reftex-index-visit-phrases-buffer
3456 Switch to the phrases buffer, initialize if empty.
3457 @end deffn
3459 @deffn Command reftex-index-phrases-apply-to-region
3460 Index all index phrases in the current region.
3461 This works exactly like global indexing from the index phrases buffer,
3462 but operation is restricted to the current region.
3463 @end deffn
3465 @deffn Command reftex-display-index
3466 Display a buffer with an index compiled from the current document.
3467 When the document has multiple indices, first prompts for the correct one.
3468 When index support is turned off, offer to turn it on.
3469 With one or two @kbd{C-u} prefixes, rescan document first.
3470 With prefix 2, restrict index to current document section.
3471 With prefix 3, restrict index to active region.@refill
3472 @end deffn
3474 @deffn Command reftex-view-crossref
3475 View cross reference of macro at point.  Point must be on the @var{key}
3476 argument.  Works with the macros @code{\label}, @code{\ref},
3477 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3478 these.  Where it makes sense, subsequent calls show additional
3479 locations.  See also the variable @code{reftex-view-crossref-extra} and
3480 the command @code{reftex-view-crossref-from-bibtex}.  With one or two
3481 @kbd{C-u} prefixes, enforce rescanning of the document.  With argument
3482 2, select the window showing the cross reference.
3483 @end deffn
3485 @deffn Command reftex-view-crossref-from-bibtex
3486 View location in a LaTeX document which cites the BibTeX entry at point.
3487 Since BibTeX files can be used by many LaTeX documents, this function
3488 prompts upon first use for a buffer in @b{Ref@TeX{}} mode.  To reset this
3489 link to a document, call the function with with a prefix arg.  Calling
3490 this function several times find successive citation locations.
3491 @end deffn
3493 @deffn Command reftex-create-tags-file
3494 Create TAGS file by running @code{etags} on the current document.  The
3495 TAGS file is also immediately visited with
3496 @code{visit-tags-table}.@refill
3497 @end deffn
3499 @deffn Command reftex-grep-document
3500 Run grep query through all files related to this document.
3501 With prefix arg, force to rescan document.
3502 No active TAGS table is required.@refill
3503 @end deffn
3505 @deffn Command reftex-search-document
3506 Regexp search through all files of the current document.
3507 Starts always in the master file.  Stops when a match is found.
3508 No active TAGS table is required.@refill
3509 @end deffn
3511 @deffn Command reftex-query-replace-document
3512 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3513 document.  With prefix arg, replace only word-delimited matches.  No
3514 active TAGS table is required.@refill
3515 @end deffn
3517 @deffn Command reftex-change-label
3518 Query replace @var{from} with @var{to} in all @code{\label} and
3519 @code{\ref} commands.  Works on the entire multifile document.  No
3520 active TAGS table is required.@refill
3521 @end deffn
3523 @deffn Command reftex-renumber-simple-labels
3524 Renumber all simple labels in the document to make them sequentially.
3525 Simple labels are the ones created by RefTeX, consisting only of the
3526 prefix and a number.  After the command completes, all these labels will
3527 have sequential numbers throughout the document.  Any references to the
3528 labels will be changed as well.  For this, @b{Ref@TeX{}} looks at the
3529 arguments of any macros which either start or end with the string
3530 @samp{ref}.  This command should be used with care, in particular in
3531 multifile documents.  You should not use it if another document refers
3532 to this one with the @code{xr} package.@refill
3533 @end deffn
3535 @deffn Command reftex-find-duplicate-labels
3536 Produce a list of all duplicate labels in the document.@refill
3537 @end deffn
3539 @deffn Command reftex-customize
3540 Run the customize browser on the @b{Ref@TeX{}} group.
3541 @end deffn
3542 @deffn Command reftex-show-commentary
3543 Show the commentary section from @file{reftex.el}.
3544 @end deffn
3545 @deffn Command reftex-info
3546 Run info on the top @b{Ref@TeX{}} node.
3547 @end deffn
3548 @deffn Command reftex-parse-document
3549 Parse the entire document in order to update the parsing information.
3550 @end deffn
3551 @deffn Command reftex-reset-mode
3552 Enforce rebuilding of several internal lists and variables.  Also
3553 removes the parse file associated with the current document.
3554 @end deffn
3556 @node Options, Keymaps and Hooks, Commands, Top
3557 @chapter Options, Keymaps, Hooks
3558 @cindex Options, list of
3560 Here is a complete list of @b{Ref@TeX{}}'s configuration variables.  All
3561 variables have customize support - so if you are not familiar with Emacs
3562 Lisp (and even if you are) you might find it more comfortable to use
3563 @code{customize} to look at and change these variables. @kbd{M-x
3564 reftex-customize} will get you there.@refill
3566 @menu
3567 * Options (Table of Contents)::
3568 * Options (Defining Label Environments)::
3569 * Options (Creating Labels)::
3570 * Options (Referencing Labels)::
3571 * Options (Creating Citations)::
3572 * Options (Index Support)::
3573 * Options (Viewing Cross-References)::
3574 * Options (Finding Files)::
3575 * Options (Optimizations)::
3576 * Options (Fontification)::
3577 * Options (Misc)::
3578 @end menu
3580 @node Options (Table of Contents), Options (Defining Label Environments), ,  Options
3581 @section Table of Contents
3582 @cindex Options, table of contents
3583 @cindex Table of contents, options
3585 @defopt reftex-toc-max-level
3586 The maximum level of toc entries which will be included in the TOC.
3587 Section headings with a bigger level will be ignored.  In RefTeX,
3588 chapters are level 1, sections level 2 etc.  This variable can be
3589 changed from within the @file{*toc*} buffer with the @kbd{t} key.@refill
3590 @end defopt
3592 @defopt reftex-toc-keep-other-windows
3593 Non-@code{nil} means, split the selected window to display the
3594 @file{*toc*} buffer.  This helps to keep the window configuration, but
3595 makes the @file{*toc*} small.  When @code{nil}, all other windows except
3596 the selected one will be deleted, so that the @file{*toc*} window fills
3597 half the frame.@refill
3598 @end defopt
3600 @defopt reftex-toc-include-file-boundaries
3601 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3602 This flag can be toggled from within the @file{*toc*} buffer with the
3603 @kbd{i} key.@refill
3604 @end defopt
3606 @defopt reftex-toc-include-labels
3607 Non-@code{nil} means, include labels in @file{*toc*} buffer.  This flag
3608 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3609 key.@refill
3610 @end defopt
3612 @defopt reftex-toc-include-index-entries
3613 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3614 This flag can be toggled from within the @file{*toc*} buffer with the
3615 @kbd{i} key.
3616 @end defopt
3618 @defopt reftex-toc-include-context
3619 Non-@code{nil} means, include context with labels in the @file{*toc*}
3620 buffer.  Context will only be shown if the labels are visible as well.
3621 This flag can be toggled from within the @file{*toc*} buffer with the
3622 @kbd{c} key.@refill
3623 @end defopt
3625 @defopt reftex-toc-follow-mode
3626 Non-@code{nil} means, point in @file{*toc*} buffer (the
3627 table-of-contents buffer) will cause other window to follow.  The other
3628 window will show the corresponding part of the document.  This flag can
3629 be toggled from within the @file{*toc*} buffer with the @kbd{f}
3630 key.@refill
3631 @end defopt
3633 @deffn {Normal Hook} reftex-toc-mode-hook
3634 Normal hook which is run when a @file{*toc*} buffer is
3635 created.@refill
3636 @end deffn
3638 @deffn Keymap reftex-toc-map
3639 The keymap which is active in the @file{*toc*} buffer.
3640 (@pxref{Table of Contents}).@refill
3641 @end deffn
3643 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
3644 @section Defining Label Environments
3645 @cindex Options, defining label environments
3646 @cindex Defining label environments, options
3648 @defopt reftex-default-label-alist-entries
3649 Default label alist specifications.  It is a list of symbols with
3650 associations in the constant @code{reftex-label-alist-builtin}.
3651 @code{LaTeX} should always be the last entry.@refill
3652 @end defopt
3654 @defopt reftex-label-alist
3655 Set this variable to define additions and changes to the defaults in
3656 @code{reftex-default-label-alist-entries}.  The only things you
3657 @emph{must not} change is that @code{?s} is the type indicator for
3658 section labels, and @key{SPC} for the @code{any} label type.  These are
3659 hard-coded at other places in the code.@refill
3661 The value of the variable must be a list of items.  Each item is a list
3662 itself and has the following structure:
3664 @example
3665  (@var{env-or-macro}  @var{type-key}  @var{label-prefix}  @var{reference-format}
3666     @var{context-method}  (@var{magic-word} ... )  @var{toc-level})
3667 @end example
3669 Each list entry describes either an environment carrying a counter for
3670 use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
3671 label as (or inside) one of its arguments.  The elements of each list
3672 entry are:@refill
3674 @table @asis
3675 @item @var{env-or-macro}
3676 Name of the environment (like @samp{table}) or macro (like
3677 @samp{\myfig}).  For macros, indicate the arguments, as in
3678 @samp{\myfig[]@{@}@{@}@{*@}@{@}}.  Use square brackets for optional
3679 arguments, a star to mark the label argument, if any.  The macro does
3680 not have to have a label argument - you could also use
3681 @samp{\label@{...@}} inside one of its arguments.@refill
3683 Special names: @code{section} for section labels, @code{any} to define a
3684 group which contains all labels.@refill
3686 This may also be a function to do local parsing and identify point to be
3687 in a a non-standard label environment.  The function must take an
3688 argument @var{bound} and limit backward searches to this value.  It
3689 should return either nil or a cons cell @code{(@var{function}
3690 . @var{position})} with the function symbol and the position where the
3691 special environment starts.  See the Info documentation for an
3692 example.@refill
3694 Finally this may also be @code{nil} if the entry is only meant to change
3695 some settings associated with the type indicator character (see
3696 below).@refill
3698 @item @var{type-key}
3699 Type indicator character, like @code{?t}, must be a printable ASCII
3700 character.  The type indicator is a single character which defines a
3701 label type.  Any label inside the environment or macro is assumed to
3702 belong to this type.  The same character may occur several times in this
3703 list, to cover cases in which different environments carry the same
3704 label type (like @code{equation} and @code{eqnarray}).  If the type
3705 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
3706 the macro defines neutral labels just like @code{\label}.  In this case
3707 the reminder of this entry is ignored.@refill
3709 @item @var{label-prefix}
3710 Label prefix string, like @samp{tab:}.  The prefix is a short string
3711 used as the start of a label.  It may be the empty string.  The prefix
3712 may contain the following @samp{%} escapes:@refill
3714 @example
3715 %f Current file name, directory and extension stripped.
3716 %F Current file name relative to master file directory.
3717 %u User login name, on systems which support this.
3718 %S A section prefix derived with variable @code{reftex-section-prefixes}.
3719 @end example
3721 @noindent
3722 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
3723 @samp{eq:intro:}.@refill
3725 @item @var{reference-format}
3726 Format string for reference insert in buffer.  @samp{%s} will be
3727 replaced by the label.  When the format starts with @samp{~}, this
3728 @samp{~} will only be inserted when the character before point is
3729 @emph{not} a whitespace.@refill
3731 @item @var{context-method}
3732 Indication on how to find the short context.
3733 @itemize @minus
3734 @item
3735 If @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill
3736 @item
3737 If @code{t}, use
3738 @itemize @minus
3739 @item
3740 the section heading for section labels.
3741 @item
3742 text following the @samp{\begin@{...@}} statement of environments (not
3743 a good choice for environments like eqnarray or enumerate, where one has
3744 several labels in a single environment).@refill
3745 @item
3746 text after the macro name (starting with the first arg) for
3747 macros.@refill
3748 @end itemize
3749 @item
3750 If an integer, use the nth argument of the macro.  As a special case,
3751 1000 means to get text after the last macro argument.@refill
3752 @item
3753 If a string, use as regexp to search @emph{backward} from the label.
3754 Context is then the text following the end of the match.  E.g. putting
3755 this to @samp{\\caption[[@{]} will use the caption in a figure or table
3756 environment.  @samp{\\begin@{eqnarray@}\|\\\\} works for
3757 eqnarrays.@refill
3758 @item
3759 If any of @code{caption}, @code{item}, @code{eqnarray-like},
3760 @code{alignat-like}, this symbol will internally be translated into an
3761 appropriate regexp (see also the variable
3762 @code{reftex-default-context-regexps}).@refill
3763 @item
3764 If a function, call this function with the name of the environment/macro
3765 as argument.  On call, point will be just after the @code{\label} macro.
3766 The function is expected to return a suitable context string.  It should
3767 throw an exception (error) when failing to find context.  As an example,
3768 here is a function returning the 10 chars following the label macro as
3769 context:@refill
3771 @example
3772 (defun my-context-function (env-or-mac)
3773    (if (> (point-max) (+ 10 (point)))
3774        (buffer-substring (point) (+ 10 (point)))
3775      (error "Buffer too small")))
3776 @end example
3777 @end itemize
3779 Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
3780 menu, and to derive a label string.  If you want to use a different
3781 method for each of these, specify them as a dotted pair.
3782 E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
3783 display, and text from the default position (@code{t}) to derive a label
3784 string.  This is actually used for section labels.@refill
3786 @item @var{magic-word-list}
3787 List of magic words which identify a reference to be of this type.  If
3788 the word before point is equal to one of these words when calling
3789 @code{reftex-reference}, the label list offered will be automatically
3790 restricted to labels of the correct type.  If the first element of this
3791 word--list is the symbol `regexp', the strings are interpreted as regular
3792 expressions.@refill
3794 @item @var{toc-level}
3795 The integer level at which this environment should be added to the table
3796 of contents.  See also @code{reftex-section-levels}.  A positive value
3797 will number the entries mixed with the sectioning commands of the same
3798 level.  A negative value will make unnumbered entries.  Useful only for
3799 theorem-like environments which structure the document.  Will be ignored
3800 for macros.  When omitted or @code{nil}, no TOC entries will be
3801 made.@refill
3802 @end table
3804 If the type indicator characters of two or more entries are the same,
3805 @b{Ref@TeX{}} will use@refill
3806 @itemize @minus
3807 @item
3808 the first non-@code{nil} format and prefix
3809 @item
3810 the magic words of all involved entries.
3811 @end itemize
3813 Any list entry may also be a symbol.  If that has an association in
3814 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
3815 spliced into the list.  However, builtin defaults should normally be set
3816 with the variable @code{reftex-default-label-alist-entries}.@refill
3817 @end defopt
3819 @defopt reftex-max-section-depth
3820 Maximum depth of section levels in document structure.
3821 Standard LaTeX needs 7, default is 12.
3822 @end defopt
3824 @defopt reftex-section-levels
3825 Commands and levels used for defining sections in the document.  The
3826 @code{car} of each cons cell is the name of the section macro.  The
3827 @code{cdr} is a number indicating its level.  A negative level means the
3828 same as the positive value, but the section will never get a
3829 number.  The @code{cdr} may also be a function which then has to return
3830 the level.@refill
3831 @end defopt
3833 @defopt reftex-section-prefixes
3834 Prefixes for section labels.  When the label prefix given in an entry in
3835 @code{reftex-label-alist} contains @samp{%S}, this list is used to
3836 determine the correct prefix string depending on the current section
3837 level.  The list is an alist, with each entry of the form
3838 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
3839 names like @samp{chapter}, integer section levels (as given in
3840 @code{reftex-section-levels}), and @code{t} for the default.
3841 @end defopt
3843 @defopt reftex-default-context-regexps
3844 Alist with default regular expressions for finding context.  The emacs
3845 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
3846 to calculate the final regular expression - so @samp{%s} will be
3847 replaced with the environment or macro.@refill
3848 @end defopt
3850 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
3851 @section Creating Labels
3852 @cindex Options, creating labels
3853 @cindex Creating labels, options
3855 @defopt reftex-insert-label-flags
3856 Flags governing label insertion.  The value has the form
3858 @example
3859 (@var{derive} @var{prompt})
3860 @end example
3862 If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
3863 label from context.  A section label for example will be derived from
3864 the section heading.  The conversion of the context to a legal label is
3865 governed by the specifications given in
3866 @code{reftex-derive-label-parameters}.  If @var{derive} is @code{nil},
3867 the default label will consist of the prefix and a unique number, like
3868 @samp{eq:23}.@refill
3870 If @var{prompt} is @code{t}, the user will be prompted for a label
3871 string.  When @var{prompt} is @code{nil}, the default label will be
3872 inserted without query.@refill
3874 So the combination of @var{derive} and @var{prompt} controls label
3875 insertion.  Here is a table describing all four possibilities:@refill
3877 @example
3878 @group
3879 @var{derive} @var{prompt} @var{action}
3880 -----------------------------------------------------------
3881 nil    nil    @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
3882 nil    t      @r{Prompt for label.}
3883 t      nil    @r{Derive a label from context and insert. No query.}
3884 t      t      @r{Derive a label from context, prompt for confirmation.}
3885 @end group
3886 @end example
3888 Each flag may be set to @code{t}, @code{nil}, or a string of label type
3889 letters indicating the label types for which it should be true.  Thus,
3890 the combination may be set differently for each label type.  The default
3891 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
3892 headings (with confirmation).  Prompt for figure and table labels.  Use
3893 simple labels without confirmation for everything else.@refill
3895 The available label types are: @code{s} (section), @code{f} (figure),
3896 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
3897 (footnote), @code{N} (endnote) plus any definitions in
3898 @code{reftex-label-alist}.@refill
3899 @end defopt
3901 @deffn Hook reftex-format-label-function
3902 If non-@code{nil}, should be a function which produces the string to
3903 insert as a label definition.  The function will be called with two
3904 arguments, the @var{label} and the @var{default-format} (usually
3905 @samp{\label@{%s@}}).  It should return the string to insert into the
3906 buffer.@refill
3907 @end deffn
3909 @deffn Hook reftex-string-to-label-function
3910 Function to turn an arbitrary string into a legal label.
3911 @b{Ref@TeX{}}'s default function uses the variable
3912 @code{reftex-derive-label-parameters}.@refill
3913 @end deffn
3915 @deffn Hook reftex-translate-to-ascii-function
3916 Filter function which will process a context string before it is used to
3917 derive a label from it.  The intended application is to convert ISO or
3918 Mule characters into something legal in labels.  The default function
3919 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
3920 characters.  X-Symbol (>=2.6) sets this variable to the much more
3921 general @code{x-symbol-translate-to-ascii}.@refill
3922 @end deffn
3924 @defopt reftex-derive-label-parameters
3925 Parameters for converting a string into a label.  This variable is a
3926 list of the following items:@refill
3927 @table @asis
3928 @item @var{nwords}
3929 Number of words to use.
3930 @item @var{maxchar}
3931 Maximum number of characters in a label string.
3932 @item @var{illegal}
3933 @code{nil}: Throw away any words containing characters illegal in labels.@*
3934 @code{t}:   Throw away only the illegal characters, not the whole word.
3935 @item @var{abbrev}
3936 @code{nil}: Never abbreviate words.@*
3937 @code{t}:   Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
3938 @code{1}:   Abbreviate words if necessary to shorten label string.
3939 @item @var{separator}
3940 String separating different words in the label.
3941 @item @var{ignorewords}
3942 List of words which should not be part of labels.
3943 @item @var{downcase}
3944 @code{t}:   Downcase words before putting them into the label.@*
3945 @end table
3946 @end defopt
3948 @defopt reftex-label-illegal-re
3949 Regexp matching characters not legal in labels.
3950 @end defopt
3952 @defopt reftex-abbrev-parameters
3953 Parameters for abbreviation of words.  A list of four parameters.@refill
3954 @table @asis
3955 @item @var{min-chars}
3956 Minimum number of characters remaining after abbreviation.
3957 @item @var{min-kill}
3958 Minimum number of characters to remove when abbreviating words.@refill
3959 @item @var{before}
3960 Character class before abbrev point in word.@refill
3961 @item @var{after}
3962 Character class after  abbrev point in word.@refill
3963 @end table
3964 @end defopt
3966 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
3967 @section Referencing Labels
3968 @cindex Options, referencing labels
3969 @cindex Referencing labels, options
3971 @defopt reftex-label-menu-flags
3972 List of flags governing the label menu makeup. The flags are:
3973 @table @asis
3974 @item @var{table-of-contents}
3975 Show the labels embedded in a table of context.@refill
3976 @item @var{section-numbers}
3977 Include section numbers (like 4.1.3) in table of contents.@refill
3978 @item @var{counters}
3979 Show counters.  This just numbers the labels in the menu.@refill
3980 @item @var{no-context}
3981 Non-@code{nil} means do @emph{not} show the short context.@refill
3982 @item @var{follow}
3983 Follow full context in other window.@refill
3984 @item @var{show-commented}
3985 Show labels from regions which are commented out.@refill
3986 @item @var{match-everywhere}
3987 Obsolete flag.@refill
3988 @item @var{show-files}
3989 Show begin and end of included files.@refill
3990 @end table
3992 Each of these flags can be set to @code{t} or @code{nil}, or to a string
3993 of type letters indicating the label types for which it should be true.
3994 These strings work like character classes in regular expressions.  Thus,
3995 setting one of the flags to @samp{"sf"} makes the flag true for section
3996 and figure labels, @code{nil} for everything else.  Setting it to
3997 @samp{"^sf"} makes it the other way round.@refill
3999 The available label types are: @code{s} (section), @code{f} (figure),
4000 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4001 (footnote), plus any definitions in @code{reftex-label-alist}.@refill
4003 Most options can also be switched from the label menu itself - so if you
4004 decide here to not have a table of contents in the label menu, you can
4005 still get one interactively during selection from the label menu.@refill
4006 @end defopt
4008 @defopt reftex-multiref-punctuation
4009 Punctuation strings for multiple references.  When marking is used in
4010 the selection buffer to select several references, this variable
4011 associates the 3 marking characters @samp{,-+} with prefix strings to be
4012 inserted into the buffer before the corresponding @code{\ref} macro.
4013 This is used to string together whole reference sets, like
4014 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
4015 @code{reftex-reference}.@refill
4016 @end defopt
4018 @defopt reftex-vref-is-default
4019 Non-@code{nil} means, the varioref macro @code{\vref} is used as
4020 default.  In the selection buffer, the @kbd{v} key toggles the reference
4021 macro between @code{\ref} and @code{\vref}.  The value of this variable
4022 determines the default which is active when entering the selection
4023 process.  Instead of @code{nil} or @code{t}, this may also be a string
4024 of type letters indicating the label types for which it should be
4025 true.@refill
4026 @end defopt
4028 @defopt reftex-fref-is-default
4029 Non-@code{nil} means, the fancyref macro @code{\fref} is used as
4030 default.  In the selection buffer, the @kbd{V} key toggles the reference
4031 macro between @code{\ref}, @code{\fref} and @code{\Fref}.  The value of
4032 this variable determines the default which is active when entering the
4033 selection process.  Instead of @code{nil} or @code{t}, this may also be
4034 a string of type letters indicating the label types for which it should
4035 be true.
4036 @end defopt
4038 @deffn Hook reftex-format-ref-function
4039 If non-@code{nil}, should be a function which produces the string to
4040 insert as a reference.  Note that the insertion format can also be
4041 changed with @code{reftex-label-alist}.  This hook also is used by the
4042 special commands to insert @code{\vref} and @code{\fref} references, so
4043 even if you set this, your setting will be ignored by the special
4044 commands.  The function will be called with two arguments, the
4045 @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
4046 It should return the string to insert into the buffer.@refill
4047 @end deffn
4049 @defopt reftex-level-indent
4050 Number of spaces to be used for indentation per section level.@refill
4051 @end defopt
4053 @defopt reftex-guess-label-type
4054 Non-@code{nil} means, @code{reftex-reference} will try to guess the
4055 label type.  To do that, @b{Ref@TeX{}} will look at the word before the
4056 cursor and compare it with the magic words given in
4057 @code{reftex-label-alist}.  When it finds a match, @b{Ref@TeX{}} will
4058 immediately offer the correct label menu - otherwise it will prompt you
4059 for a label type.  If you set this variable to @code{nil}, @b{Ref@TeX{}}
4060 will always prompt for a label type.@refill
4061 @end defopt
4063 @deffn {Normal Hook} reftex-display-copied-context-hook
4064 Normal Hook which is run before context is displayed anywhere.  Designed
4065 for @w{@code{X-Symbol}}, but may have other uses as well.@refill
4066 @end deffn
4068 @deffn Hook reftex-pre-refontification-functions
4069 @code{X-Symbol} specific hook.  Probably not useful for other purposes.
4070 The functions get two arguments, the buffer from where the command
4071 started and a symbol indicating in what context the hook is
4072 called.@refill
4073 @end deffn
4075 @deffn {Normal Hook} reftex-select-label-mode-hook
4076 Normal hook which is run when a selection buffer enters
4077 @code{reftex-select-label-mode}.@refill 
4078 @end deffn
4080 @deffn Keymap reftex-select-label-map
4081 The keymap which is active in the labels selection process
4082 (@pxref{Referencing Labels}).@refill
4083 @end deffn
4085 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
4086 @section Creating Citations
4087 @cindex Options, creating citations
4088 @cindex Creating citations, options
4090 @defopt reftex-bibfile-ignore-regexps
4091 List of regular expressions to exclude files in
4092 @code{\\bibliography@{..@}}.  File names matched by any of these regexps
4093 will not be parsed.  Intended for files which contain only
4094 @code{@@string} macro definitions and the like, which are ignored by
4095 @b{Ref@TeX{}} anyway.@refill
4096 @end defopt
4098 @defopt reftex-default-bibliography
4099 List of BibTeX database files which should be used if none are specified.
4100 When @code{reftex-citation} is called from a document with neither
4101 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4102 environment, @b{Ref@TeX{}} will scan these files instead.  Intended for
4103 using @code{reftex-citation} in non-LaTeX files.  The files will be
4104 searched along the BIBINPUTS or TEXBIB path.@refill
4105 @end defopt
4107 @defopt reftex-sort-bibtex-matches
4108 Sorting of the entries found in BibTeX databases by reftex-citation.
4109 Possible values:@refill
4110 @example
4111 nil          @r{Do not sort entries.}
4112 author       @r{Sort entries by author name.}
4113 year         @r{Sort entries by increasing year.}
4114 reverse-year @r{Sort entries by decreasing year.}
4115 @end example
4116 @end defopt
4118 @defopt reftex-cite-format
4119 The format of citations to be inserted into the buffer.  It can be a
4120 string, an alist or a symbol.  In the simplest case this is just the string
4121 @samp{\cite@{%l@}}, which is also the default.  See the definition of
4122 @code{reftex-cite-format-builtin} for more complex examples.@refill
4124 If @code{reftex-cite-format} is a string, it will be used as the format.
4125 In the format, the following percent escapes will be expanded.@refill
4127 @table @code
4128 @item %l
4129 The BibTeX label of the citation.
4130 @item %a
4131 List of author names, see also @code{reftex-cite-punctuation}.
4132 @item %2a
4133 Like %a, but abbreviate more than 2 authors like Jones et al.
4134 @item %A
4135 First author name only.
4136 @item %e
4137 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4138 @samp{%E} work a well).@refill
4139 @end table
4141 It is also possible to access all other BibTeX database fields:
4143 @example
4144 %b booktitle     %c chapter        %d edition    %h howpublished
4145 %i institution   %j journal        %k key        %m month
4146 %n number        %o organization   %p pages      %P first page
4147 %r address       %s school         %u publisher  %t title
4148 %v volume        %y year
4149 %B booktitle, abbreviated          %T title, abbreviated
4150 @end example
4152 @noindent
4153 Usually, only @samp{%l} is needed.  The other stuff is mainly for the
4154 echo area display, and for @code{(setq reftex-comment-citations t)}.@refill
4156 @samp{%<} as a special operator kills punctuation and space around it
4157 after the string has been formatted.@refill
4159 Beware that all this only works with BibTeX database files.  When
4160 citations are made from the @code{\bibitems} in an explicit
4161 @code{thebibliography} environment, only @samp{%l} is available.@refill
4163 If @code{reftex-cite-format} is an alist of characters and strings, the
4164 user will be prompted for a character to select one of the possible
4165 format strings.@refill
4167 In order to configure this variable, you can either set
4168 @code{reftex-cite-format} directly yourself or set it to the
4169 @emph{symbol} of one of the predefined styles.  The predefined symbols
4170 are those which have an association in the constant
4171 @code{reftex-cite-format-builtin})  E.g.: @code{(setq reftex-cite-format
4172 'natbib)}.@refill
4173 @end defopt
4175 @deffn Hook reftex-format-cite-function
4177 If non-@code{nil}, should be a function which produces the string to
4178 insert as a citation.  Note that the citation format can also be changed
4179 with the variable @code{reftex-cite-format}.  The function will be
4180 called with two arguments, the @var{citation-key} and the
4181 @var{default-format} (taken from @code{reftex-cite-format}).  It should
4182 return the string to insert into the buffer.@refill
4183 @end deffn
4185 @defopt reftex-comment-citations
4186 Non-@code{nil} means add a comment for each citation describing the full
4187 entry.  The comment is formatted according to
4188 @code{reftex-cite-comment-format}.@refill
4189 @end defopt
4191 @defopt reftex-cite-comment-format
4192 Citation format used for commented citations.  Must @emph{not} contain
4193 @samp{%l}.  See the variable @code{reftex-cite-format} for possible
4194 percent escapes.@refill
4195 @end defopt
4197 @defopt reftex-cite-punctuation
4198 Punctuation for formatting of name lists in citations.  This is a list
4199 of 3 strings.@refill
4200 @enumerate
4201 @item
4202 normal names separator, like @samp{, } in Jones, Brown and Miller
4203 @item
4204 final names separator, like @samp{ and }  in Jones, Brown and Miller
4205 @item
4206 The @samp{et al.} string, like @samp{ @{\it et al.@}} in 
4207 Jones @{\it et al.@}
4208 @end enumerate
4209 @end defopt
4211 @deffn {Normal Hook} reftex-select-bib-mode-hook
4212 Normal hook which is run when a selection buffer enters
4213 @code{reftex-select-bib-mode}.@refill 
4214 @end deffn
4216 @deffn Keymap reftex-select-bib-map
4217 The keymap which is active in the citation-key selection process
4218 (@pxref{Creating Citations}).@refill
4219 @end deffn
4221 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations),  Options
4222 @section Index Support
4223 @cindex Options, Index support
4224 @cindex Index support, options
4226 @defopt reftex-support-index
4227 Non-@code{nil} means, index entries are parsed as well.  Index support
4228 is resource intensive and the internal structure holding the parsed
4229 information can become quite big.  Therefore it can be turned off.  When
4230 this is @code{nil} and you execute a command which requires index
4231 support, you will be asked for confirmation to turn it on and rescan the
4232 document.@refill
4233 @end defopt
4235 @defopt reftex-index-special-chars
4236 List of special characters in index entries, given as strings.  These
4237 correspond to the @code{MakeIndex} keywords 
4238 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4239 @end defopt
4241 @defopt reftex-index-macros
4242 List of macros which define index entries.  The structure of each entry
4244 @lisp
4245 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4246 @end lisp
4248 @var{macro} is the macro.  Arguments should be denoted by empty braces,
4249 as for example in @samp{\index[]@{*@}}.  Use square brackets to denote
4250 optional arguments.  The star marks where the index key is.@refill
4252 @var{index-tag} is a short name of the index.  @samp{idx} and @samp{glo}
4253 are reserved for the default index and the glossary.  Other indices can
4254 be defined as well.  If this is an integer, the Nth argument of the
4255 macro holds the index tag.@refill
4257 @var{key} is a character which is used to identify the macro for input
4258 with @code{reftex-index}.  @samp{?i}, @samp{?I}, and @samp{?g} are
4259 reserved for default index and glossary.@refill
4261 @var{prefix} can be a prefix which is added to the @var{key} part of the
4262 index entry.  If you have a macro
4263 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4264 should be @samp{Molecules!}.@refill
4266 @var{exclude} can be a function.  If this function exists and returns a
4267 non-nil value, the index entry at point is ignored.  This was
4268 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4269 in the LaTeX2e @code{index} package.@refill
4271 @var{repeat}, if non-@code{nil}, means the index macro does not typeset
4272 the entry in the text, so that the text has to be repeated outside the
4273 index macro.  Needed for @code{reftex-index-selection-or-word} and for
4274 indexing from the phrase buffer.@refill
4276 The final entry may also be a symbol.  It must have an association in
4277 the variable @code{reftex-index-macros-builtin} to specify the main
4278 indexing package you are using.  Legal values are currently@refill
4279 @example
4280 default         @r{The LaTeX default - unnecessary to specify this one}
4281 multind         @r{The multind.sty package}
4282 index           @r{The index.sty package}
4283 index-shortcut  @r{The index.sty packages with the ^ and _ shortcuts.}
4284                 @r{Should not be used - only for old documents}
4285 @end example
4286 Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
4287 so with a sufficiently new version of AUCTeX, you should not set the
4288 package here.
4289 @end defopt
4291 @defopt reftex-index-default-macro
4292 The default index macro for @code{reftex-index-selection-or-word}.
4293 This is a list with @code{(@var{macro-key} @var{default-tag})}.
4295 @var{macro-key} is a character identifying an index macro - see
4296 @code{reftex-index-macros}.
4298 @var{default-tag} is the tag to be used if the macro requires a
4299 @var{tag} argument.  When this is @code{nil} and a @var{tag} is needed,
4300 @b{Ref@TeX{}} will ask for it.  When this is the empty string and the
4301 TAG argument of the index macro is optional, the TAG argument will be
4302 omitted.@refill
4303 @end defopt
4305 @defopt reftex-index-default-tag
4306 Default index tag.  When working with multiple indexes, RefTeX queries
4307 for an index tag when creating index entries or displaying a specific
4308 index.  This variable controls the default offered for these queries.
4309 The default can be selected with @key{RET} during selection or
4310 completion.  Legal values of this variable are:@refill
4311 @example
4312 nil        @r{Do not provide a default index}
4313 "tag"      @r{The default index tag given as a string, e.g. "idx"}
4314 last       @r{The last used index tag will be offered as default}
4315 @end example
4316 @end defopt
4318 @defopt reftex-index-math-format
4319 Format of index entries when copied from inside math mode.  When
4320 @code{reftex-index-selection-or-word} is executed inside TeX math mode,
4321 the index key copied from the buffer is processed with this format
4322 string through the @code{format} function.  This can be used to add the
4323 math delimiters (e.g. @samp{$}) to the string.  Requires the
4324 @file{texmathp.el} library which is part of AUCTeX.@refill
4325 @end defopt
4327 @defopt reftex-index-phrase-file-extension
4328 File extension for the index phrase file.  This extension will be added
4329 to the base name of the master file.
4330 @end defopt
4332 @defopt reftex-index-phrases-logical-and-regexp
4333 Regexp matching the @samp{and} operator for index arguments in phrases
4334 file.  When several index arguments in a phrase line are separated by
4335 this operator, each part will generate an index macro.  So each match of
4336 the search phrase will produce @emph{several} different index entries.
4337 Make sure this does no match things which are not separators.  This
4338 logical @samp{and} has higher priority than the logical @samp{or}
4339 specified in @code{reftex-index-phrases-logical-or-regexp}.@refill
4340 @end defopt
4342 @defopt reftex-index-phrases-logical-or-regexp
4343 Regexp matching the @samp{or} operator for index arguments in phrases
4344 file.  When several index arguments in a phrase line are separated by
4345 this operator, the user will be asked to select one of them at each
4346 match of the search phrase.  The first index arg will be the default.  A
4347 number key @kbd{1}--@kbd{9} must be pressed to switch to another.  Make
4348 sure this does no match things which are not separators.  The logical
4349 @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4350 has higher priority than this logical @samp{or}.@refill
4351 @end defopt
4353 @defopt reftex-index-phrases-search-whole-words
4354 Non-@code{nil} means phrases search will look for whole words, not subwords.
4355 This works by requiring word boundaries at the beginning and end of
4356 the search string.  When the search phrase already has a non-word-char
4357 at one of these points, no word boundary is required there.
4358 @end defopt
4360 @defopt reftex-index-phrases-case-fold-search
4361 Non-@code{nil} means, searching for index phrases will ignore
4362 case.@refill
4363 @end defopt
4365 @defopt reftex-index-phrases-skip-indexed-matches
4366 Non-@code{nil} means, skip matches which appear to be indexed already.
4367 When doing global indexing from the phrases buffer, searches for some
4368 phrases may match at places where that phrase was already indexed.  In
4369 particular when indexing an already processed document again, this
4370 will even be the norm.  When this variable is non-@code{nil},
4371 @b{Ref@TeX{}} checks if the match is an index macro argument, or if an
4372 index macro is directly before or after the phrase.  If that is the
4373 case, that match will be ignored.@refill
4374 @end defopt
4376 @defopt reftex-index-phrases-wrap-long-lines
4377 Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
4378 Inserting indexing commands in a line makes the line longer - often
4379 so long that it does not fit onto the screen.  When this variable is
4380 non-@code{nil}, newlines will be added as necessary before and/or after the
4381 indexing command to keep lines short.  However, the matched text
4382 phrase and its index command will always end up on a single line.@refill
4383 @end defopt
4385 @defopt reftex-index-phrases-sort-prefers-entry
4386 Non-@code{nil} means when sorting phrase lines, the explicit index entry
4387 is used. Phrase lines in the phrases buffer contain a search phrase, and
4388 sorting is normally based on these.  Some phrase lines also have
4389 an explicit index argument specified.  When this variable is
4390 non-@code{nil}, the index argument will be used for sorting.@refill
4391 @end defopt
4393 @defopt reftex-index-phrases-sort-in-blocks
4394 Non-@code{nil} means, empty and comment lines separate phrase buffer
4395 into blocks.  Sorting will then preserve blocks, so that lines are
4396 re-arranged only within blocks.
4397 @end defopt
4399 @defopt reftex-index-phrases-map
4400 Keymap for the Index Phrases buffer.
4401 @end defopt
4403 @defopt reftex-index-phrases-mode-hook
4404 Normal hook which is run when a buffer is put into
4405 @code{reftex-index-phrases-mode}.@refill
4406 @end defopt
4408 @defopt reftex-index-section-letters
4409 The letters which denote sections in the index.  Usually these are all
4410 capital letters.  Don't use any downcase letters.  Order is not
4411 significant, the index will be sorted by whatever the sort function
4412 thinks is correct.  In addition to these letters, @b{Ref@TeX{}} will
4413 create a group @samp{!} which contains all entries sorted below the
4414 lowest specified letter.  In the @file{*Index*} buffer, pressing any of
4415 these capital letters or @kbd{!} will jump to that section.@refill
4416 @end defopt
4418 @defopt reftex-index-include-context
4419 Non-@code{nil} means, display the index definition context in the
4420 @file{*Index*} buffer.  This flag may also be toggled from the
4421 @file{*Index*} buffer with the @kbd{c} key.
4422 @end defopt
4424 @defopt reftex-index-follow-mode
4425 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4426 window to follow.  The other window will show the corresponding part of
4427 the document.  This flag can be toggled from within the @file{*Index*}
4428 buffer with the @kbd{f} key.
4429 @end defopt
4431 @deffn Keymap reftex-index-map
4432 The keymap which is active in the @file{*Index*} buffer
4433 (@pxref{Index Support}).@refill
4434 @end deffn
4436 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support),  Options
4437 @section Viewing Cross-References
4438 @cindex Options, viewing cross-references
4439 @cindex Viewing cross-references, options
4441 @defopt reftex-view-crossref-extra
4442 Macros which can be used for the display of cross references.
4443 This is used when `reftex-view-crossref' is called with point in an
4444 argument of a macro.  Note that crossref viewing for citations,
4445 references (both ways) and index entries is hard-coded.  This variable
4446 is only to configure additional structures for which crossreference
4447 viewing can be useful.  Each entry has the structure 
4448 @example
4449 (@var{macro-re} @var{search-re} @var{highlight}).
4450 @end example
4451 @var{macro-re} is matched against the macro.  @var{search-re} is the
4452 regexp used to search for cross references.  @samp{%s} in this regexp is
4453 replaced with with the macro argument at point.  @var{highlight} is an
4454 integer indicating which subgroup of the match should be highlighted.
4455 @end defopt
4457 @defopt reftex-auto-view-crossref
4458 Non-@code{nil} means, initially turn automatic viewing of crossref info
4459 on.  Automatic viewing of crossref info normally uses the echo area.
4460 Whenever point is on the argument of a @code{\ref} or @code{\cite}
4461 macro, and no other message is being displayed, the echo area will
4462 display information about that cross reference.  You can also set the
4463 variable to the symbol @code{window}.  In this case a small temporary
4464 window is used for the display.  This feature can be turned on and of
4465 from the menu (Ref->Options).@refill
4466 @end defopt
4468 @defopt reftex-idle-time
4469 Time (secs) Emacs has to be idle before automatic crossref display is
4470 done.@refill
4471 @end defopt
4473 @defopt reftex-cite-view-format
4474 Citation format used to display citation info in the message area.  See
4475 the variable @code{reftex-cite-format} for possible percent
4476 escapes.@refill
4477 @end defopt
4479 @defopt reftex-revisit-to-echo
4480 Non-@code{nil} means, automatic citation display will revisit files if
4481 necessary.  When nil, citation display in echo area will only be active
4482 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4483 BibTeX database files which are already visited by a live associated
4484 buffers.@refill
4485 @end defopt
4487 @defopt reftex-cache-cite-echo
4488 Non-@code{nil} means, the information displayed in the echo area for
4489 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4490 saved along with the parsing information.  The cache survives document
4491 scans.  In order to clear it, use @kbd{M-x reftex-reset-mode}.
4492 @end defopt
4494 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References),  Options
4495 @section Finding Files
4496 @cindex Options, Finding Files
4497 @cindex Finding files, options
4499 @defopt reftex-texpath-environment-variables
4500 List of specifications how to retrieve the search path for TeX files.
4501 Several entries are possible.@refill
4502 @itemize @minus
4503 @item
4504 If an element is the name of an environment variable, its content is
4505 used.@refill
4506 @item
4507 If an element starts with an exclamation mark, it is used as a command
4508 to retrieve the path.  A typical command with the kpathsearch library
4509 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4510 @item
4511 Otherwise the element itself is interpreted as a path.
4512 @end itemize
4513 Multiple directories can be separated by the system dependent
4514 @code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
4515 be expanded recursively.  See also @code{reftex-use-external-file-finders}.
4516 @end defopt
4518 @defopt reftex-bibpath-environment-variables
4519 List of specifications how to retrieve the search path for BibTeX
4520 files.  Several entries are possible.@refill
4521 @itemize @minus
4522 @item
4523 If an element is the name of an environment variable, its content is
4524 used.@refill
4525 @item
4526 If an element starts with an exclamation mark, it is used as a command
4527 to retrieve the path.  A typical command with the kpathsearch library
4528 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4529 @item
4530 Otherwise the element itself is interpreted as a path.
4531 @end itemize
4532 Multiple directories can be separated by the system dependent
4533 @code{path-separator}.  Directories ending in @samp{//} or @samp{!!} will
4534 be expanded recursively.  See also @code{reftex-use-external-file-finders}.
4535 @end defopt
4537 @defopt reftex-file-extensions
4538 Association list with file extensions for different file types.
4539 This is a list of items, each item is like: 
4540 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4541 @example
4542 @var{type}:       @r{File type like @code{"bib"} or @code{"tex"}.}
4543 @var{def-ext}:    @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
4544 @var{other-ext}:  @r{Any number of other legal extensions for this file type.}
4545 @end example
4546 When a files is searched and it does not have any of the legal extensions,
4547 we try the default extension first, and then the naked file name.@refill
4548 @end defopt
4550 @defopt reftex-search-unrecursed-path-first
4551 Non-@code{nil} means, search all specified directories before trying
4552 recursion.  Thus, in a path @samp{.//:/tex/}, search first @samp{./},
4553 then @samp{/tex/}, and then all subdirectories of @samp{./}.  If this
4554 option is @code{nil}, the subdirectories of @samp{./} are searched
4555 before @samp{/tex/}.  This is mainly for speed - most of the time the
4556 recursive path is for the system files and not for the user files.  Set
4557 this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
4558 equal names in wrong sequence.@refill
4559 @end defopt
4561 @defopt reftex-use-external-file-finders
4562 Non-@code{nil} means, use external programs to find files.  Normally,
4563 @b{Ref@TeX{}} searches the paths given in the environment variables
4564 @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
4565 database files.  With this option turned on, it calls an external
4566 program specified in the option @code{reftex-external-file-finders}
4567 instead.  As a side effect, the variables
4568 @code{reftex-texpath-environment-variables} and
4569 @code{reftex-bibpath-environment-variables} will be ignored.
4570 @end defopt
4572 @defopt reftex-external-file-finders
4573 Association list with external programs to call for finding files.  Each
4574 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
4575 @var{type} is either @code{"tex"} or @code{"bib"}.  @var{program} is a
4576 string containing the external program to use with any arguments.
4577 @code{%f} will be replaced by the name of the file to be found.  Note
4578 that these commands will be executed directly, not via a shell.  Only
4579 relevant when @code{reftex-use-external-file-finders} is
4580 non-@code{nil}.@refill
4581 @end defopt
4583 @page
4584 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
4585 @section Optimizations
4586 @cindex Options, optimizations
4587 @cindex Optimizations, options
4589 @defopt reftex-keep-temporary-buffers
4590 Non-@code{nil} means, keep buffers created for parsing and lookup.
4591 @b{Ref@TeX{}} sometimes needs to visit files related to the current
4592 document.  We distinguish files visited for@refill
4593 @table @asis
4594 @item PARSING
4595 Parts of a multifile document loaded when (re)-parsing the
4596 document.@refill
4597 @item LOOKUP
4598 BibTeX database files and TeX files loaded to find a reference, to
4599 display label context, etc.@refill
4600 @end table
4601 The created buffers can be kept for later use, or be thrown away
4602 immediately after use, depending on the value of this variable:@refill
4604 @table @code
4605 @item nil
4606 Throw away as much as possible.
4607 @item t
4608 Keep everything.
4609 @item 1
4610 Throw away buffers created for parsing, but keep the ones created for
4611 lookup.@refill
4612 @end table
4614 If a buffer is to be kept, the file is visited normally (which is
4615 potentially slow but will happen only once). If a buffer is to be thrown
4616 away, the initialization of the buffer depends upon the variable
4617 @code{reftex-initialize-temporary-buffers}.@refill
4618 @end defopt
4620 @defopt reftex-initialize-temporary-buffers
4621 Non-@code{nil} means do initializations even when visiting file
4622 temporarily.  When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
4623 other stuff to briefly visit a file. When @code{t}, the full default
4624 initializations are done (@code{find-file-hook} etc.).  Instead of
4625 @code{t} or @code{nil}, this variable may also be a list of hook
4626 functions to do a minimal initialization.@refill
4627 @end defopt
4629 @defopt reftex-no-include-regexps
4630 List of regular expressions to exclude certain input files from parsing.
4631 If the name of a file included via @code{\include} or @code{\input} is
4632 matched by any of the regular expressions in this list, that file is not
4633 parsed by @b{Ref@TeX{}}.
4634 @end defopt
4636 @defopt reftex-enable-partial-scans
4637 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4638 Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
4639 commands, or with the @kbd{r} key in menus.  When this option is
4640 @code{t} in a multifile document, we will only parse the current buffer,
4641 or the file associated with the label or section heading near point in a
4642 menu.  Requesting re-parsing of an entire multifile document then
4643 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
4644 menus.@refill
4645 @end defopt
4647 @defopt reftex-save-parse-info
4648 Non-@code{nil} means, save information gathered with parsing in files.
4649 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
4650 used to save the information.  When this variable is @code{t},
4651 @itemize @minus
4652 @item
4653 accessing the parsing information for the first time in an editing
4654 session will read that file (if available) instead of parsing the
4655 document.@refill
4656 @item
4657 exiting Emacs or killing a buffer in reftex-mode will cause a new
4658 version of the file to be written.@refill
4659 @end itemize
4660 @end defopt
4662 @defopt reftex-parse-file-extension
4663 File extension for the file in which parser information is stored.
4664 This extension is added to the base name of the master file.
4665 @end defopt
4667 @defopt reftex-allow-automatic-rescan
4668 Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
4669 necessary.  Applies (currently) only in rare cases, when a new label
4670 cannot be placed with certainty into the internal label list.
4671 @end defopt
4673 @defopt reftex-use-multiple-selection-buffers
4674 Non-@code{nil} means use a separate selection buffer for each label
4675 type.  These buffers are kept from one selection to the next and need
4676 not to be created for each use - so the menu generally comes up faster.
4677 The selection buffers will be erased (and therefore updated)
4678 automatically when new labels in its category are added.  See the
4679 variable @code{reftex-auto-update-selection-buffers}.@refill
4680 @end defopt
4682 @defopt reftex-auto-update-selection-buffers
4683 Non-@code{nil} means, selection buffers will be updated automatically.
4684 When a new label is defined with @code{reftex-label}, all selection
4685 buffers associated with that label category are emptied, in order to
4686 force an update upon next use.  When @code{nil}, the buffers are left
4687 alone and have to be updated by hand, with the @kbd{g} key from the
4688 label selection process.  The value of this variable will only have any
4689 effect when @code{reftex-use-multiple-selection-buffers} is
4690 non-@code{nil}.@refill
4691 @end defopt
4693 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
4694 @section Fontification
4695 @cindex Options, fontification
4696 @cindex Fontification, options
4698 @defopt reftex-use-fonts
4699 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
4700 Font-lock must be loaded as well to actually get fontified
4701 display.  After changing this option, a rescan may be necessary to
4702 activate it.@refill
4703 @end defopt
4705 @defopt reftex-refontify-context
4706 Non-@code{nil} means, re-fontify the context in the label menu with
4707 font-lock.  This slightly slows down the creation of the label menu.  It
4708 is only necessary when you definitely want the context fontified.@refill
4710 This option may have 3 different values:
4711 @table @code
4712 @item nil
4713 Never refontify.
4714 @item t
4715 Always refontify.
4716 @item 1
4717 Refontify when necessary, e.g. with old versions of the x-symbol
4718 package.@refill
4719 @end table
4720 The option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill
4721 @end defopt
4723 @defopt reftex-highlight-selection
4724 Non-@code{nil} means, highlight selected text in selection and
4725 @file{*toc*} buffers.  Normally, the text near the cursor is the
4726 @emph{selected} text, and it is highlighted.  This is the entry most
4727 keys in the selection and @file{*toc*} buffers act on.  However, if you
4728 mainly use the mouse to select an item, you may find it nice to have
4729 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
4730 variable may have one of these values:@refill
4732 @example
4733 nil      @r{No highlighting.}
4734 cursor   @r{Highlighting is cursor driven.}
4735 mouse    @r{Highlighting is mouse driven.}
4736 both     @r{Both cursor and mouse trigger highlighting.}
4737 @end example
4739 Changing this variable requires to rebuild the selection and *toc*
4740 buffers to become effective (keys @kbd{g} or @kbd{r}).@refill
4741 @end defopt
4743 @defopt reftex-cursor-selected-face
4744 Face name to highlight cursor selected item in toc and selection buffers.
4745 See also the variable @code{reftex-highlight-selection}.@refill
4746 @end defopt
4747 @defopt reftex-mouse-selected-face
4748 Face name to highlight mouse selected item in toc and selection buffers.
4749 See also the variable @code{reftex-highlight-selection}.@refill
4750 @end defopt
4751 @defopt reftex-file-boundary-face
4752 Face name for file boundaries in selection buffer.
4753 @end defopt
4754 @defopt reftex-label-face
4755 Face name for labels in selection buffer.
4756 @end defopt
4757 @defopt reftex-section-heading-face
4758 Face name for section headings in toc and selection buffers.
4759 @end defopt
4760 @defopt reftex-toc-header-face
4761 Face name for the header of a toc buffer.
4762 @end defopt
4763 @defopt reftex-bib-author-face
4764 Face name for author names in bib selection buffer.
4765 @end defopt
4766 @defopt reftex-bib-year-face
4767 Face name for year in bib selection buffer.
4768 @end defopt
4769 @defopt reftex-bib-title-face
4770 Face name for article title in bib selection buffer.
4771 @end defopt
4772 @defopt reftex-bib-extra-face
4773 Face name for bibliographic information in bib selection buffer.
4774 @end defopt
4775 @defopt reftex-select-mark-face
4776 Face name for marked entries in the selection buffers.
4777 @end defopt
4778 @defopt reftex-index-header-face
4779 Face name for the header of an index buffer.
4780 @end defopt
4781 @defopt reftex-index-section-face
4782 Face name for the start of a new letter section in the index.
4783 @end defopt
4784 @defopt reftex-index-tag-face
4785 Face name for index names (for multiple indices).
4786 @end defopt
4787 @defopt reftex-index-face
4788 Face name for index entries.
4789 @end defopt
4791 @node Options (Misc), , Options (Fontification), Options
4792 @section Miscellaneous
4793 @cindex Options, misc
4795 @defopt reftex-extra-bindings
4796 Non-@code{nil} means, make additional key bindings on startup.  These
4797 extra bindings are located in the users @samp{C-c letter}
4798 map. @xref{Keybindings}.@refill
4799 @end defopt
4801 @defopt reftex-plug-into-AUCTeX
4802 Plug-in flags for AUCTeX interface.  This variable is a list of
4803 5 boolean flags.  When a flag is non-@code{nil}, @b{Ref@TeX{}}
4804 will@refill
4806 @example
4807 - supply labels in new sections and environments  (flag 1)
4808 - supply arguments for macros like @code{\label}         (flag 2)
4809 - supply arguments for macros like @code{\ref}           (flag 3)
4810 - supply arguments for macros like @code{\cite}          (flag 4)
4811 - supply arguments for macros like @code{\index}         (flag 5)
4812 @end example
4814 You may also set the variable itself to t or nil in order to turn all
4815 options on or off, respectively.@*
4816 Supplying labels in new sections and environments applies when creating
4817 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
4818 Supplying macro arguments applies when you insert such a macro
4819 interactively with @kbd{C-c @key{RET}}.@*
4820 See the AUCTeX documentation for more information.
4821 @end defopt
4823 @defopt reftex-revisit-to-follow
4824 Non-@code{nil} means, follow-mode will revisit files if necessary.
4825 When nil, follow-mode will be suspended for stuff in unvisited files.
4826 @end defopt
4828 @defopt reftex-allow-detached-macro-args
4829 Non-@code{nil} means, allow arguments of macros to be detached by
4830 whitespace.  When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
4831 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}.  Note that
4832 this will be the case even if @code{\bb} is defined with zero or one
4833 argument.@refill
4834 @end defopt
4836 @node Keymaps and Hooks, Changes, Options, Top
4837 @section Keymaps and Hooks
4838 @cindex Keymaps
4840 @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
4842 @deffn Keymap reftex-mode-map
4843 The keymap for @b{Ref@TeX{}} mode.
4844 @end deffn
4846 @deffn {Normal Hook} reftex-load-hook
4847 Normal hook which is being run when loading @file{reftex.el}.
4848 @end deffn
4850 @deffn {Normal Hook} reftex-mode-hook
4851 Normal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill
4852 @end deffn
4854 Furthermore, the 4 modes used for referencing labels, creating
4855 citations, the table of contents buffer and the phrases buffer have
4856 their own keymaps and mode hooks.  See the respective sections.  There
4857 are many more hooks which are described in the relevant sections about
4858 options for a specific part of @b{Ref@TeX{}}.@refill
4860 @node Changes, , Keymaps and Hooks, Top
4861 @chapter Changes
4862 @cindex Changes
4864 Here is a list of recent changes to @b{Ref@TeX{}}.
4866 @ignore
4867 @noindent @b{Version 1.00}
4868 @itemize @bullet
4869 @item
4870 released on 7 Jan 1997.
4871 @end itemize
4873 @noindent @b{Version 1.04}
4874 @itemize @bullet
4875 @item
4876 Macros as wrappers, AMSTeX support, delayed context parsing for
4877 new labels.@refill
4878 @end itemize
4880 @noindent @b{Version 1.05}
4881 @itemize @bullet
4882 @item
4883 XEmacs port.
4884 @end itemize
4886 @noindent @b{Version 1.07}
4887 @itemize @bullet
4888 @item
4889 @b{Ref@TeX{}} gets its own menu.
4890 @end itemize
4892 @noindent @b{Version 1.09}
4893 @itemize @bullet
4894 @item
4895 Support for @code{tex-main-file}, an analogue for
4896 @code{TeX-master}.@refill
4897 @item
4898 MS-DOS support.
4899 @end itemize
4901 @noindent @b{Version 2.00}
4902 @itemize @bullet
4903 @item
4904 Labels can be derived from context (default for sections).
4905 @item
4906 Configuration of label insertion and label referencing revised.
4907 @item
4908 Crossref fields in BibTeX database entries.
4909 @item
4910 @code{reftex-toc} introduced (thanks to Stephen Eglen).
4911 @end itemize
4913 @noindent @b{Version 2.03}
4914 @itemize @bullet
4915 @item
4916 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
4917 default environments.@refill
4918 @item
4919 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
4920 @item
4921 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
4922 @code{reftex-arg-cite}.@refill
4923 @item
4924 Emacs/XEmacs compatibility reworked.  XEmacs 19.15 now is
4925 required.@refill
4926 @item
4927 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
4928 files).@refill
4929 @item
4930 Finding context with a hook function.
4931 @item
4932 Sorting BibTeX entries (new variable:
4933 @code{reftex-sort-bibtex-matches}).
4934 @end itemize
4936 @noindent @b{Version 2.05}
4937 @itemize @bullet
4938 @item
4939 Support for @file{custom.el}.
4940 @item
4941 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
4942 @end itemize
4944 @noindent @b{Version 2.07}
4945 @itemize @bullet
4946 @item
4947 New functions @code{reftex-search-document},
4948 @code{reftex-query-replace-document}.
4949 @end itemize
4951 @noindent @b{Version 2.11}
4952 @itemize @bullet
4953 @item
4954 Submitted for inclusion to Emacs and XEmacs.
4955 @end itemize
4957 @noindent @b{Version 2.14}
4958 @itemize @bullet
4959 @item
4960 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
4961 AUCTeX.@refill
4962 @end itemize
4964 @noindent @b{Version 2.17}
4965 @itemize @bullet
4966 @item
4967 Label prefix expands % escapes with current file name and other stuff.
4968 @item
4969 Citation format now with % escapes.  This is not backward
4970 compatible!@refill
4971 @item
4972 TEXINPUTS variable recognized when looking for input files.
4973 @item
4974 Context can be the nth argument of a macro.@refill
4975 @item
4976 Searching in the select buffer is now possible (@kbd{C-s} and
4977 @kbd{C-r}).@refill
4978 @item
4979 Display and derive-label can use two different context methods.
4980 @item
4981 AMSmath @code{xalignat} and @code{xxalignat} added.
4982 @end itemize
4984 @noindent @b{Version 3.00}
4985 @itemize @bullet
4986 @item
4987 @b{Ref@TeX{}} should work better for very large projects:
4988 @item
4989 The new parser works without creating a master buffer.
4990 @item
4991 Rescanning can be limited to a part of a multifile document.
4992 @item
4993 Information from the parser can be stored in a file.
4994 @item
4995 @b{Ref@TeX{}} can deal with macros having a naked label as an argument.
4996 @item
4997 Macros may have white space and newlines between arguments.
4998 @item
4999 Multiple identical section headings no longer confuse
5000 @code{reftex-toc}.@refill
5001 @item
5002 @b{Ref@TeX{}} should work correctly in combination with buffer-altering
5003 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill
5004 @item
5005 All labeled environments discussed in @emph{The LaTeX Companion} by
5006 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
5007 @b{Ref@TeX{}}'s defaults.@refill
5008 @end itemize
5010 @noindent @b{Version 3.03}
5011 @itemize @bullet
5012 @item
5013 Support for the LaTeX package @code{xr}, for inter-document
5014 references.@refill
5015 @item
5016 A few (minor) Mule-related changes.
5017 @item
5018 Fixed bug which could cause @emph{huge} @file{.rel} files.
5019 @item
5020 Search for input and @file{.bib} files with recursive path definitions.
5021 @end itemize
5023 @noindent @b{Version 3.04}
5024 @itemize @bullet
5025 @item
5026 Fixed BUG in the @emph{xr} support.
5027 @end itemize
5029 @noindent @b{Version 3.05}
5030 @itemize @bullet
5031 @item
5032 Compatibility code now first checks for XEmacs feature.
5033 @end itemize
5035 @noindent @b{Version 3.07}
5036 @itemize @bullet
5037 @item
5038 @code{Ref} menu improved.
5039 @end itemize
5041 @noindent @b{Version 3.10}
5042 @itemize @bullet
5043 @item
5044 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5045 @item
5046 Removed unimportant code which caused OS/2 Emacs to crash.
5047 @item
5048 All customization variables now accessible from menu.
5049 @end itemize
5051 @noindent @b{Version 3.11}
5052 @itemize @bullet
5053 @item
5054 Fixed bug which led to naked label in (e.g.) footnotes.
5055 @item
5056 Added scroll-other-window functions to RefTeX-Select.
5057 @end itemize
5059 @noindent @b{Version 3.12}
5060 @itemize @bullet
5061 @item
5062 There are 3 new keymaps for customization: @code{reftex-toc-map},
5063 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5064 @item
5065 Refontification uses more standard font-lock stuff.
5066 @item
5067 When no BibTeX database files are specified, citations can also use
5068 @code{\bibitem} entries from a @code{thebibliography} environment.@refill
5069 @end itemize
5071 @noindent @b{Version 3.14}
5072 @itemize @bullet
5073 @item
5074 Selection buffers can be kept between selections: this is faster.
5075 See new variable @code{reftex-use-multiple-selection-buffers}.@refill
5076 @item
5077 Prefix interpretation of reftex-view-crossref changed.
5078 @item
5079 Support for the @code{varioref} package (@kbd{v} key in selection
5080 buffer).@refill
5081 @end itemize
5083 @noindent @b{Version 3.16}
5084 @itemize @bullet
5085 @item
5086 New hooks @code{reftex-format-label-function},
5087 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill
5088 @item
5089 TeXInfo documentation completed.
5090 @item
5091 Some restrictions in Label inserting and referencing removed.
5092 @item
5093 New variable @code{reftex-default-bibliography}.
5094 @end itemize
5096 @noindent @b{Version 3.17}
5097 @itemize @bullet
5098 @item
5099 Additional bindings in selection and @file{*toc*} buffers.  @kbd{g}
5100 redefined.
5101 @item
5102 New command @code{reftex-save-all-document-buffers}.
5103 @item
5104 Magic word matching made more intelligent.
5105 @item
5106 Selection process can switch to completion (with @key{TAB}).
5107 @item
5108 @code{\appendix} is now recognized and influences section numbering.
5109 @item
5110 File commentary shortened considerably (use Info documentation).
5111 @item
5112 New option @code{reftex-no-include-regexps} to skip some include files.
5113 @item
5114 New option @code{reftex-revisit-to-follow}.
5115 @end itemize
5117 @noindent @b{Version 3.18}
5118 @itemize @bullet
5119 @item
5120 The selection now uses a recursive edit, much like minibuffer input.
5121 This removes all restrictions during selection.  E.g. you can now
5122 switch buffers at will, use the mouse etc.@refill
5123 @item
5124 New option @code{reftex-highlight-selection}.
5125 @item
5126 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
5127 buffers.@refill
5128 @item
5129 Fixed some problems regarding the interaction with VIPER mode.
5130 @item
5131 Follow-mode is now only used after point motion.
5132 @item
5133 @b{Ref@TeX{}} now finally does not fontify temporary files anymore.
5134 @end itemize
5136 @noindent @b{Version 3.19}
5137 @itemize @bullet
5138 @item
5139 Fixed bug with AUCTeX @code{TeX-master}.
5140 @end itemize
5142 @noindent @b{Version 3.21}
5143 @itemize @bullet
5144 @item
5145 New options for all faces used by @b{Ref@TeX{}}. They're in the
5146 customization group @code{reftex-fontification-configurations}.@refill
5147 @end itemize
5149 @noindent @b{Version 3.22}
5150 @itemize @bullet
5151 @item
5152 Fixed bug with empty context strings.
5153 @item
5154 @code{reftex-mouse-view-crossref} is now bound by default at
5155 @kbd{S-mouse-2}.@refill
5156 @end itemize
5158 @noindent @b{Version 3.23}
5159 @itemize @bullet
5160 @item
5161 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5162 @item
5163 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse 
5164 file.
5165 @item
5166 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5167 automatic display of crossref information in the echo area.  See
5168 variable @code{reftex-auto-view-crossref}.
5169 @item
5170 AUCTeX interface updates:
5171 @itemize @minus
5172 @item
5173 AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
5174 @item
5175 @b{Ref@TeX{}} notifies AUCTeX about new labels.
5176 @item
5177 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
5178 @item
5179 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5180 @item
5181 Settings added to @b{Ref@TeX{}} via style files remain local.
5182 @end itemize
5183 @item
5184 Fixed bug with @code{reftex-citation} in non-latex buffers.
5185 @item
5186 Fixed bug with syntax table and context refontification.
5187 @item
5188 Safety-net for name change of @code{font-lock-reference-face}.
5189 @end itemize
5191 @noindent @b{Version 3.24}
5192 @itemize @bullet
5193 @item
5194 New option @code{reftex-revisit-to-echo}.
5195 @item
5196 Interface with X-Symbol (>=2.6) is now complete and stable.
5197 @item
5198 Adapted to new outline, which uses overlays.
5199 @item
5200 File names in @code{\bibliography} may now have the @code{.bib}
5201 extension.@refill
5202 @item
5203 Fixed Bug with parsing "single file" from master file buffer.
5204 @end itemize
5206 @noindent @b{Version 3.25}
5207 @itemize @bullet
5208 @item
5209 Echoing of citation info caches the info for displayed entries.
5210 New option @code{reftex-cache-cite-echo}.@refill
5211 @item
5212 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
5213 info.@refill
5214 @item
5215 Default of @code{reftex-revisit-to-follow} changed to nil.
5216 @end itemize
5218 @noindent @b{Version 3.26}
5219 @itemize @bullet
5220 @item
5221 [X]Emacs 19 no longer supported.  Use 3.22 for Emacs 19.
5222 @item
5223 New hooks @code{reftex-translate-to-ascii-function},
5224 @code{reftex-string-to-label-function}.@refill
5225 @item
5226 Made sure automatic crossref display will not visit/scan files.
5227 @end itemize
5229 @noindent @b{Version 3.27}
5230 @itemize @bullet
5231 @item
5232 Macros can define @emph{neutral} labels, just like @code{\label}
5233 itself.@refill
5234 @item
5235 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5236 @end itemize
5238 @noindent @b{Version 3.28}
5239 @itemize @bullet
5240 @item
5241 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5242 timer, since itimer restart is not reliable.@refill
5243 @item
5244 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5245 @item
5246 Expansion of recursive tex and bib path rewritten.
5247 @item
5248 Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
5249 @item
5250 Fixed bug with section numbering after *-red sections.
5251 @end itemize
5253 @noindent @b{Version 3.30}
5254 @itemize @bullet
5255 @item
5256 In @code{reftex-citation}, the regular expression used to scan BibTeX
5257 files can be specified using completion on known citation keys.
5258 @item
5259 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5260 entries.
5261 @item
5262 New command @code{reftex-renumber-simple-labels} to renumber simple
5263 labels like @samp{eq:13} sequentially through a document.
5264 @end itemize
5265 @noindent @b{Version 3.33}
5266 @itemize @bullet
5267 @item
5268 Multiple selection buffers are now hidden buffers (they start with a
5269 SPACE).
5270 @item 
5271 Fixed bug with file search when TEXINPUTS environment variable is empty.
5272 @end itemize
5273 @noindent @b{Version 3.34}
5274 @itemize @bullet
5275 @item
5276 Additional flag in @code{reftex-derive-label-parameters} do make only
5277 lowercase labels (default @code{t}).
5278 @item
5279 All @file{.rel} files have a final newline to avoid queries.
5280 @item
5281 Single byte representations of accented European letters (ISO-8859-1)
5282 are now legal in labels.
5283 @end itemize
5284 @noindent @b{Version 3.35}
5285 @itemize @bullet
5286 @item
5287 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5288 This takes back the related changes in 3.34 for safety reasons.@refill
5289 @end itemize
5290 @noindent @b{Version 3.36}
5291 @itemize @bullet
5292 @item
5293 New value @code{window} for option @code{reftex-auto-view-crossref}.
5294 @end itemize
5295 @noindent @b{Version 3.38}
5296 @itemize @bullet
5297 @item
5298 @code{reftex-view-crossref} no longer moves to find a macro.  Point has
5299 to be on the macro argument.
5300 @end itemize
5301 @noindent @b{Version 3.41}
5302 @itemize @bullet
5303 @item
5304 New options @code{reftex-texpath-environment-variables},
5305 @code{reftex-use-external-file-finders}, 
5306 @code{reftex-external-file-finders}, 
5307 @code{reftex-search-unrecursed-path-first}. 
5308 @item
5309 @emph{kpathsearch} support.  See new options and
5310 @code{reftex-bibpath-environment-variables}.
5311 @end itemize
5312 @noindent @b{Version 3.42}
5313 @itemize @bullet
5314 @item
5315 File search further refined.  New option @code{reftex-file-extensions}.
5316 @item
5317 @file{*toc*} buffer can show the file boundaries of a multifile
5318 document, all labels and associated context.  New keys @kbd{i}, @kbd{l},
5319 and @kbd{c}.  New options @code{reftex-toc-include-labels},
5320 @code{reftex-toc-include-context},
5321 @code{reftex-toc-include-file-boundaries}. @refill
5322 @end itemize
5323 @noindent @b{Version 3.43}
5324 @itemize @bullet
5325 @item
5326 Viewing cross-references generalized.  Now works on @code{\label},
5327 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5328 these, and from BibTeX buffers.@refill
5329 @item
5330 New option @code{reftex-view-crossref-extra}.@refill
5331 @item
5332 Support for the additional sectioning commands @code{\addchap} and
5333 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill
5334 @item
5335 Files in @code{reftex-default-bibliography} will be searched along
5336 @code{BIBINPUTS} path.@refill
5337 @item
5338 Reading a parse file now checks consistency.
5339 @end itemize
5340 @end ignore
5341 @noindent @b{Version 4.00}
5342 @itemize @bullet
5343 @item
5344 RefTeX has been split into several smaller files which are autoloaded on 
5345 demand.
5346 @item
5347 Index support, along with many new options.
5348 @item
5349 The selection of keys for @code{\ref} and @code{\cite} now allows to
5350 select multiple items by marking entries with the @kbd{m} key.
5351 @item
5352 Fancyref support.
5353 @end itemize
5354 @noindent @b{Version 4.01}
5355 @itemize @bullet
5356 @item
5357 New command @code{reftex-index-globally} to index a word in many
5358 places in the document.  Also available from the index buffer with
5359 @kbd{&}.
5360 @item
5361 The first item in a @code{reftex-label-alist} entry may now also be a parser
5362 function to do non-standard parsing.
5363 @item
5364 @code{reftex-auto-view-crossref} no longer interferes with
5365 @code{pop-up-frames} (patch from Stefan Monnier).
5366 @end itemize
5367 @noindent @b{Version 4.02}
5368 @itemize @bullet
5369 @item
5370 macros ending in @samp{refrange} are considered to contain references.
5371 @item
5372 Index entries made with @code{reftex-index-selection-or-word} in TeX
5373 math mode automatically get enclosing @samp{$} to preserve math mode.  See
5374 new option @code{reftex-index-math-format}.  Requires AUCTeX.
5375 @end itemize
5376 @noindent @b{Version 4.04}
5377 @itemize @bullet
5378 @item
5379 New option @code{reftex-index-default-tag} implements a default for queries.
5380 @end itemize
5381 @noindent @b{Version 4.06}
5382 @itemize @bullet
5383 @item
5384 @code{reftex-section-levels} can contain a function to compute the level
5385 of a sectioning command.
5386 @item
5387 Multiple @code{thebibliography} environments recognized.
5388 @end itemize
5389 @noindent @b{Version 4.09}
5390 @itemize @bullet
5391 @item
5392 New option @code{reftex-toc-max-level} to limit the depth of the toc.
5393 New keybinding @kbd{t} in the @file{*toc*} buffer to change this
5394 setting.@refill 
5395 @item
5396 RefTeX maintaines an @file{Index Phrases} file in which phrases can be 
5397 collected.  When the document is ready, RefTeX can search all
5398 these phrases and assist indexing all matches.@refill
5399 @item
5400 The variables @code{reftex-index-macros} and
5401 @code{reftex-index-default-macro} have changed their syntax slightly.
5402 The @var{repeat} parameter has move from the latter to the former.
5403 Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5404 need to be adapted.@refill
5405 @item
5406 The variable @code{reftex-section-levels} no longer contains the
5407 default stuff which has been moved to a constant.@refill
5408 @item
5409 Environments like theorems can be placed into the TOC by putting
5410 entries for @samp{"begin@{theorem@}"} in
5411 @code{reftex-setion-levels}.@refill 
5412 @end itemize
5413 @noindent @b{Version 4.10}
5414 @itemize @bullet
5415 @item
5416 Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5417 with @file{reftex-vars.el} on DOS machines.
5418 @item
5419 New options @code{reftex-parse-file-extension} and
5420 @code{reftex-index-phrase-file-extension}.
5421 @end itemize
5422 @noindent @b{Version 4.11}
5423 @itemize @bullet
5424 @item
5425 Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5426 @end itemize
5427 @noindent @b{Version 4.12}
5428 @itemize @bullet
5429 @item
5430 Support for @file{bibentry} citation style.
5431 @end itemize
5433 @node Index,  , , Top
5434 @unnumbered Index
5435 @printindex cp
5437 @summarycontents
5438 @contents
5439 @bye