1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/reftex
4 @settitle RefTeX User Manual
7 * RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
14 @set DATE September 1999
15 @set AUTHOR Carsten Dominik
16 @set AUTHOR-EMAIL dominik@@strw.leidenuniv.nl
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINER-EMAIL dominik@@strw.leidenuniv.nl
24 @c Subheadings inside a table. Need a difference between info and the rest.
25 @macro tablesubheading{text}
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 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.
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).
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.
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.
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
75 Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.
78 This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
79 @b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
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.
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.
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.
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
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.
141 * Index:: The full index.
147 * Installation:: How to install and activate RefTeX.
148 * RefTeX in a Nutshell:: A brief summary and quick guide.
150 Labels and References
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.
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.
181 * Creating Index Entries::
182 * Displaying and Editing the Index::
183 * Builtin Index Macros:: The index macros RefTeX knows about.
184 * Defining Index Macros:: ... and macros it doesn't.
188 * AUCTeX-RefTeX Interface:: How both packages work together
189 * Style Files:: AUCTeX's style files can support RefTeX
190 * Bib-Cite:: Hypertext reading of a document
192 Options, Keymaps, Hooks
194 * Options (Table of Contents)::
195 * Options (Defining Label Environments)::
196 * Options (Creating Labels)::
197 * Options (Referencing Labels)::
198 * Options (Creating Citations)::
199 * Options (Index Support)::
200 * Options (Viewing Cross-References)::
201 * Options (Finding Files)::
202 * Options (Optimizations)::
203 * Options (Fontification)::
211 @node Introduction, Table of Contents, , Top
212 @chapter Introduction
215 @b{Ref@TeX{}} is a specialized package for support of labels,
216 references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
217 itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
218 and @code{\index}. Using these macros usually requires looking up
219 different parts of the document and searching through BibTeX database
220 files. @b{Ref@TeX{}} automates these time--consuming tasks almost
221 entirely. It also provides functions to display the structure of a
222 document and to move around in this structure quickly.@refill
225 Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
226 in great depth. All you need to know to use @b{Ref@TeX{}} can be
227 summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
228 back later to other parts of this document when needed.
231 @xref{Imprint}, for information about who to contact for help, bug
232 reports or suggestions.
235 * Installation:: How to install and activate RefTeX.
236 * RefTeX in a Nutshell:: A brief summary and quick guide.
239 @node Installation, RefTeX in a Nutshell, , Introduction
240 @section Installation
243 @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2.
244 It was also bundled and pre--installed with XEmacs 19.16--20.x. XEmacs
245 21.x users want to install the corresponding plug-in package which is
247 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}. See
248 the XEmacs 21.x documentation on package installation for
251 Users of earlier Emacs distributions (including Emacs 19) can get a copy
252 of the @b{Ref@TeX{}} distribution from the maintainers web-page.
253 @xref{Imprint}, for more information.@refill
256 @cindex Finding files
257 @cindex BibTeX database files, not found
258 @cindex TeX files, not found
259 @cindex @code{TEXINPUTS}, environment variable
260 @cindex @code{BIBINPUTS}, environment variable
262 @b{Ref@TeX{}} needs to access all files which are part of a multifile
263 document, and the BibTeX database files requested by the
264 @code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
265 require a search path, i.e. a list of directories to check. Normally
266 this list is stored in the environment variables @code{TEXINPUTS} and
267 @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
268 systems these variables do not contain the full search path. If
269 @b{Ref@TeX{}} does not work for you because it cannot find some files,
270 read @ref{Finding Files}.
272 @section Entering @b{Ref@TeX{}} Mode
274 @findex turn-on-reftex
276 @vindex LaTeX-mode-hook
277 @vindex latex-mode-hook
278 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
279 @kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
280 files, add the following lines to your @file{.emacs} file:@refill
283 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
284 (add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
288 @node RefTeX in a Nutshell, , Installation, Introduction
289 @section @b{Ref@TeX{}} in a Nutshell
291 @cindex Getting Started
292 @cindex RefTeX in a Nutshell
293 @cindex Nutshell, RefTeX in a
297 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
298 a table of contents of the document. This buffer can display sections,
299 labels and index entries defined in the document. From the buffer, you
300 can jump quickly to every part of your document. Press @kbd{?} to get
304 @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
305 and to find the correct key for references quickly. It distinguishes
306 labels for different environments, knows about all standard
307 environments (and many others), and can be configured to recognize any
308 additional labeled environments you have defined yourself (variable
309 @code{reftex-label-alist}).@refill
313 @b{Creating Labels}@*
314 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
315 @b{Ref@TeX{}} will either
318 derive a label from context (default for section labels)
320 prompt for a label string (default for figures and tables) or
322 insert a simple label made of a prefix and a number (all other
326 Which labels are created how is configurable with the variable
327 @code{reftex-insert-label-flags}.@refill
330 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
331 (@code{reftex-reference}). This shows an outline of the document with
332 all labels of a certain type (figure, equation,...) and some label
333 context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
334 into the original buffer.@refill
339 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
340 regular expression to search in current BibTeX database files (as
341 specified in the @code{\bibliography} command) and pull out a list of
342 matches for you to choose from. The list is @emph{formatted} and
343 sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
344 (see the variable @code{reftex-cite-format} if you want to insert
345 different macros).@refill
349 @b{Ref@TeX{}} helps to enter index entries. It also compiles all
350 entries into an alphabetically sorted @file{*Index*} buffer which you
351 can use to check and edit the entries. @b{Ref@TeX{}} knows about the
352 standard index macros and can be configured to recognize any additional
353 macros you have defined (@code{reftex-index-macros}). Multiple indices
354 are supported.@refill
358 @b{Creating Index Entries}@*
359 Type @kbd{C-c /} (@code{reftex-index-selection-or-word}) to index the
360 current selection or the word at the cursor with the default macro (see
361 the variable @code{reftex-index-default-macro}).@*
362 Type @kbd{C-c <} (@code{reftex-index}) to insert a general index macro.
363 @b{Ref@TeX{}} will offer a list of available macros and provide
364 completion for the index tag (used to identify one of multiple indices)
365 and for the entry itself (useful with subentries).
370 @b{Displaying the Index}@* To display the compiled index in a special
371 buffer, type @kbd{C-c >} (@code{reftex-display-index}). From that
372 buffer you can check and edit all entries. The index can be restricted
373 to those entries defined in a single document section or in a user
374 defined region.@refill
378 @item @b{Viewing Cross-References}@*
379 When point is on the @var{key} argument of a cross--referencing macro
380 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
381 @code{\index}, and variations) or inside a BibTeX database entry, you
382 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
383 corresponding locations in the document and associated BibTeX database
384 files.@refill @* When the enclosing macro is @code{\cite} or @code{\ref}
385 and no other message occupies the echo area, information about the
386 citation or label will automatically be displayed in the echo
390 @b{Multifile Documents}@*
391 Multifile Documents are fully supported. The included files must have a
392 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
393 master file. @b{Ref@TeX{}} provides cross-referencing information from
394 all parts of the document, and across document borders
395 (@file{xr.sty}).@refill
398 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
399 order to find labels and other information. It does it automatically
400 once and updates its list internally when @code{reftex-label} and
401 @code{reftex-index} are used. To enforce reparsing, call any of the
402 commands described above with a raw @kbd{C-u} prefix, or press the
403 @kbd{r} key in the label selection buffer, the table of contents
404 buffer, or the index buffer.@refill
407 @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
408 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
409 contains style files which trigger appropriate settings in
410 @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
411 additional customizations will be necessary.@refill
414 @b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,
417 (setq reftex-enable-partial-scans t)
418 (setq reftex-save-parse-info t)
419 (setq reftex-use-multiple-selection-buffers t)
422 To integrate with AUCTeX, use
424 (setq reftex-plug-into-AUCTeX t)
427 To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
428 customize the variables@refill
430 @code{reftex-label-alist} @r{(for label macros/environments)}
431 @code{reftex-section-levels} @r{(for sectioning commands)}
432 @code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
433 @code{reftex-index-macros} @r{(for @code{\index}-like macros)}
434 @code{reftex-index-default-macro} @r{(to set the default macro)}
436 If you have a large number of macros defined, you may want to write
437 an AUCTeX style file to support them with both AUCTeX and
438 @b{Ref@TeX{}}.@refill
440 @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
441 until you have picked up the key bindings. For an overview of what you
442 can do in each of the different special buffers, press @kbd{?}. Read
443 the manual if you get stuck. The first part of the manual explains in
444 a tutorial way how to use and customize @b{Ref@TeX{}}. The second
445 part is a command and variable reference.@refill
448 @node Table of Contents, Labels and References, Introduction, Top
449 @chapter Table of Contents
450 @cindex @file{*toc*} buffer
451 @cindex Table of contents buffer
455 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
456 contents of the document. By default, this @file{*toc*} buffer shows
457 only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
458 can display all labels and index entries defined in the document as
461 With the cursor in any of the lines denoting a location in the
462 document, simple key strokes will display the corresponding part in
463 another window, jump to that location, or perform other actions.@refill
466 Here is a list of special commands in the @file{*toc*} buffer. A
467 summary of this information is always available by pressing
472 @tablesubheading{General}
474 Display a summary of commands.
479 @tablesubheading{Moving around}
481 Goto next entry in the table of context.
484 Goto previous entry in the table of context.
487 Goto next section heading. Useful when many labels and index entries
488 separate section headings.@refill
491 Goto previous section heading.
493 @tablesubheading{Access to document locations}
495 Show the corresponding location in another window. This command does
496 @emph{not} select that other window.@refill
499 Goto the location in another window.
502 Go to the location and hide the @file{*toc*} buffer. This will restore
503 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
507 @vindex reftex-highlight-selection
508 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
509 See also variable @code{reftex-highlight-selection}, @ref{Options
510 (Fontification)}.@refill
513 @vindex reftex-toc-follow-mode
514 @vindex reftex-revisit-to-follow
515 Toggle follow mode. When follow mode is active, the other window will
516 always show the location corresponding to the line at point in the
517 @file{*toc*} buffer. This is similar to pressing @key{SPC} after each
518 cursor motion. The default for this flag can be set with the variable
519 @code{reftex-toc-follow-mode}. Note that only context in files already
520 visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
521 mode. See, however, the variable
522 @code{reftex-revisit-to-follow}.@refill
525 Show calling point in another window. This is the point from where
526 @code{reftex-toc} was last called.
528 @tablesubheading{Exiting}
530 Hide the @file{*toc*} buffer, return to the position where
531 @code{reftex-toc} was last called.@refill
534 Kill the @file{*toc*} buffer, return to the position where
535 @code{reftex-toc} was last called.@refill
538 Switch to the @file{*Index*} buffer of this document. With prefix
539 @samp{2}, restrict the index to the section at point in the @file{*toc*}
542 @tablesubheading{Controlling what gets displayed}
545 @vindex reftex-toc-include-file-boundaries
546 Toggle the display of the file borders of a multifile document in the
547 @file{*toc*} buffer. The default for this flag can be set with the
548 variable @code{reftex-toc-include-file-boundaries}.@refill
551 @vindex reftex-toc-include-labels
552 Toggle the display of labels in the @file{*toc*} buffer. The default
553 for this flag can be set with the variable
554 @code{reftex-toc-include-labels}. When called with a prefix argument,
555 @b{Ref@TeX{}} will prompt for a label type and include only labels of
556 the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
557 indicator shows which labels are included.@refill
560 @vindex reftex-toc-include-index-entries
561 Toggle the display of index entries in the @file{*toc*} buffer. The
562 default for this flag can be set with the variable
563 @code{reftex-toc-include-index-entries}. When called with a prefix
564 argument, @b{Ref@TeX{}} will prompt for a specific index and include
565 only entries in the selected index in the @file{*toc*} buffer. The mode
566 line @samp{I<>} indicator shows which index is used.@refill
569 @vindex reftex-toc-include-context
570 Toggle the display of label and index context in the @file{*toc*}
571 buffer. The default for this flag can be set with the variable
572 @code{reftex-toc-include-context}.@refill
574 @tablesubheading{Updating the buffer}
577 Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
581 @vindex reftex-enable-partial-scans
582 Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
583 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
584 location is defined in, not the entire document.@refill
587 Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
591 Switch to the @file{*toc*} buffer of an external document. When the
592 current document is using the @code{xr} package (@pxref{xr (LaTeX
593 package)}), @b{Ref@TeX{}} will switch to one of the external
598 @vindex reftex-toc-map
599 In order to define additional commands for the @file{*toc*} buffer, the
600 keymap @code{reftex-toc-map} may be used.@refill
602 @cindex Sectioning commands
603 @cindex KOMA-Script, LaTeX classes
604 @cindex LaTeX classes, KOMA-Script
605 @vindex reftex-section-levels
606 The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
607 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
608 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
609 Additional macros can be configured with the variable
610 @code{reftex-section-levels}.
612 @node Labels and References, Citations, Table of Contents, Top
613 @chapter Labels and References
614 @cindex Labels in LaTeX
615 @cindex References in LaTeX
616 @cindex Label category
617 @cindex Label environment
618 @cindex @code{\label}
620 LaTeX provides a powerful mechanism to deal with cross--references in a
621 document. When writing a document, any part of it can be marked with a
622 label, like @samp{\label@{mark@}}. LaTeX records the current value of a
623 certain counter when a label is defined. Later references to this label
624 (like @samp{\ref@{mark@}}) will produce the recorded value of the
627 Labels can be used to mark sections, figures, tables, equations,
628 footnotes, items in enumerate lists etc. LaTeX is context sensitive in
629 doing this: A label defined in a figure environment automatically
630 records the figure counter, not the section counter.@refill
632 Several different environments can share a common counter and therefore
633 a common label category. E.g. labels in both @code{equation} and
634 @code{eqnarray} environments record the value of the same counter - the
635 equation counter.@refill
639 * Referencing Labels::
640 * Builtin Label Environments:: The environments RefTeX knows about.
641 * Defining Label Environments:: ... and environments it doesn't.
642 * Reference Info:: View the label corresponding to a \ref.
643 * xr (LaTeX package):: References to external documents.
644 * varioref (LaTeX package):: How to create \vref instead of \ref.
645 * fancyref (LaTeX package):: How to create \fref instead of \ref.
648 @node Creating Labels, Referencing Labels, , Labels and References
649 @section Creating Labels
650 @cindex Creating labels
651 @cindex Labels, creating
652 @cindex Labels, deriving from context
656 In order to create a label in a LaTeX document, press @kbd{C-c (}
657 (@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
658 and will figure out the environment it currently is in and adapt the
659 label to that environment. A label usually consists of a short prefix
660 indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
661 3 different modes to create this mark.@refill
665 @vindex reftex-translate-to-ascii-function
666 @vindex reftex-derive-label-parameters
667 @vindex reftex-label-illegal-re
668 @vindex reftex-abbrev-parameters
669 A label can be derived from context. This means, @b{Ref@TeX{}} takes
670 the context of the label definition and constructs a label from
671 that@footnote{Note that the context may contain constructs which are
672 illegal in labels. @b{Ref@TeX{}} will therefore strip the accent from
673 accented Latin-1 characters and remove everything else which is not
674 legal in labels. This mechanism is safe, but may not be satisfactory
675 for non-western languages. Check the following variables if you need to
676 change things: @code{reftex-translate-to-ascii-function},
677 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
678 @code{reftex-abbrev-parameters}.}. This works best for section labels,
679 where the section heading is used to construct a label. In fact,
680 @b{Ref@TeX{}}'s default settings use this method only for section
681 labels. You will be asked to confirm the derived label, or edit
685 We may also use a simple unique number to identify a label. This is
686 mostly useful for labels where it is difficult to come up with a very
687 good descriptive name. @b{Ref@TeX{}}'s default settings use this method
688 for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
689 tends to write documents with many equations and finds it impossible
690 to come up with good names for each of them. These simple labels are
691 inserted without query, and are therefore very fast. Good descriptive
692 names are not really necessary as @b{Ref@TeX{}} will provide context to
693 reference a label (@pxref{Referencing Labels}).@refill
696 The third method is to ask the user for a label. This is most
697 useful for things which are easy to describe briefly and do not turn up
698 too frequently in a document. @b{Ref@TeX{}} uses this for figures and
699 tables. Of course, one can enter the label directly by typing the full
700 @samp{\label@{mark@}}. The advantage of using @code{reftex-label}
701 anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
702 It will then not be necessary to rescan the document in order to access
703 this label later.@refill
706 @vindex reftex-insert-label-flags
707 If you want to change the way certain labels are created, check out the
708 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
711 If you are using AUCTeX to write your LaTeX documents, you can
712 set it up to delegate the creation of labels to
713 @b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
715 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
716 @section Referencing Labels
717 @cindex Referencing labels
718 @cindex Labels, referencing
719 @cindex Selection buffer, labels
720 @cindex Selection process
723 @findex reftex-reference
725 Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c
726 )} in order to reference a label (reftex-reference). This will start a
727 selection process and finally insert the complete @samp{\ref@{label@}}
728 into the buffer.@refill
730 First, @b{Ref@TeX{}} will determine the label category which is required.
731 Often that can be figured out from context. For example, if you
732 write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
733 that an equation label is going to be referenced. If it cannot figure
734 out what label category is needed, it will query for one.@refill
736 You will then be presented with a label selection menu. This is a
737 special buffer which contains an outline of the document along with all
738 labels of the given label category. In addition, next to the label
739 there will be one line of context of the label definition, which is some
740 text in the buffer near the label definition. Usually this is
741 sufficient to identify the label. If you are unsure about a certain
742 label, pressing @key{SPC} will show the label definition point in
743 another window.@refill
745 In order to reference a label, move to cursor to the correct label and
746 press @key{RET}. You can also reference several labels with a single
747 call to @code{reftex-reference} by marking entries with the @kbd{m}
751 Here is a list of special commands in the selection buffer. A summary
752 of this information is always available from the selection process by
753 pressing @kbd{?}.@refill
758 @tablesubheading{General}
760 Show a summary of available commands.
765 @tablesubheading{Moving around}
770 Go to previous label.
773 Jump back to the position where you last left the selection buffer.
774 Normally this should get you back to the last referenced label.@refill
777 Goto next section heading.
780 Goto previous section heading.
782 @tablesubheading{Displaying Context}
784 Show the surroundings of the definition of the current label in another
785 window. See also the @kbd{f} key.@refill
788 @vindex reftex-revisit-to-follow
789 Toggle follow mode. When follow mode is active, the other window will
790 always display the full context of the current label. This is similar
791 to pressing @key{SPC} after each cursor motion. Note that only context
792 in files already visited is shown. @b{RefTeX} will not visit a file
793 just for follow mode. See, however, the variable
794 @code{reftex-revisit-to-follow}.@refill
797 Show insertion point in another window. This is the point from where you
798 called @code{reftex-reference}.@refill
800 @tablesubheading{Selecting a label and creating the reference}
802 Insert a reference to the label at point into the buffer from which the
803 selection process was started. When entries have been marked, @key{RET}
804 references all marked labels.@refill
807 @vindex reftex-highlight-selection
808 Clicking with mouse button 2 on a label will accept it like @key{RET}
809 would. See also variable @code{reftex-highlight-selection}, @ref{Options
812 @vindex reftex-multiref-punctuation
814 Mark the current entry. When several entries have been marked, pressing
815 @kbd{RET} will accept all of them and place them into several
816 @code{\ref} macros. The special markers @samp{,-+} also store a
817 separator to be inserted before the corresponding reference. So marking
818 six entries with the keys @samp{m , , - , +} will give a reference list
819 like this (see the variable @code{reftex-multiref-punctuation})
821 In eqs. (1), (2), (3)--(4), (5) and (6)
825 Unmark a marked entry.
827 @c FIXME: Do we need `A' as well for consistency?
828 @cindex LaTeX packages, @code{saferef}
829 @cindex @code{saferef}, LaTeX package
831 Accept the marked entries and put all labels as a comma-separated list
832 into one @emph{single} @code{\ref} macro. Some packages like
833 @file{saferef.sty} support multiple references in this way.@refill
836 Use the last referenced label(s) again. This is equivalent to moving to
837 that label and pressing @key{RET}.@refill
840 Enter a label with completion. This may also be a label which does not
841 yet exist in the document.
844 @cindex @code{varioref}, LaTeX package
846 @cindex LaTeX packages, @code{varioref}
847 Toggle between @code{\ref} and @code{\vref} macro for references. The
848 @code{\vref} macro is defined in the @code{varioref} LaTeX package.
849 With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
850 macro. The current state of this flag is displayed by the @samp{S<>}
851 indicator in the mode line of the selection buffer.@refill
854 @cindex @code{fancyref}, LaTeX package
857 @cindex LaTeX packages, @code{fancyref}
858 Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The
859 @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
860 LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a
861 @code{\fref} or @code{\Fref} macro. The current state of this flag is
862 displayed by the @samp{S<>} indicator in the mode line of the
865 @tablesubheading{Exiting}
868 Exit the selection process without inserting any reference into the
871 @tablesubheading{Controlling what gets displayed}
872 @vindex reftex-label-menu-flags
873 The defaults for the following flags can be configured with the variable
874 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
877 Toggle the display of the one-line label definition context in the
878 selection buffer.@refill
881 Toggle the display of the file borders of a multifile document in the
882 selection buffer.@refill
885 Toggle the display of the table of contents in the selection buffer.@refill
888 Toggle the display of a label counter in the selection buffer.@refill
891 Toggle the display of labels hidden in comments in the selection
892 buffers. Sometimes, you may have commented out parts of your document.
893 If these parts contain label definitions, @b{Ref@TeX{}} can still display
894 and reference these labels.@refill
896 @tablesubheading{Updating the buffer}
898 Update the menu. This will rebuilt the menu from the internal label
899 list, but not reparse the document (see @kbd{r}).@refill
902 @vindex reftex-enable-partial-scans
903 Reparse the document to update the information on all labels and rebuild
904 the menu. If the variable @code{reftex-enable-partial-scans} is
905 non-@code{nil} and your document is a multifile document, this will
906 reparse only a part of the document (the file in which the label at
907 point was defined).@refill
910 Reparse the @emph{entire} document.
913 Switch the label category. After prompting for another label category,
914 a menu for that category will be shown.@refill
917 Reference a label from an external document. With the LaTeX package
918 @code{xr} it is possible to reference labels defined in another
919 document. This key will switch to the label menu of an external
920 document and let you select a label from there (@pxref{xr (LaTeX
921 package),,xr}).@refill
925 @vindex reftex-select-label-map
926 In order to define additional commands for the selection process, the
927 keymap @code{reftex-select-label-map} may be used.@refill
929 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
930 @section Builtin Label Environments
931 @cindex Builtin label environments
932 @cindex Label environments, builtin
933 @cindex Environments, builtin
934 @vindex reftex-label-alist
935 @vindex reftex-label-alist-builtin
937 @b{Ref@TeX{}} needs to be aware of the environments which can be referenced
938 with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}
939 recognizes all labeled environments and macros discussed in @cite{The
940 LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
941 1994.}. These are:@refill
945 @cindex @code{figure}, LaTeX environment
946 @cindex @code{figure*}, LaTeX environment
947 @cindex @code{table}, LaTeX environment
948 @cindex @code{table*}, LaTeX environment
949 @cindex @code{equation}, LaTeX environment
950 @cindex @code{eqnarray}, LaTeX environment
951 @cindex @code{enumerate}, LaTeX environment
952 @cindex @code{\footnote}, LaTeX macro
953 @cindex LaTeX macro @code{footnote}
955 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
956 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
957 the LaTeX core stuff)@refill
960 @cindex @code{amsmath}, LaTeX package
961 @cindex LaTeX packages, @code{amsmath}
962 @cindex @code{align}, AMS-LaTeX environment
963 @cindex @code{gather}, AMS-LaTeX environment
964 @cindex @code{multline}, AMS-LaTeX environment
965 @cindex @code{flalign}, AMS-LaTeX environment
966 @cindex @code{alignat}, AMS-LaTeX environment
967 @cindex @code{xalignat}, AMS-LaTeX environment
968 @cindex @code{xxalignat}, AMS-LaTeX environment
969 @cindex @code{subequations}, AMS-LaTeX environment
970 @code{align}, @code{gather}, @code{multline}, @code{flalign},
971 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
972 (from AMS-LaTeX's @file{amsmath.sty} package)@refill
974 @cindex @code{endnote}, LaTeX package
975 @cindex LaTeX packages, @code{endnote}
976 @cindex @code{\endnote}, LaTeX macro
977 the @code{\endnote} macro (from @file{endnotes.sty})
979 @cindex @code{fancybox}, LaTeX package
980 @cindex LaTeX packages, @code{fancybox}
981 @cindex @code{Beqnarray}, LaTeX environment
982 @code{Beqnarray} (@file{fancybox.sty})
984 @cindex @code{floatfig}, LaTeX package
985 @cindex LaTeX packages, @code{floatfig}
986 @cindex @code{floatingfig}, LaTeX environment
987 @code{floatingfig} (@file{floatfig.sty})
989 @cindex @code{longtable}, LaTeX package
990 @cindex LaTeX packages, @code{longtable}
991 @cindex @code{longtable}, LaTeX environment
992 @code{longtable} (@file{longtable.sty})
994 @cindex @code{picinpar}, LaTeX package
995 @cindex LaTeX packages, @code{picinpar}
996 @cindex @code{figwindow}, LaTeX environment
997 @cindex @code{tabwindow}, LaTeX environment
998 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1000 @cindex @code{sidecap}, LaTeX package
1001 @cindex LaTeX packages, @code{sidecap}
1002 @cindex @code{SCfigure}, LaTeX environment
1003 @cindex @code{SCtable}, LaTeX environment
1004 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1006 @cindex @code{rotating}, LaTeX package
1007 @cindex LaTeX packages, @code{rotating}
1008 @cindex @code{sidewaysfigure}, LaTeX environment
1009 @cindex @code{sidewaystable}, LaTeX environment
1010 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1012 @cindex @code{subfig}, LaTeX package
1013 @cindex LaTeX packages, @code{subfigure}
1014 @cindex @code{subfigure}, LaTeX environment
1015 @cindex @code{subfigure*}, LaTeX environment
1016 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1017 (@file{subfigure.sty})@refill
1019 @cindex @code{supertab}, LaTeX package
1020 @cindex LaTeX packages, @code{supertab}
1021 @cindex @code{supertabular}, LaTeX environment
1022 @code{supertabular} (@file{supertab.sty})
1024 @cindex @code{wrapfig}, LaTeX package
1025 @cindex LaTeX packages, @code{wrapfig}
1026 @cindex @code{wrapfigure}, LaTeX environment
1027 @code{wrapfigure} (@file{wrapfig.sty})
1030 If you want to use other labeled environments, defined with
1031 @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
1032 them (@pxref{Defining Label Environments}).@refill
1034 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1035 @section Defining Label Environments
1036 @cindex Label environments, defining
1038 @vindex reftex-label-alist
1039 @b{Ref@TeX{}} can be configured to recognize additional labeled
1040 environments and macros. This is done with the variable
1041 @code{reftex-label-alist} (@pxref{Options (Defining Label
1042 Environments)}). If you are not familiar with Lisp, you can use the
1043 @code{custom} library to configure this rather complex variable. To do
1047 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1050 @vindex reftex-label-alist-builtin
1051 Here we will discuss a few examples, in order to make things clearer.
1052 It can also be instructive to look at the constant
1053 @code{reftex-label-alist-builtin} which contains the entries for
1054 all the builtin environments and macros (@pxref{Builtin Label
1055 Environments}).@refill
1058 * Theorem and Axiom:: Defined with @code{\newenvironment}.
1059 * Quick Equation:: When a macro sets the label type.
1060 * Figure Wrapper:: When a macro argument is a label.
1061 * Adding Magic Words:: Other words for other languages.
1062 * Using \eqref:: How to switch to this AMS-LaTeX macro.
1063 * Non-Standard Environments:: Environments without \begin and \end
1064 * Putting it Together:: How to combine many entries.
1067 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1068 @subsection Theorem and Axiom Environments
1069 @cindex @code{theorem}, newtheorem
1070 @cindex @code{axiom}, newtheorem
1071 @cindex @code{\newtheorem}
1073 Suppose you are using @code{\newtheorem} in LaTeX in order to define two
1074 new environments, @code{theorem} and @code{axiom}@refill
1077 \newtheorem@{axiom@}@{Axiom@}
1078 \newtheorem@{theorem@}@{Theorem@}
1082 to be used like this:
1091 So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
1092 labeled environments which define their own label categories. We can
1093 either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
1094 library. With Lisp it would look like this
1097 (setq reftex-label-alist
1098 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax."))
1099 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th."))))
1102 The type indicator characters @code{?a} and @code{?h} are used for
1103 prompts when @b{Ref@TeX{}} queries for a label type. @code{?h}
1104 was chosen for @code{theorem} since @code{?t} is already taken by
1105 @code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
1106 @code{?i}, @code{?n} are already used for standard environments.@refill
1109 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1110 @samp{thr:}, respectively. @xref{AUCTeX}, for information on how
1111 AUCTeX can use @b{Ref@TeX{}} to automatically create labels when a new
1112 environment is inserted into a buffer.@refill
1115 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1116 references to these labels.@refill
1119 The next item indicates how to grab context of the label definition.@refill
1122 @code{t} means to get it from a default location (from the beginning of
1123 a @code{\macro} or after the @code{\begin} statement). @code{t} is
1124 @emph{not} a good choice for eqnarray and similar environments.@refill
1126 @code{nil} means to use the text right after the label definition.@refill
1128 For more complex ways of getting context, see the variable
1129 @code{reftex-label-alist} (@ref{Options (Defining Label
1130 Environments)}).@refill
1133 The strings at the end of each entry are used to guess the correct label
1134 type from the word before point when creating a reference. E.g. if you
1135 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1136 @b{Ref@TeX{}} will know that you are looking for a theorem label and restrict
1137 the menu to only these labels without even asking.@refill
1139 To do the same configuration with @code{customize}, you need to click on
1140 the @code{[INS]} button twice to create two templates and fill them in
1144 Reftex Label Alist: [Hide]
1145 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1146 Environment or \macro : [Value Menu] String: axiom
1147 Type specification : [Value Menu] Char : a
1148 Label prefix string : [Value Menu] String: ax:
1149 Label reference format: [Value Menu] String: ~\ref@{%s@}
1150 Context method : [Value Menu] After label
1152 [INS] [DEL] String: axiom
1153 [INS] [DEL] String: ax.
1155 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1156 Environment or \macro : [Value Menu] String: theorem
1157 Type specification : [Value Menu] Char : h
1158 Label prefix string : [Value Menu] String: thr:
1159 Label reference format: [Value Menu] String: ~\ref@{%s@}
1160 Context method : [Value Menu] Default position
1162 [INS] [DEL] String: theorem
1163 [INS] [DEL] String: theor.
1164 [INS] [DEL] String: th.
1168 @vindex reftex-insert-label-flags
1169 @vindex reftex-label-menu-flags
1170 Depending on how you would like the label insertion and selection for
1171 the new environments to work, you might want to add the letters @samp{a}
1172 and @samp{h} to some of the flags in the variables
1173 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1174 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1178 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1179 @subsection Quick Equation Macro
1180 @cindex Quick equation macro
1181 @cindex Macros as environment wrappers
1183 Suppose you would like to have a macro for quick equations. It
1184 could be defined like this:
1187 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1194 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1197 We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
1198 @code{\quickeq} is an equation label. Here is how to do this with lisp:
1201 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1204 The first element in this list is now the macro with empty braces as an
1205 @emph{image} of the macro arguments. @code{?e} indicates that this is
1206 an equation label, the different @code{nil} elements indicate to use the
1207 default values for equations. The @samp{1} as the fifth element
1208 indicates that the context of the label definition should be the 1st
1209 argument of the macro.@refill
1211 Here is again how this would look in the customization buffer:
1214 Reftex Label Alist: [Hide]
1215 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1216 Environment or \macro : [Value Menu] String: \quickeq@{@}
1217 Type specification : [Value Menu] Char : e
1218 Label prefix string : [Value Menu] Default
1219 Label reference format: [Value Menu] Default
1220 Context method : [Value Menu] Macro arg nr: 1
1225 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1226 @subsection Figure Wrapping Macro
1227 @cindex Macros as environment wrappers
1228 @cindex Figure wrapping macro
1230 Suppose you want to make figures not directly with the figure
1231 environment, but with a macro like
1234 \newcommand@{\myfig@}[5][tbp]@{%
1235 \begin@{figure@}[#1]
1243 which would be called like
1246 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1249 Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
1250 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1254 (setq reftex-label-alist
1255 '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1258 The empty pairs of brackets indicate the different arguments of the
1259 @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
1260 indicates that this is a figure label which will be listed together with
1261 labels from normal figure environments. The @code{nil} entries for
1262 prefix and reference format mean to use the defaults for figure labels.
1263 The @samp{3} for the context method means to grab the 3rd macro argument
1264 - the caption.@refill
1266 As a side effect of this configuration, @code{reftex-label} will now
1267 insert the required naked label (without the @code{\label} macro) when
1268 point is directly after the opening parenthesis of a @code{\myfig} macro
1271 Again, here the configuration in the customization buffer:
1274 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1275 Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1276 Type specification : [Value Menu] Char : f
1277 Label prefix string : [Value Menu] Default
1278 Label reference format: [Value Menu] Default
1279 Context method : [Value Menu] Macro arg nr: 3
1284 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1285 @subsection Adding Magic Words
1287 @cindex German magic words
1288 @cindex Label category
1290 Sometimes you don't want to define a new label environment or macro, but
1291 just change the information associated with a label category. Maybe you
1292 want to add some magic words, for another language. Changing only the
1293 information associated with a label category is done by giving
1294 @code{nil} for the environment name and then specify the items you want
1295 to define. Here is an example which adds German magic words to all
1296 predefined label categories.@refill
1299 (setq reftex-label-alist
1300 '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1301 (nil ?e nil nil nil ("Gleichung" "Gl."))
1302 (nil ?t nil nil nil ("Tabelle"))
1303 (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1304 (nil ?n nil nil nil ("Anmerkung" "Anm."))
1305 (nil ?i nil nil nil ("Punkt"))))
1308 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1309 @subsection Using @code{\eqref}
1310 @cindex @code{\eqref}, AMS-LaTeX macro
1312 @cindex Label category
1314 Another case where one only wants to change the information associated
1315 with the label category is to change the macro which is used for
1316 referencing the label. When working with the AMS-LaTeX stuff, you might
1317 prefer @code{\eqref} for doing equation references. Here is how to
1321 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1324 @b{Ref@TeX{}} has also a predefined symbol for this special purpose. The
1325 following is equivalent to the line above.@refill
1328 (setq reftex-label-alist '(AMSTeX))
1331 Note that this is automatically done by the @file{amsmath.el} style file
1332 of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
1333 this configuration will not be necessary.@refill
1335 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1336 @subsection Non-standard Environments
1337 @cindex Non-standard environments
1338 @cindex Environments without @code{\begin}
1339 @cindex Special parser functions
1340 @cindex Parser functions, for special environments
1342 Some LaTeX packages define environment-like structures without using the
1343 standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse
1344 these directly, but you can write your own special-purpose parser and
1345 use it instead of the name of an environment in an entry for
1346 @code{reftex-label-alist}. The function should check if point is
1347 currently in the special environment it was written to detect. If so,
1348 it must return a buffer position indicating the start of this
1349 environment. The return value must be @code{nil} on failure to detect
1350 the environment. The function is called with one argument @var{bound}.
1351 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1352 which should be observed. We will discuss two examples.@refill
1354 @cindex LaTeX commands, abbreviated
1356 Some people define abbreviations for
1357 environments, like @code{\be} for @code{\begin@{equation@}}, and
1358 @code{\ee} for @code{\end@{equation@}}. The parser function would have
1359 to search backward for these macros. When the first match is
1360 @code{\ee}, point is not in this environment. When the first match is
1361 @code{\be}, point is in this environment and the function must return
1362 the beginning of the match. To avoid scanning too far, we can also look
1363 for empty lines which cannot occure inside an equation environment.
1364 Here is the setup:@refill
1367 ;; Setup entry in reftex-label-alist, using all defaults for equations
1368 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1370 (defun detect-be-ee (bound)
1371 ;; Search backward for the macros or an empty line
1372 (if (re-search-backward
1373 "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1374 (if (match-beginning 2)
1375 (match-beginning 2) ; Return start of environment
1376 nil) ; Return nil because env is closed
1377 nil)) ; Return nil for not found
1380 @cindex @code{linguex}, LaTeX package
1381 @cindex LaTeX packages, @code{linguex}
1382 A more complex example is the @file{linguex.sty} package which defines
1383 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1384 terminated by @samp{\z.} or by an empty line.@refill
1387 \ex. \label@{ex:12@} Some text in an exotic language ...
1388 \a. \label@{ex:13@} more stuff
1389 \b. \label@{ex:14@} still more stuff
1390 \a. List on a deeper level
1392 \b. and the third one
1394 \b. Third item on this level.
1396 ... text after the empty line terminating all lists
1399 The difficulty is that the @samp{\a.} lists can nest and that an empty
1400 line terminates all list levels in one go. So we have to count nesting
1401 levels between @samp{\a.} and @samp{\z.}. Here is the implementation
1405 (setq reftex-label-alist
1406 '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1408 (defun detect-linguex (bound)
1412 ;; Search backward for all possible delimiters
1414 (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1415 "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1417 ;; Check which delimiter was matched.
1419 ((match-beginning 1)
1420 ;; empty line terminates all - return nil
1422 ((match-beginning 2)
1423 ;; \z. terminates one list level - decrease nesting count
1425 ((match-beginning 3)
1426 ;; \ex. : return match unless there was a \z. on this level
1427 (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1428 ((match-beginning 4)
1429 ;; \a. : return match when on level 0, otherwise
1430 ;; increment nesting count
1432 (throw 'exit (match-beginning 4))
1436 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1437 @subsection Putting it all together
1439 When you have to put several entries into @code{reftex-label-alist}, just
1440 put them after each other in a list, or create that many templates in
1441 the customization buffer. Here is a lisp example which uses several of
1442 the entries described above:
1445 (setq reftex-label-alist
1446 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax."))
1447 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th."))
1448 ("\\quickeq@{@}" ?e nil nil 1 nil)
1450 ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1451 (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1454 @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
1455 @section Reference Info
1456 @findex reftex-view-crossref
1457 @findex reftex-mouse-view-crossref
1458 @cindex Cross-references, displaying
1459 @cindex Reference info
1460 @cindex Displaying cross-references
1461 @cindex Viewing cross-references
1465 When point is idle on the argument of a @code{\ref} macro, the echo area
1466 will display some information about the label referenced there. Note
1467 that the information is only displayed if the echo area is not occupied
1468 by a different message.
1470 @b{Ref@TeX{}} can also display the label definition corresponding to a
1471 @code{\ref} macro, or all reference locations corresponding to a
1472 @code{\label} macro. @xref{Viewing Cross-References}, for more
1475 @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
1476 @section @code{xr}: Cross-Document References
1477 @cindex @code{xr}, LaTeX package
1478 @cindex LaTeX packages, @code{xr}
1479 @cindex @code{\externaldocument}
1480 @cindex External documents
1481 @cindex References to external documents
1482 @cindex Cross-document references
1484 The LaTeX package @code{xr} makes it possible to create references to
1485 labels defined in external documents. The preamble of a document using
1486 @code{xr} will contain something like this:@refill
1490 \externaldocument[V1-]@{volume1@}
1491 \externaldocument[V3-]@{volume3@}
1495 and we can make references to any labels defined in these
1496 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1497 respectively.@refill
1499 @b{Ref@TeX{}} can be used to create such references as well. Start the
1500 referencing process normally, by pressing @kbd{C-c )}. Select a label
1501 type if necessary. When you see the label selection buffer, pressing
1502 @kbd{x} will switch to the label selection buffer of one of the external
1503 documents. You may then select a label as before and @b{Ref@TeX{}} will
1504 insert it along with the required prefix.@refill
1506 For this kind of inter-document cross-references, saving of parsing
1507 information and the use of multiple selection buffers can mean a large
1508 speed-up (@pxref{Optimizations}).@refill
1510 @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
1511 @section @code{varioref}: Variable Page References
1512 @cindex @code{varioref}, LaTeX package
1513 @cindex @code{\vref}
1514 @cindex LaTeX packages, @code{varioref}
1515 @vindex reftex-vref-is-default
1516 @code{varioref} is a frequently used LaTeX package to create
1517 cross--references with page information. When you want to make a
1518 reference with the @code{\vref} macro, just press the @kbd{v} key in the
1519 selection buffer to toggle between @code{\ref} and @code{\vref}
1520 (@pxref{Referencing Labels}). The mode line of the selection buffer
1521 shows the current status of this switch. If you find that you almost
1522 always use @code{\vref}, you may want to make it the default by
1523 customizing the variable @code{reftex-vref-is-default}. If this
1524 toggling seems too inconvenient, you can also use the command
1525 @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
1526 Or use AUCTeX to create your macros (@pxref{AUCTeX}).@refill
1528 @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
1529 @section @code{fancyref}: Fancy Cross References
1530 @cindex @code{fancyref}, LaTeX package
1531 @cindex @code{\fref}
1532 @cindex @code{\Fref}
1533 @cindex LaTeX packages, @code{fancyref}
1534 @vindex reftex-fref-is-default
1535 @code{fancyref} is a LaTeX package where a macro call like
1536 @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
1537 the referenced counter but also the complete text around it, like
1538 @samp{Figure 3 on the preceding page}. In order to make it work you
1539 need to use label prefixes like @samp{fig:} consistently - something
1540 @b{Ref@TeX{}} does automatically. When you want to make a reference
1541 with the @code{\fref} macro, just press the @kbd{V} key in the selection
1542 buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
1543 (@pxref{Referencing Labels}). The mode line of the selection buffer
1544 shows the current status of this switch. If this cycling seems
1545 inconvenient, you can also use the commands @code{reftex-fancyref-fref}
1546 and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
1547 f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros
1548 (@pxref{AUCTeX}).@refill
1550 @node Citations, Index Support, Labels and References, Top
1553 @cindex @code{\cite}
1555 Citations in LaTeX are done with the @code{\cite} macro or variations of
1556 it. The argument of the macro is a citation key which identifies an
1557 article or book in either a BibTeX database file or in an explicit
1558 @code{thebibliography} environment in the document. @b{Ref@TeX{}}'s
1559 support for citations helps to select the correct key quickly.@refill
1562 * Creating Citations:: How to create them.
1563 * Citation Styles:: Natbib, Harvard, Chicago and Co.
1564 * Citation Info:: View the corresponding database entry.
1565 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
1566 * Citations Outside LaTeX:: How to make citations in Emails etc.
1569 @node Creating Citations, Citation Styles, , Citations
1570 @section Creating Citations
1571 @cindex Creating citations
1572 @cindex Citations, creating
1573 @findex reftex-citation
1575 @cindex Selection buffer, citations
1576 @cindex Selection process
1578 In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then
1579 prompts for a regular expression which will be used to search through
1580 the database and present the list of matches to choose from in a
1581 selection process similar to that for selecting labels
1582 (@pxref{Referencing Labels}).@refill
1584 The regular expression uses an extended syntax: @samp{&&} defines a
1585 logic @code{and} for regular expressions. For example
1586 @samp{Einstein&&Bose} will match all articles which mention
1587 Bose-Einstein condensation, or which are co-authored by Bose and
1588 Einstein. When entering the regular expression, you can complete on
1589 known citation keys.@refill
1591 @cindex @code{\bibliography}
1592 @cindex @code{thebibliography}, LaTeX environment
1593 @cindex @code{BIBINPUTS}, environment variable
1594 @cindex @code{TEXBIB}, environment variable
1595 @b{Ref@TeX{}} prefers to use BibTeX database files specified with a
1596 @code{\bibliography} macro to collect its information. Just like
1597 BibTeX, it will search for the specified files in the current directory
1598 and along the path given in the environment variable @code{BIBINPUTS}.
1599 If you do not use BibTeX, but the document contains an explicit
1600 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
1601 information from there. Note that in this case the information
1602 presented in the selection buffer will just be a copy of relevant
1603 @code{\bibitem} entries, not the structured listing available with
1604 BibTeX database files.@refill
1607 In the selection buffer, the following keys provide special commands. A
1608 summary of this information is always available from the selection
1609 process by pressing @kbd{?}.@refill
1612 @tablesubheading{General}
1614 Show a summary of available commands.
1619 @tablesubheading{Moving around}
1624 Go to previous article.
1626 @tablesubheading{Access to full database entries}
1628 Show the database entry corresponding to the article at point, in
1629 another window. See also the @kbd{f} key.@refill
1632 Toggle follow mode. When follow mode is active, the other window will
1633 always display the full database entry of the current article. This is
1634 equivalent to pressing @key{SPC} after each cursor motion. With BibTeX
1635 entries, follow mode can be rather slow.@refill
1637 @tablesubheading{Selecting entries and creating the citation}
1639 Insert a citation referencing the article at point into the buffer from
1640 which the selection process was started.@refill
1643 @vindex reftex-highlight-selection
1644 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1645 would. See also variable @code{reftex-highlight-selection}, @ref{Options
1649 Mark the current entry. When one or several entries are marked,
1650 pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
1651 @key{RET} behaves like the @kbd{a} key.
1654 Unmark a marked entry.
1657 Accept all (marked) entries in the selection buffer and create a single
1658 @code{\cite} macro referring to them.@refill
1661 Accept all (marked) entries in the selection buffer and create a
1662 separate @code{\cite} macro for each of it.@refill
1665 Enter a citation key with completion. This may also be a key which does
1669 Show insertion point in another window. This is the point from where you
1670 called @code{reftex-citation}.@refill
1672 @tablesubheading{Exiting}
1674 Exit the selection process without inserting a citation into the
1677 @tablesubheading{Updating the buffer}
1680 Start over with a new regular expression. The full database will be
1681 rescanned with the new expression (see also @kbd{r}).@refill
1683 @c FIXME: Should we use something else here? r is usually rescan!
1685 Refine the current selection with another regular expression. This will
1686 @emph{not} rescan the entire database, but just the already selected
1691 @vindex reftex-select-bib-map
1692 In order to define additional commands for this selection process, the
1693 keymap @code{reftex-select-bib-map} may be used.@refill
1695 @node Citation Styles, Citation Info, Creating Citations, Citations
1696 @section Citation Styles
1697 @cindex Citation styles
1698 @cindex Citation styles, @code{natbib}
1699 @cindex Citation styles, @code{harvard}
1700 @cindex Citation styles, @code{chicago}
1701 @cindex @code{natbib}, citation style
1702 @cindex @code{harvard}, citation style
1703 @cindex @code{chicago}, citation style
1705 @vindex reftex-cite-format
1706 The standard LaTeX macro @code{\cite} works well with numeric or simple
1707 key citations. To deal with the more complex task of author-year
1708 citations as used in many natural sciences, a variety of packages has
1709 been developed which define derived forms of the @code{\cite} macro.
1710 @b{Ref@TeX{}} can be configured to produce these citation macros as well by
1711 setting the variable @code{reftex-cite-format}. For the most commonly
1712 used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
1713 be done from the menu, under @code{Ref->Citation Styles}. Since there
1714 are usually several macros to create the citations, executing
1715 @code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
1716 macro. For the Natbib style, this looks like this:
1719 SELECT A CITATION FORMAT
1726 [e] \citep[e.g.][]@{%l@}
1727 [s] \citep[see][]@{%l@}
1728 [a] \citeauthor@{%l@}
1729 [A] \citeauthor*@{%l@}
1733 Following the most generic of these packages, @code{natbib}, the builtin
1734 citation packages always accept the @kbd{t} key for a @emph{textual}
1735 citation (like: @code{Jones et al. (1997) have shown...}) as well as
1736 the @kbd{p} key for a parenthetical citation (like: @code{As shown
1737 earlier (Jones et al, 1997)}).@refill
1739 To make one of these styles the default, customize the variable
1740 @code{reftex-cite-format} or put into @file{.emacs}:
1743 (setq reftex-cite-format 'natbib)
1746 You can also use AUCTeX style files to automatically set the
1747 citation style based on the @code{usepackage} commands in a given
1748 document. @xref{Style Files}, for information on how to set up the style
1749 files correctly.@refill
1751 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
1752 @section Citation Info
1753 @cindex Displaying citations
1754 @cindex Citations, displaying
1755 @cindex Citation info
1756 @cindex Viewing citations
1759 @findex reftex-view-crossref
1760 @findex reftex-mouse-view-crossref
1762 When point is idle on the argument of a @code{\cite} macro, the echo area
1763 will display some information about the article cited there. Note
1764 that the information is only displayed if the echo area is not occupied
1765 by a different message.
1767 @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
1768 entry corresponding to a @code{\cite} macro, or all citation locations
1769 corresponding to a @code{\bibitem} or BibTeX database entry.
1770 @xref{Viewing Cross-References}.@refill
1772 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
1773 @section Chapterbib and Bibunits
1774 @cindex @code{chapterbib}, LaTeX package
1775 @cindex @code{bibunits}, LaTeX package
1776 @cindex Bibliographies, multiple
1778 @code{chapterbib} and @code{bibunits} are two LaTeX packages which
1779 produce multiple bibliographies in a document. This is no problem for
1780 @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
1781 files. If they do not, it is best to have each document part in a
1782 separate file (as it is required for @code{chapterbib} anyway). Then
1783 @b{Ref@TeX{}} will still scan the locally relevant databases correctly. If
1784 you have multiple bibliographies within a @emph{single file}, this may
1785 or may not be the case.
1787 @node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations
1788 @section Citations outside LaTeX
1789 @cindex Citations outside LaTeX
1790 @vindex reftex-default-bibliography
1792 The command @code{reftex-citation} can also be executed outside a LaTeX
1793 buffer. This can be useful to reference articles in the mail buffer and
1794 other documents. You should @emph{not} enter @code{reftex-mode} for
1795 this, just execute the command. The list of BibTeX files will in this
1796 case be taken from the variable @code{reftex-default-bibliography}.
1797 Setting the variable @code{reftex-cite-format} to the symbol
1798 @code{locally} does a decent job of putting all relevant information
1799 about a citation directly into the buffer. Here is the lisp code to add
1800 the @kbd{C-c [} binding to the mail buffer. It also provides a local
1801 binding for @code{reftex-cite-format}.@refill
1807 (define-key mail-mode-map "\C-c["
1811 (let ((reftex-cite-format 'locally))
1812 (reftex-citation))))))
1815 @node Index Support, Viewing Cross-References, Citations, Top
1816 @chapter Index Support
1817 @cindex Index Support
1818 @cindex @code{\index}
1820 LaTeX has builtin support for creating an Index. The LaTeX core
1821 supports two different indices, the standard index and a glossary. With
1822 the help of special LaTeX packages (@file{multind.sty} or
1823 @file{index.sty}), any number of indices can be supported.
1825 Index entries are created with the @code{\index@{@var{entry}@}} macro.
1826 All entries defined in a document are written out to the @file{.aux}
1827 file. A separate tool must be used to convert this information into a
1828 nicely formatted index. Tools used with LaTeX include @code{MakeIndex}
1829 and @code{xindy}.@refill
1831 Indexing is a lot of work and must follow strict conventions, so that
1832 the same word looks the same in all index entries referencing it, and in
1833 order to avoid spurious multiple entries. Therefore, the author of a
1834 document will most likely define special macros to make this easier. To
1835 make @b{Ref@TeX{}} support for indexing possible, these special macros
1836 must be added to @b{Ref@TeX{}}'s configuration (@pxref{Defining Index
1840 * Creating Index Entries::
1841 * Displaying and Editing the Index::
1842 * Builtin Index Macros:: The index macros RefTeX knows about.
1843 * Defining Index Macros:: ... and macros it doesn't.
1846 @node Creating Index Entries, Displaying and Editing the Index, , Index Support
1847 @section Creating Index Entries
1848 @cindex Creating index entries
1849 @cindex Index entries, creating
1851 @findex reftex-index
1853 First you need to make sure that @b{Ref@TeX{}} knows about the index
1854 style being used in the current document. @b{Ref@TeX{}} has builtin
1855 support for the default @code{\index} and @code{\glossary} macros.
1856 Other LaTeX packages, like the @file{multind} or @file{index} package,
1857 redefine the @code{\index} macro to have an additional argument, and
1858 @b{Ref@TeX{}} needs to be configured for those. A sufficiently new
1859 version of AUCTeX (9.10c or later) will do this automatically. If you
1860 really don't use AUCTeX (you should!), this configuration needs to be
1861 done by hand with the menu (@code{Ref->Index Style}), or globally for
1862 all your documents with
1865 (setq reftex-index-macros '((multind)) @r{or}
1866 (setq reftex-index-macros '((index))
1870 @findex reftex-index-selection-or-word
1872 In order to index the current selection or the word at the cursor press
1873 @kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
1874 selection or word @samp{@var{word}} to be replaced with
1875 @samp{\index@{@var{word}@}@var{word}}. The macro which is used
1876 (@code{\index} by default) can be configured with the variable
1877 @code{reftex-index-default-macro}. When the command is called with a
1878 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
1879 generated index entry. Use this to change the case of the word or to
1880 make the entry a subentry, for example by entering
1881 @samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
1882 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
1883 When there is nothing selected and no word at point, this command will
1884 just call @code{reftex-index}, described below.
1886 In order to create a general index entry, press @kbd{C-c <}
1887 (@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the
1888 available index macros and for its arguments. Completion will be
1889 available for the index entry and, if applicable, the index tag. The
1890 index tag is a string identifying one of multiple indices. With the
1891 @file{multind} and @file{index} packages, this tag is the first argument
1892 to the redefined @code{\index} macro.@refill
1894 @findex reftex-index-globally
1896 There is also a command @code{reftex-index-globally}@footnote{This
1897 function is still experimentally and may change or go away.} which
1898 copies an index entry near point to other occurrences of the same word
1899 in the document. @b{Ref@TeX{}} assumes that the word you want to index
1900 is in direct contact with the index macro, e.g.
1901 @samp{\index@{@var{word}@}@var{word}} or
1902 @samp{@var{word}\index@{@var{word}@}}. If there is no such word, it
1903 uses the key argument of the index macro. After making you confirm the
1904 precise search and replace strings, a query-replace over the entire
1905 document will be launched.
1907 @node Displaying and Editing the Index, Builtin Index Macros, Creating Index Entries, Index Support
1908 @section Displaying and Editing the Index
1909 @cindex Displaying the Index
1910 @cindex Editing the Index
1911 @cindex Index entries, creating
1912 @cindex Index, displaying
1913 @cindex Index, editing
1915 @findex reftex-display-index
1917 In order to compile and display the index, press @kbd{C-c >}. If the
1918 document uses multiple indices, @b{Ref@TeX{}} will ask you to select
1919 one. Then, all index entries will be sorted alphabetically and
1920 displayed in a special buffer, the @file{*Index*} buffer. From that
1921 buffer you can check and edit each entry.@refill
1923 The index can be restricted to the current section or the region. Then
1924 only entries in that part of the document will go into the compiled
1925 index. To restrict to the current section, use a numeric prefix
1926 @samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
1927 region, make the region active and use a numeric prefix @samp{3} (press
1928 @kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
1929 restriction can be moved from one section to the next with the @kbd{<}
1930 and @kbd{>} keys.@refill
1932 One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
1933 by searching near the buffer position where it had found to macro during
1934 scanning. If you have several identical index entries in the same
1935 buffer and significant changes have shifted the entries around, you must
1936 rescan the buffer to ensure the correspondence between the
1937 @file{*Index*} buffer and the definition locations. It is therefore
1938 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
1939 frequently while editing the index from the @file{*Index*}
1943 Here is a list of special commands available in the @file{*Index*} buffer. A
1944 summary of this information is always available by pressing
1948 @tablesubheading{General}
1950 Display a summary of commands.
1955 @tablesubheading{Moving around}
1957 Pressing any capital letter will jump to the corresponding section in
1958 the @file{*Index*} buffer. The exclamation mark is special and jumps to
1959 the first entries alphabetically sorted below @samp{A}. These are
1960 usually non-alphanumeric characters.@refill
1962 Go to next entry.@refill
1964 Go to previous entry.@refill
1966 @tablesubheading{Access to document locations}
1968 Show the place in the document where this index entry is defined.@refill
1971 Go to the definition of the current index entry in another
1975 Go to the definition of the current index entry and hide the
1976 @file{*Index*} buffer.@refill
1979 @vindex reftex-index-follow-mode
1980 @vindex reftex-revisit-to-follow
1981 Toggle follow mode. When follow mode is active, the other window will
1982 always show the location corresponding to the line in the @file{*Index*}
1983 buffer at point. This is similar to pressing @key{SPC} after each
1984 cursor motion. The default for this flag can be set with the variable
1985 @code{reftex-index-follow-mode}. Note that only context in files
1986 already visited is shown. @b{Ref@TeX{}} will not visit a file just for
1987 follow mode. See, however, the variable
1988 @code{reftex-revisit-to-follow}.@refill
1990 @tablesubheading{Entry editing}
1992 Edit the current index entry. In the minibuffer, you can edit the
1993 index macro which defines this entry.@refill
1996 Kill the index entry. Currently not implemented because I don't know
1997 how to implement an @code{undo} function for this.@refill
2000 Edit the @var{key} part of the entry. This is the initial part of the
2001 entry which determines the location of the entry in the index.@refill
2004 Edit the @var{attribute} part of the entry. This is the part after the
2005 vertical bar. With @code{MakeIndex}, this part is an encapsulating
2006 macro. With @code{xindy}, it is called @emph{attribute} and is a
2007 property of the index entry that can lead to special formatting. When
2008 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2012 Edit the @var{visual} part of the entry. This is the part after the
2013 @samp{@@} which is used by @code{MakeIndex} to change the visual
2014 appearance of the entry in the index. When called with @kbd{C-u}
2015 prefix, kill the entire @var{visual} part.@refill
2018 Toggle the beginning of page range property @samp{|(} of the
2022 Toggle the end of page range property @samp{|)} of the entry.@refill
2025 Make the current entry a subentry. This command will prompt for the
2026 superordinate entry and insert it.@refill
2029 Remove the highest superordinate entry. If the current entry is a
2030 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2031 (@samp{bbb!ccc}).@refill
2034 Globalize the current entry. This runs a search-and-replace through the
2035 entire document in order to index the same word at other places. Rescan
2036 the document in order to get the new entries into the index buffer. For
2037 details, see the command @code{reftex-index-globally},
2038 @ref{Commands}.@refill
2040 @tablesubheading{Exiting}
2042 Hide the @file{*Index*} buffer.@refill
2045 Kill the @file{*Index*} buffer.@refill
2048 Switch to the Table of Contents buffer of this document.@refill
2050 @tablesubheading{Controlling what gets displayed}
2052 @vindex reftex-index-include-context
2053 Toggle the display of short context in the @file{*Index*} buffer. The
2054 default for this flag can be set with the variable
2055 @code{reftex-index-include-context}.@refill
2058 Restrict the index to a single document section. The corresponding
2059 section number will be displayed in the @code{R<>} indication in the
2060 mode line and in the header of the @file{*Index*} buffer.@refill
2063 Widen the index to contain all entries of the document.@refill
2066 When the index is currently restricted, move the restriction to the
2067 previous section.@refill
2070 When the index is currently restricted, move the restriction to the
2071 next section.@refill
2073 @tablesubheading{Updating the buffer}
2075 Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
2076 document. However, it sorts the entries again, so that edited entries
2077 will move to the correct position.@refill
2080 @vindex reftex-enable-partial-scans
2081 Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When
2082 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
2083 location is defined in, not the entire document.@refill
2086 Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
2090 Switch to a different index (for documents with multiple
2095 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2096 @section Builtin Index Macros
2097 @cindex Builtin index macros
2098 @cindex Index macros, builtin
2099 @vindex reftex-index-macros
2100 @cindex @code{multind}, LaTeX package
2101 @cindex @code{index}, LaTeX package
2102 @cindex LaTeX packages, @code{multind}
2103 @cindex LaTeX packages, @code{index}
2105 @b{Ref@TeX{}} by default recognizes the @code{\index} and
2106 @code{\glossary} macros which are defined in the LaTeX core. It has
2107 also builtin support for the re-implementations of the @code{\index}
2108 macro of the @file{multind} and @file{index} packages. However, since
2109 the different definitions of the @code{\index} macro are incompatible,
2110 you will have to explicitly specify the index style used.
2111 @xref{Creating Index Entries}, for information on how to do that.
2113 @node Defining Index Macros, , Builtin Index Macros, Index Support
2114 @section Defining Index Macros
2115 @cindex Defining Index Macros
2116 @cindex Index macros, defining
2117 @vindex reftex-index-macros
2119 When writing a document with an index you will probably define
2120 additional macros which make entries into the index.
2121 Let's look at an example.
2124 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2125 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2126 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2129 The first macro @code{\ix} typesets its argument in the text and places
2130 it into the index. The second macro @code{\nindex} typesets its
2131 argument in the text and places it into a separate index with the tag
2132 @samp{name}@footnote{We are using the syntax of the @file{index} package
2133 here.}. The last macro also places its argument into the index, but as
2134 subitems under the main index entry @samp{Astronomical Objects}. Here
2135 is how to make @b{Ref@TeX{}} recognize and correctly interpret these
2136 macros, first with Emacs Lisp.
2139 (setq reftex-index-macros
2140 '(("\\ix@{*@}" "idx" ?x "" nil)
2141 ("\\nindex@{*@}" "name" ?n "" nil)
2142 ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil)))
2145 Note that the index tag is @samp{idx} for the main index, and
2146 @samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
2147 for the default index and for the glossary.
2149 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2150 quick identification of these macros when @b{Ref@TeX{}} inserts new
2151 index entries with @code{reftex-index}. These codes need to be
2152 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2153 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2156 The following string is empty unless your macro adds a superordinate
2157 entry to the index key - this is the case for the @code{\astobj} macro.
2159 To do the same thing with customize, you need to fill in the templates
2165 Macro with args: \ix@{*@}
2166 Index Tag : [Value Menu] String: idx
2169 Exclusion hook : nil
2171 Macro with args: \nindex@{*@}
2172 Index Tag : [Value Menu] String: name
2175 Exclusion hook : nil
2177 Macro with args: \astobj@{*@}
2178 Index Tag : [Value Menu] String: idx
2180 Key Prefix : Astronomical Objects!
2181 Exclusion hook : nil
2185 With the macro @code{\ix} defined, you may want to change the default
2186 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2187 This would be done like this
2190 (setq reftex-index-default-macro '(?x "idx" nil))
2193 which specifies that the macro identified with the character @code{?x} (the
2194 @code{\ix} macro) should be used for indexing phrases and words already
2195 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2196 The index tag is "idx", and the final @code{nil} means that it is not
2197 necessary to repeat the phrase outside the macro, because the macro
2198 indexes @emph{and} typesets is argument.
2200 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2201 @chapter Viewing Cross--References
2202 @findex reftex-view-crossref
2203 @findex reftex-mouse-view-crossref
2207 @b{Ref@TeX{}} can display cross--referencing information. This means,
2208 if two document locations are linked, @b{Ref@TeX{}} can display the
2209 matching location(s) in another window. The @code{\label} and @code{\ref}
2210 macros are one way of establishing such a link. Also, a @code{\cite}
2211 macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
2212 database entry.@refill
2214 The feature is invoked by pressing @kbd{C-c &}
2215 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2216 of a macro involved in cross--referencing. You can also click with
2217 @kbd{S-mouse-2} on the macro argument. Here is what will happen for
2218 individual classes of macros:@refill
2224 Display the corresponding label definition. All usual
2225 variants@footnote{all macros that start with @samp{ref} or end with
2226 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2227 cross--reference display. This works also for labels defined in an
2228 external document when the current document refers to them through the
2229 @code{xr} interface (@pxref{xr (LaTeX package)}).@refill
2232 @cindex @code{\label}
2233 @vindex reftex-label-alist
2234 Display a document location which references this label. Pressing
2235 @kbd{C-c &} several times moves through the entire document and finds
2236 all locations. Not only the @code{\label} macro but also other macros
2237 with label arguments (as configured with @code{reftex-label-alist}) are
2238 active for cross--reference display.@refill
2241 @cindex @code{\cite}
2242 Display the corresponding BibTeX database entry or @code{\bibitem}.
2243 All usual variants@footnote{all macros that either start or end with
2244 @samp{cite}} of the @code{\cite} macro are active for cross--reference
2247 @item @code{\bibitem}
2248 @cindex @code{\bibitem}
2249 Display a document location which cites this article. Pressing
2250 @kbd{C-c &} several times moves through the entire document and finds
2251 all locations.@refill
2254 @cindex BibTeX buffer, viewing cite locations from
2255 @cindex Viewing cite locations from BibTeX buffer
2256 @kbd{C-c &} is also active in BibTeX buffers. All locations in a
2257 document where the database entry at point is cited will be displayed.
2258 On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
2259 the document you want to search. Subsequent calls will use the same
2260 document, until you break this link with a prefix argument to @kbd{C-c
2264 @cindex @code{\index}
2265 Display other locations in the document which are marked by an index
2266 macro with the same key argument. Along with the standard @code{\index}
2267 and @code{\glossary} macros, all macros configured in
2268 @code{reftex-index-macros} will be recognized.@refill
2271 @vindex reftex-view-crossref-macros
2272 While the display of cross referencing information for the above
2273 mentioned macros is hard--coded, you can configure additional relations
2274 in the variable @code{reftex-view-crossref-macros}.
2277 @chapter All the Rest
2280 @node RefTeXs Menu, Keybindings, Viewing Cross-References, Top
2281 @section @b{Ref@TeX{}}'s Menu
2282 @cindex RefTeXs Menu
2283 @cindex Menu, in the menu bar
2285 @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
2286 which support this. From this menu you can access all of
2287 @b{Ref@TeX{}}'s commands and a few of its options. There is also a
2288 @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
2289 entire set of options.@refill
2291 @node Keybindings, Faces, RefTeXs Menu, Top
2292 @section Default Keybindings
2293 @cindex Keybindings, summary
2295 Here is a summary of the available keybindings.
2307 @kbd{C-c =} @code{reftex-toc}
2308 @kbd{C-c (} @code{reftex-label}
2309 @kbd{C-c )} @code{reftex-reference}
2310 @kbd{C-c [} @code{reftex-citation}
2311 @kbd{C-c &} @code{reftex-view-crossref}
2312 @kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
2313 @kbd{C-c /} @code{reftex-index-selection-or-word}
2314 @kbd{C-c <} @code{reftex-index}
2315 @kbd{C-c >} @code{reftex-display-index}
2318 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2319 not already used by some other package. @b{Ref@TeX{}} will not override an
2320 existing binding to @kbd{S-mouse-2}.@refill
2322 Personally, I also bind some functions in the users @kbd{C-c} map for
2323 easier access.@refill
2325 @c FIXME: Do we need bindings for the Index macros here as well?
2326 @c C-c i C-c I or so????
2327 @c How about keybindings for reftex-reset-mode and reftex-parse-document?
2336 @kbd{C-c t} @code{reftex-toc}
2337 @kbd{C-c l} @code{reftex-label}
2338 @kbd{C-c r} @code{reftex-reference}
2339 @kbd{C-c c} @code{reftex-citation}
2340 @kbd{C-c v} @code{reftex-view-crossref}
2341 @kbd{C-c s} @code{reftex-search-document}
2342 @kbd{C-c g} @code{reftex-grep-document}
2345 @noindent These keys are reserved for the user, so I cannot bind them by
2346 default. If you want to have these keybindings available, set in your
2349 @vindex reftex-extra-bindings
2351 (setq reftex-extra-bindings t)
2354 @vindex reftex-load-hook
2355 Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook
2356 @code{reftex-load-hook}. For information on the keymaps
2357 which should be used to add keys, see @ref{Keymaps and Hooks}.
2359 @node Faces, AUCTeX, Keybindings, Top
2363 @b{Ref@TeX{}} uses faces when available to structure the selection and
2364 table of contents buffers. It does not create its own faces, but uses
2365 the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will
2366 use faces only when @code{font-lock} is loaded. This seems to be
2367 reasonable because people who like faces will very likely have it
2368 loaded. If you wish to turn off fontification or change the involved
2369 faces, see @ref{Options (Fontification)}.@refill
2371 @node Multifile Documents, Language Support, AUCTeX, Top
2372 @section Multifile Documents
2373 @cindex Multifile documents
2374 @cindex Documents, spread over files
2376 The following is relevant when working with documents spread over many
2381 @b{Ref@TeX{}} has full support for multifile documents. You can edit parts of
2382 several (multifile) documents at the same time without conflicts.
2383 @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
2384 @code{query-replace} on all files which are part of a multifile
2388 @vindex tex-main-file
2390 All files belonging to a multifile document should have a File Variable
2391 (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
2392 standard Emacs LaTeX mode) set to the name of the master file. See the
2393 documentation of your (La)TeX mode and @ref{File Variables,,,emacs, The
2394 GNU Emacs Manual}.@refill
2397 The context of a label definition must be found in the same file as the
2398 label itself in order to be processed correctly by @b{Ref@TeX{}}. The only
2399 exception is that section labels referring to a section statement
2400 outside the current file can still use that section title as
2404 @node Language Support, Finding Files, Multifile Documents, Top
2405 @section Language Support
2406 @cindex Language support
2408 Some parts of @b{Ref@TeX{}} are language dependent. The default
2409 settings work well for English. If you are writing in a different
2410 language, the following hints may be useful:
2414 @vindex reftex-derive-label-parameters
2415 @vindex reftex-abbrev-parameters
2416 The mechanism to derive a label from context includes the abbreviation
2417 of words and omission of unimportant words. These mechanisms may have
2418 to be changed for other languages. See the variables
2419 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2422 @vindex reftex-translate-to-ascii-function
2423 @vindex reftex-label-illegal-re
2424 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
2425 context string from non-ASCII characters in order to make a legal label.
2426 If there should ever be a version of @TeX{} which allows extended
2427 characters @emph{in labels}, then we will have to look at the
2428 variables @code{reftex-translate-to-ascii-function} and
2429 @code{reftex-label-illegal-re}.
2432 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
2433 to guess which label type is required. These @emph{magic words} are
2434 different in every language. For an example of how to add magic words,
2435 see @ref{Adding Magic Words}.
2437 @vindex reftex-multiref-punctuation
2438 @vindex reftex-cite-punctuation
2440 @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
2441 for the author list in citations. Some of this may be language
2442 dependent. See the variables @code{reftex-multiref-punctuation} and
2443 @code{reftex-cite-punctuation}.
2446 @node Finding Files, Optimizations, Language Support, Top
2447 @section Finding Files
2448 @cindex Finding files
2450 In order to find files included in a document via @code{\input} or
2451 @code{\include}, @b{Ref@TeX{}} searches all directories specified in the
2452 environment variable @code{TEXINPUTS}. Similarly, it will search the
2453 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
2454 BibTeX database files.
2456 When searching, @b{Ref@TeX{}} will also expand recursive path
2457 definitions (directories ending in @samp{//} or @samp{!!}). But it will
2458 only search and expand directories @emph{explicitly} given in these
2459 variables. This may cause problems under the following circumstances:
2463 Most TeX system have a default search path for both TeX files and BibTeX
2464 files which is defined in some setup file. Usually this default path is
2465 for system files which @b{Ref@TeX{}} does not need to see. But if your
2466 document needs TeX files or BibTeX database files in a directory only
2467 given in the default search path, @b{Ref@TeX{}} will fail to find them.
2469 Some TeX systems do not use environment variables at all in order to
2470 specify the search path. Both default and user search path are then
2471 defined in setup files.
2475 There are three ways to solve this problem:
2479 Specify all relevant directories explicitly in the environment
2480 variables. If for some reason you don't want to mess with the default
2481 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
2482 variables and configure @b{Ref@TeX{}} to use them instead:
2485 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
2486 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
2490 Specify the full search path directly in @b{Ref@TeX{}}'s variables.
2493 (setq reftex-texpath-environment-variables
2494 '("./inp:/home/cd/tex//:/usr/local/tex//"))
2495 (setq reftex-bibpath-environment-variables
2496 '("/home/cd/tex/lit/"))
2500 Some TeX systems provide stand--alone programs to do the file search just
2501 like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the
2502 @code{kpathsearch} library which provides the command @code{kpsewhich}
2503 to search for files. @b{Ref@TeX{}} can be configured to use this
2504 program. Note that the exact syntax of the @code{kpsewhich}
2505 command depends upon the version of that program.
2508 (setq reftex-use-external-file-finders t)
2509 (setq reftex-external-file-finders
2510 '(("tex" "kpsewhich -format=.tex %f")
2511 ("bib" "kpsewhich -format=.bib %f")))
2515 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
2516 @section Optimizations
2517 @cindex Optimizations
2519 Implementing the principle of least surprises, the default settings of
2520 @b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
2521 when using @b{Ref@TeX{}} for a large project and/or on a small computer,
2522 there are ways to improve speed or memory usage.@refill
2526 @b{Removing Lookup Buffers}@*
2527 @cindex Removing lookup buffers
2528 @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
2529 database files for lookup purposes. These buffers are kept, so that
2530 subsequent use of the same files is fast. If you can't afford keeping
2531 these buffers around, and if you can live with a speed penalty, try
2533 @vindex reftex-keep-temporary-buffers
2535 (setq reftex-keep-temporary-buffers nil)
2539 @b{Partial Document Scans}@*
2540 @cindex Partial documents scans
2541 @cindex Document scanning, partial
2542 A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
2543 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
2544 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
2545 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
2546 re-parsing of the entire document in order to update the parsing
2547 information. For a large document this can be unnecessary, in
2548 particular if only one file has changed. @b{Ref@TeX{}} can be configured
2549 to do partial scans instead of full ones. @kbd{C-u} re-parsing then
2550 does apply only to the current buffer and files included from it.
2551 Likewise, the @kbd{r} key in both the label selection buffer and the
2552 table-of-contents buffer will only prompt scanning of the file in which
2553 the label or section macro near the cursor was defined. Re-parsing of
2554 the entire document is still available by using @kbd{C-u C-u} as a
2555 prefix, or the capital @kbd{R} key in the menus. To use this feature,
2558 @vindex reftex-enable-partial-scans
2560 (setq reftex-enable-partial-scans t)
2564 @b{Saving Parser Information}@*
2565 @cindex Saving parser information
2566 @cindex Parse information, saving to a file
2567 Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
2568 scan, when you start working with a document. To avoid this, parsing
2569 information can be stored in a file. The file @file{MASTER.rel} is used
2570 for storing information about a document with master file
2571 @file{MASTER.tex}. It is written automatically when you kill a buffer
2572 in @code{reftex-mode} or when you exit Emacs. The information is
2573 restored when you begin working with a document in a new editing
2574 session. To use this feature, put into @file{.emacs}:@refill
2576 @vindex reftex-save-parse-info
2578 (setq reftex-save-parse-info t)
2582 @b{Automatic Document Scans}@*
2583 @cindex Automatic document scans
2584 @cindex Document scanning, automatic
2585 At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
2586 document. If this gets into your way, it can be turned off with
2588 @vindex reftex-allow-automatic-rescan
2590 (setq reftex-allow-automatic-rescan nil)
2593 @b{Ref@TeX{}} will then occasionally annotate new labels in the selection
2594 buffer, saying that their position in the label list in uncertain. A
2595 manual document scan will fix this.@refill
2598 @b{Multiple Selection Buffers}@*
2599 @cindex Multiple selection buffers
2600 @cindex Selection buffers, multiple
2601 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
2602 every selection process. In documents with very many labels this can
2603 take several seconds. @b{Ref@TeX{}} provides an option to create a
2604 separate selection buffer for each label type and to keep this buffer
2605 from one selection to the next. These buffers are updated automatically
2606 only when a new label has been added in the buffers category with
2607 @code{reftex-label}. Updating the buffer takes as long as recreating it
2608 - so the time saving is limited to cases where no new labels of that
2609 category have been added. To turn on this feature, use@refill
2611 @vindex reftex-use-multiple-selection-buffers
2613 (setq reftex-use-multiple-selection-buffers t)
2617 @cindex Selection buffers, updating
2618 You can also inhibit the automatic updating entirely. Then the
2619 selection buffer will always pop up very fast, but may not contain the
2620 most recently defined labels. You can always update the buffer by hand,
2621 with the @kbd{g} key. To get this behavior, use instead@refill
2623 @vindex reftex-auto-update-selection-buffers
2625 (setq reftex-use-multiple-selection-buffers t
2626 reftex-auto-update-selection-buffers nil)
2632 @b{As a summary}, here are the settings I recommend for heavy use of
2633 @b{Ref@TeX{}} with large documents:
2637 (setq reftex-enable-partial-scans t
2638 reftex-save-parse-info t
2639 reftex-use-multiple-selection-buffers t)
2644 @node AUCTeX, Multifile Documents, Faces, Top
2645 @section @w{AUC @TeX{}}
2646 @cindex @code{AUCTeX}, Emacs package
2647 @cindex Emacs packages, @code{AUCTeX}
2649 AUCTeX is without doubt the best major mode for editing TeX and LaTeX
2650 files with Emacs. If AUCTeX is not part of you Emacs distribution, you
2651 can get it@footnote{XEmacs 21.x users may
2652 want to install the corresponding XEmacs package.} by ftp from the
2653 @uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.
2656 * AUCTeX-RefTeX Interface:: How both packages work together
2657 * Style Files:: AUCTeX's style files can support RefTeX
2658 * Bib-Cite:: Hypertext reading of a document
2661 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
2662 @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
2664 @b{Ref@TeX{}} contains code to interface with AUCTeX. When this
2665 interface is turned on, both packages will interact closely. Instead of
2666 using @b{Ref@TeX{}}'s commands directly, you can then also use them
2667 indirectly as part of the AUCTeX
2668 environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
2669 needed for all of this to work. Parts of it work also with earlier
2670 versions.}. The interface is turned on with@refill
2673 (setq reftex-plug-into-AUCTeX t)
2676 If you need finer control about which parts of the interface are used
2677 and which not, read the docstring of the variable
2678 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
2679 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
2681 The following list describes the individual parts of the interface.
2685 @findex reftex-label
2686 @vindex LaTeX-label-function, @r{AUCTeX}
2689 @findex LaTeX-section, @r{AUCTeX}
2690 @findex TeX-insert-macro, @r{AUCTeX}
2691 @b{AUCTeX calls @code{reftex-label} to insert labels}@*
2692 When a new section is created with @kbd{C-c C-s}, or a new environment
2693 is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
2694 go with it. With the interface, @code{reftex-label} is called instead.
2695 For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
2696 @b{Ref@TeX{}} will insert
2706 without further prompts.
2708 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
2709 will offer its default label which is derived from the section title.
2712 @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
2713 When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
2714 have to rescan the buffer in order to see it.@refill
2717 @findex reftex-arg-label
2718 @findex TeX-arg-label, @r{AUCTeX function}
2719 @findex reftex-arg-ref
2720 @findex TeX-arg-ref, @r{AUCTeX function}
2721 @findex reftex-arg-cite
2722 @findex TeX-arg-cite, @r{AUCTeX function}
2723 @findex reftex-arg-index
2724 @findex TeX-arg-index, @r{AUCTeX function}
2725 @findex TeX-insert-macro, @r{AUCTeX function}
2726 @kindex C-c @key{RET}
2727 @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
2728 interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
2729 macro arguments. Internally, it uses the functions
2730 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
2731 prompt for arguments which are labels, citation keys and index entries.
2732 The interface takes over these functions@footnote{@code{fset} is used to
2733 do this, which is not reversible. However, @b{Ref@TeX{}} implements the
2734 old functionality when you later decide to turn off the interface.} and
2735 supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For
2736 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
2737 will supply its label selection process (@pxref{Referencing
2741 @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
2742 @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
2745 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
2746 @subsection Style Files
2747 @cindex Style files, AUCTeX
2748 @findex TeX-add-style-hook, @r{AUCTeX}
2749 Style files are Emacs Lisp files which are evaluated by AUCTeX in
2750 association with the @code{\documentclass} and @code{\usepackage}
2751 commands of a document. Support for @b{Ref@TeX{}} in such a style file
2752 is useful when the LaTeX style defines macros or environments connected
2753 with labels, citations, or the index. Many style files
2754 (e.g. @file{amsmath.el} or @file{natbib.el}) distributed with AUCTeX
2755 already support @b{Ref@TeX{}} in this way.@refill
2757 Before calling a @b{Ref@TeX{}} function, the style hook should always
2758 test for the availability of the function, so that the style file will
2759 also work for people who do not use @b{Ref@TeX{}}. @refill
2761 Additions made with style files in the way described below remain local
2762 to the current document. For example, if one package uses AMSTeX, the
2763 style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
2764 this will not affect other documents.@refill
2766 @findex reftex-add-label-environments
2767 @findex reftex-add-to-label-alist
2768 A style hook may contain calls to
2769 @code{reftex-add-label-environments}@footnote{This used to be the
2770 function @code{reftex-add-to-label-alist} which is still available as an
2771 alias for compatibility.} which defines additions to
2772 @code{reftex-label-alist}. The argument taken by this function must have
2773 the same format as @code{reftex-label-alist}. The @file{amsmath.el}
2774 style file of AUCTeX for example contains the following:@refill
2778 (TeX-add-style-hook "amsmath"
2780 (if (fboundp 'reftex-add-label-environments)
2781 (reftex-add-label-environments '(AMSTeX)))))
2786 @findex LaTeX-add-environments, @r{AUCTeX}
2787 while a package @code{myprop} defining a @code{proposition} environment
2788 with @code{\newtheorem} might use@refill
2792 (TeX-add-style-hook "myprop"
2794 (LaTeX-add-environments '("proposition" LaTeX-env-label))
2795 (if (fboundp 'reftex-add-label-environments)
2796 (reftex-add-label-environments
2797 '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
2798 ("Proposition" "Prop.")))))))
2802 @findex reftex-set-cite-format
2803 Similarly, a style hook may contain a call to
2804 @code{reftex-set-cite-format} to set the citation format. The style
2805 file @file{natbib.el} for the Natbib citation style does switch
2806 @b{Ref@TeX{}}'s citation format like this:@refill
2809 (TeX-add-style-hook "natbib"
2811 (if (fboundp 'reftex-set-cite-format)
2812 (reftex-set-cite-format 'natbib))))
2815 @findex reftex-add-index-macros
2816 The hook may contain a call to @code{reftex-add-index-macros} to
2817 define additional @code{\index}-like macros. The argument must have
2818 the same format as @code{reftex-index-macros}. It may be a symbol, to
2819 trigger support for one of the builtin index packages. For example,
2820 the style @file{multind.el} contains
2823 (TeX-add-style-hook "multind"
2825 (and (fboundp 'reftex-add-index-macros)
2826 (reftex-add-index-macros '(multind)))))
2829 If you have your own package @file{myindex} which defines the
2830 following macros to be used with the LaTeX @file{index.sty} file
2832 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
2833 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
2836 you could write this in the style file @file{myindex.el}:
2839 (TeX-add-style-hook "myindex"
2842 '("molec" TeX-arg-index)
2843 '("aindex" TeX-arg-index))
2844 (if (fboundp 'reftex-add-index-macros)
2845 (reftex-add-index-macros
2846 '(("molec@{*@}" "idx" ?m "Molecules!" nil)
2847 ("aindex@{*@}" "author" ?a "" nil))))))
2850 @findex reftex-add-section-levels
2851 Finally the hook may contain a call to @code{reftex-add-section-levels}
2852 to define additional section statements. For example, the FoilTeX class
2853 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
2854 is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
2857 (TeX-add-style-hook "foils"
2859 (if (fboundp 'reftex-add-section-levels)
2860 (reftex-add-section-levels '(("foilhead" . 3)
2861 ("rotatefoilhead" . 3))))))
2864 @node Bib-Cite, , Style Files, AUCTeX
2865 @subsection Bib-Cite
2866 @cindex @code{bib-cite}, Emacs package
2867 @cindex Emacs packages, @code{bib-cite}
2869 Once you have written a document with labels, references and citations,
2870 it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has
2871 some support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
2872 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
2873 @code{reftex-search-document}. A somewhat fancier interface with mouse
2874 highlighting is provided (among other things) by Peter S. Galbraith's
2875 @file{bib-cite.el}. There is some overlap in the functionalities of
2876 Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with
2879 Bib-cite version 3.06 and later can be configured so that bib-cite's
2880 mouse functions use @b{Ref@TeX{}} for displaying references and citations.
2881 This can be useful in particular when working with the LaTeX @code{xr}
2882 package or with an explicit @code{thebibliography} environment (rather
2883 than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To
2884 make use of this feature, try@refill
2886 @vindex bib-cite-use-reftex-view-crossref
2888 (setq bib-cite-use-reftex-view-crossref t)
2892 @node Problems and Work-Arounds, Imprint, Optimizations, Top
2893 @section Problems and Work-arounds
2894 @cindex Problems and work-arounds
2898 @b{LaTeX commands}@*
2899 @cindex LaTeX commands, not found
2900 @code{\input}, @code{\include}, @code{\bibliography} and @code{\section}
2901 (etc.) statements have to be first on a line (except for white space).@refill
2904 @b{Commented regions}@*
2905 @cindex Labels, commented out
2906 @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
2907 make duplicates of such labels. This is considered to be a feature.@refill
2910 @b{Wrong section numbers}@*
2911 @cindex Section numbers, wrong
2912 @vindex reftex-enable-partial-scans
2913 When using partial scans (@code{reftex-enable-partial-scans}), the section
2914 numbers in the table of contents may eventually become wrong. A full
2915 scan will fix this.@refill
2918 @b{Local settings}@*
2919 @cindex Settings, local
2920 @findex reftex-add-label-environments
2921 @findex reftex-set-cite-format
2922 @findex reftex-add-section-levels
2923 The label environment definitions in @code{reftex-label-alist} are
2924 global and apply to all documents. If you need to make definitions
2925 local to a document, because they would interfere with settings in other
2926 documents, you should use AUCTeX and set up style files with calls to
2927 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
2928 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
2929 Settings made with these functions remain local to the current
2930 document. @xref{AUCTeX}.@refill
2933 @b{Funny display in selection buffer}@*
2934 @cindex @code{x-symbol}, Emacs package
2935 @cindex Emacs packages, @code{x-symbol}
2936 @cindex @code{isotex}, Emacs package
2937 @cindex Emacs packages, @code{isotex}
2938 @cindex @code{iso-cvt}, Emacs package
2939 @cindex Emacs packages, @code{iso-cvt}
2940 When using packages which make the buffer representation of a file
2941 different from its disk representation (e.g. x-symbol, isotex,
2942 iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
2943 reflects the disk state of a file. This happens only in @emph{unvisited}
2944 parts of a multifile document, because @b{Ref@TeX{}} visits these files
2945 literally for speed reasons. Then both short context and section
2946 headings may look different from what you usually see on your screen.
2947 In rare cases @code{reftex-toc} may have problems to jump to an affected
2948 section heading. There are three possible ways to deal with
2952 @vindex reftex-keep-temporary-buffers
2953 @code{(setq reftex-keep-temporary-buffers t)}@*
2954 This implies that @b{Ref@TeX{}} will load all parts of a multifile
2955 document into Emacs (i.e. there won't be any temporary buffers).@refill
2957 @vindex reftex-initialize-temporary-buffers
2958 @code{(setq reftex-initialize-temporary-buffers t)}@*
2959 This means full initialization of temporary buffers. It involves
2960 a penalty when the same unvisited file is used for lookup often.@refill
2962 Set @code{reftex-initialize-temporary-buffers} to a list of hook
2963 functions doing a minimal initialization.@refill
2965 @vindex reftex-refontify-context
2966 See also the variable @code{reftex-refontify-context}.
2969 @b{Labels as arguments to \begin}@*
2970 @cindex @code{pf}, LaTeX package
2971 @cindex LaTeX packages, @code{pf}
2972 Some packages use an additional argument to a @code{\begin} macro
2973 to specify a label. E.g. Lamport's @file{pf.sty} uses both
2975 \step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
2981 We need to trick @b{Ref@TeX{}} into swallowing this:
2985 ;; Configuration for Lamport's pf.sty
2986 (setq reftex-label-alist
2987 '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
2988 ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
2993 The first line is just a normal configuration for a macro. For the
2994 @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
2995 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
2996 argument (which really is a second argument to the macro @code{\begin})
2997 as a label of type @code{?p}. Argument count for this macro starts only
2998 after the @samp{@{step+@}}, also when specifying how to get
3002 @b{Idle timers in XEmacs}@*
3003 @cindex Idle timer restart
3004 @vindex reftex-use-itimer-in-xemacs
3005 In XEmacs, idle timer restart does not work reliably after fast
3006 keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command
3007 hook to start the timer used for automatic crossref information. When
3008 this bug gets fixed, a real idle timer can be requested with
3010 (setq reftex-use-itimer-in-xemacs t)
3016 @cindex Keybindings, problems with Viper mode
3017 @findex viper-harness-minor-mode
3018 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3019 @b{Ref@TeX{}}'s keymaps with@refill
3022 (viper-harness-minor-mode "reftex")
3028 @node Imprint, Commands, Problems and Work-Arounds, Top
3032 @cindex Acknowledgments
3035 @cindex @code{http}, @b{Ref@TeX{}} home page
3036 @cindex @code{ftp}, @b{Ref@TeX{}} site
3038 @b{Ref@TeX{}} was written by @i{@value{AUTHOR}}
3039 @email{@value{AUTHOR-EMAIL}}, with contributions by @i{Stephen
3040 Eglen}. @b{Ref@TeX{}} is currently maintained by @refill
3043 @value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}}
3045 If you have questions about @b{Ref@TeX{}}, there are several Usenet
3046 groups which have competent readers: @code{comp.emacs},
3047 @code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}.
3048 You can also write directly to the maintainer.
3050 If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
3051 to contribute code or ideas, please
3052 @uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}. Remember
3053 to provide all necessary information such as version numbers of Emacs
3054 and @b{Ref@TeX{}}, and the relevant part of your configuration in
3055 @file{.emacs}. When reporting a bug which throws an exception, please
3056 include a backtrace if you know how to produce one.
3058 @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
3059 It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
3060 21.x users want to install the corresponding plugin package which is
3061 available from the XEmacs @code{ftp} site. See the XEmacs 21.x
3062 documentation on package installation for details.@refill
3064 Users of earlier Emacs distributions (including Emacs 19) can get a
3065 @b{Ref@TeX{}} distribution from the
3066 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainers
3067 webpage}. Note that the Emacs 19 version supports many but not all
3068 features described in this manual.@refill
3070 Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
3071 developing it with their reports. In particular thanks to
3072 @i{Fran Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl
3073 Eichwalder, Peter Galbraith, Kai Grossjohann, Dieter Kraft, Adrian Lanz,
3074 Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat,
3075 Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof,
3076 Christoph Wedler, Alan Williams}.@refill
3078 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3079 @file{bib-cite.el}.@refill
3081 Finally thanks to @i{Uwe Bolick} who first got me (some years ago) into
3082 supporting LaTeX labels and references with an editor (which was
3083 MicroEmacs at the time).@refill
3085 @node Commands, Options, Imprint, Top
3087 @cindex Commands, list of
3089 Here is a summary of @b{Ref@TeX{}}'s commands. All commands are available
3090 from the @code{Ref} menu. For keybindings, @pxref{Keybindings}.
3092 @deffn Command reftex-toc
3093 Show the table of contents for the current document. When called with
3094 one ore two @kbd{C-u} prefixes, rescan the document first.@refill
3097 @deffn Command reftex-label
3098 Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
3099 document rescan first.
3102 @deffn Command reftex-reference
3103 Start a selection process to select a label, and insert a reference to
3104 it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
3107 @deffn Command reftex-citation
3108 Make a citation using BibTeX database files. After prompting for a regular
3109 expression, scans the buffers with BibTeX entries (taken from the
3110 @code{\bibliography} command or a @code{thebibliography} environment)
3111 and offers the matching entries for selection. The selected entry is
3112 formated according to @code{reftex-cite-format} and inserted into the
3114 When called with one or two @kbd{C-u} prefixes, first rescans the
3115 document. When called with a numeric prefix, make that many citations.
3116 When called with point inside the braces of a @code{\cite} command, it
3117 will add another key, ignoring the value of
3118 @code{reftex-cite-format}.@refill @*
3119 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3120 as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
3121 both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
3122 on knows citation keys is possible. @samp{=} is a good regular
3123 expression to match all entries in all files.@refill
3126 @deffn Command reftex-index
3127 Query for an index macro and insert it along with its arguments. The
3128 index macros available are those defined in @code{reftex-index-macro} or
3129 by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
3130 style file. @b{Ref@TeX{}} provides completion for the index tag and the
3131 index key, and will prompt for other arguments.@refill
3134 @deffn Command reftex-index-selection-or-word
3135 Put current selection or the word near point into the default index
3136 macro. This uses the information in @code{reftex-index-default-macro}
3137 to make an index entry. The phrase indexed is the current selection or
3138 the word near point. When called with one @kbd{C-u} prefix, let the
3139 user have a chance to edit the index entry. When called with 2
3140 @kbd{C-u} as prefix, also ask for the index macro and other stuff. When
3141 called inside TeX math mode as determined by the @file{texmathp.el}
3142 library which is part of AUCTeX, the string is first processed with the
3143 @code{reftex-index-math-format}, which see.@refill
3146 @deffn Command reftex-display-index
3147 Display a buffer with an index compiled from the current document.
3148 When the document has multiple indices, first prompts for the correct one.
3149 When index support is turned off, offer to turn it on.
3150 With one or two @kbd{C-u} prefixes, rescan document first.
3151 With prefix 2, restrict index to current document section.
3152 With prefix 3, restrict index to active region.@refill
3155 @deffn Command reftex-index-globally
3156 Index a word with a global search and replace. This works very much
3157 like @code{reftex-query-replace-document}, but the defaults for the
3158 search and replace strings are derived from local context. When there
3159 is an index entry, we try to index similar words. The word to search
3160 for is the word in direct contact with the index macro (like
3161 @samp{\index@{@var{word}@}@var{word}} or
3162 @samp{@var{word}\index@{@var{word}@}}). If there is no such word, we
3163 use the the index key. The replacement text is the index macro with all
3164 its arguments and the attached word. When there is no index entry at
3165 point, we search for the word near point and propose to index it like
3166 this: @samp{\index@{@var{word}@}@var{word}}. You get a chance to edit
3167 the search and replacement strings.@refill
3170 @deffn Command reftex-view-crossref
3171 View cross reference of macro at point. Point must be on the @var{key}
3172 argument. Works with the macros @code{\label}, @code{\ref},
3173 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3174 these. Where it makes sense, subsequent calls show additional
3175 locations. See also the variable @code{reftex-view-crossref-extra} and
3176 the command @code{reftex-view-crossref-from-bibtex}. With one or two
3177 @kbd{C-u} prefixes, enforce rescanning of the document. With argument
3178 2, select the window showing the cross reference.
3181 @deffn Command reftex-view-crossref-from-bibtex
3182 View location in a LaTeX document which cites the BibTeX entry at point.
3183 Since BibTeX files can be used by many LaTeX documents, this function
3184 prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
3185 link to a document, call the function with with a prefix arg. Calling
3186 this function several times find successive citation locations.
3189 @deffn Command reftex-create-tags-file
3190 Create TAGS file by running @code{etags} on the current document. The
3191 TAGS file is also immediately visited with
3192 @code{visit-tags-table}.@refill
3195 @deffn Command reftex-grep-document
3196 Run grep query through all files related to this document.
3197 With prefix arg, force to rescan document.
3198 No active TAGS table is required.@refill
3201 @deffn Command reftex-search-document
3202 Regexp search through all files of the current document.
3203 Starts always in the master file. Stops when a match is found.
3204 No active TAGS table is required.@refill
3207 @deffn Command reftex-query-replace-document
3208 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3209 document. With prefix arg, replace only word-delimited matches. No
3210 active TAGS table is required.@refill
3213 @deffn Command reftex-change-label
3214 Query replace @var{from} with @var{to} in all @code{\label} and
3215 @code{\ref} commands. Works on the entire multifile document. No
3216 active TAGS table is required.@refill
3219 @deffn Command reftex-renumber-simple-labels
3220 Renumber all simple labels in the document to make them sequentially.
3221 Simple labels are the ones created by RefTeX, consisting only of the
3222 prefix and a number. After the command completes, all these labels will
3223 have sequential numbers throughout the document. Any references to the
3224 labels will be changed as well. For this, @b{Ref@TeX{}} looks at the
3225 arguments of any macros which either start or end with the string
3226 @samp{ref}. This command should be used with care, in particular in
3227 multifile documents. You should not use it if another document refers
3228 to this one with the @code{xr} package.@refill
3231 @deffn Command reftex-find-duplicate-labels
3232 Produce a list of all duplicate labels in the document.@refill
3235 @deffn Command reftex-customize
3236 Run the customize browser on the @b{Ref@TeX{}} group.
3238 @deffn Command reftex-show-commentary
3239 Show the commentary section from @file{reftex.el}.
3241 @deffn Command reftex-info
3242 Run info on the top @b{Ref@TeX{}} node.
3244 @deffn Command reftex-parse-document
3245 Parse the entire document in order to update the parsing information.
3247 @deffn Command reftex-reset-mode
3248 Enforce rebuilding of several internal lists and variables. Also
3249 removes the parse file associated with the current document.
3252 @node Options, Keymaps and Hooks, Commands, Top
3253 @chapter Options, Keymaps, Hooks
3254 @cindex Options, list of
3256 Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All
3257 variables have customize support - so if you are not familiar with Emacs
3258 Lisp (and even if you are) you might find it more comfortable to use
3259 @code{customize} to look at and change these variables. @kbd{M-x
3260 reftex-customize} will get you there.@refill
3263 * Options (Table of Contents)::
3264 * Options (Defining Label Environments)::
3265 * Options (Creating Labels)::
3266 * Options (Referencing Labels)::
3267 * Options (Creating Citations)::
3268 * Options (Index Support)::
3269 * Options (Viewing Cross-References)::
3270 * Options (Finding Files)::
3271 * Options (Optimizations)::
3272 * Options (Fontification)::
3276 @node Options (Table of Contents), Options (Defining Label Environments), , Options
3277 @section Table of Contents
3278 @cindex Options, table of contents
3279 @cindex Table of contents, options
3281 @defopt reftex-toc-keep-other-windows
3282 Non-@code{nil} means, split the selected window to display the
3283 @file{*toc*} buffer. This helps to keep the window configuration, but
3284 makes the @file{*toc*} small. When @code{nil}, all other windows except
3285 the selected one will be deleted, so that the @file{*toc*} window fills
3286 half the frame.@refill
3289 @defopt reftex-toc-include-file-boundaries
3290 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3291 This flag can be toggled from within the @file{*toc*} buffer with the
3295 @defopt reftex-toc-include-labels
3296 Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
3297 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3301 @defopt reftex-toc-include-index-entries
3302 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3303 This flag can be toggled from within the @file{*toc*} buffer with the
3307 @defopt reftex-toc-include-context
3308 Non-@code{nil} means, include context with labels in the @file{*toc*}
3309 buffer. Context will only be shown if the labels are visible as well.
3310 This flag can be toggled from within the @file{*toc*} buffer with the
3314 @defopt reftex-toc-follow-mode
3315 Non-@code{nil} means, point in @file{*toc*} buffer (the
3316 table-of-contents buffer) will cause other window to follow. The other
3317 window will show the corresponding part of the document. This flag can
3318 be toggled from within the @file{*toc*} buffer with the @kbd{f}
3322 @deffn {Normal Hook} reftex-toc-mode-hook
3323 Normal hook which is run when a @file{*toc*} buffer is
3327 @deffn Keymap reftex-toc-map
3328 The keymap which is active in the @file{*toc*} buffer.
3329 (@pxref{Table of Contents}).@refill
3332 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
3333 @section Defining Label Environments
3334 @cindex Options, defining label environments
3335 @cindex Defining label environments, options
3337 @defopt reftex-default-label-alist-entries
3338 Default label alist specifications. It is a list of symbols with
3339 associations in the constant @code{reftex-label-alist-builtin}.
3340 @code{LaTeX} should always be the last entry.@refill
3343 @defopt reftex-label-alist
3344 Set this variable to define additions and changes to the defaults in
3345 @code{reftex-default-label-alist-entries}. The only things you
3346 @emph{must not} change is that @code{?s} is the type indicator for
3347 section labels, and @key{SPC} for the @code{any} label type. These are
3348 hard-coded at other places in the code.@refill
3350 The value of the variable must be a list of items. Each item is a list
3351 itself and has the following structure:
3354 (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
3355 @var{context-method} (@var{magic-word} ... ))
3358 Each list entry describes either an environment carrying a counter for
3359 use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
3360 label as (or inside) one of its arguments. The elements of each list
3364 @item @var{env-or-macro}
3365 Name of the environment (like @samp{table}) or macro (like
3366 @samp{\myfig}). For macros, indicate the arguments, as in
3367 @samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
3368 arguments, a star to mark the label argument, if any. The macro does
3369 not have to have a label argument - you could also use
3370 @samp{\label@{...@}} inside one of its arguments.@refill
3372 Special names: @code{section} for section labels, @code{any} to define a
3373 group which contains all labels.@refill
3375 This may also be a function to do local parsing and identify point to be
3376 in a a non-standard label environment. The function must take an
3377 argument @var{bound} and limit backward searches to this value. It
3378 should return either nil or a cons cell @code{(@var{function}
3379 . @var{position})} with the function symbol and the position where the
3380 special environment starts. See the Info documentation for an
3383 Finally this may also be @code{nil} if the entry is only meant to change
3384 some settings associated with the type indicator character (see
3387 @item @var{type-key}
3388 Type indicator character, like @code{?t}, must be a printable ASCII
3389 character. The type indicator is a single character which defines a
3390 label type. Any label inside the environment or macro is assumed to
3391 belong to this type. The same character may occur several times in this
3392 list, to cover cases in which different environments carry the same
3393 label type (like @code{equation} and @code{eqnarray}). If the type
3394 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
3395 the macro defines neutral labels just like @code{\label}. In this case
3396 the reminder of this entry is ignored.@refill
3398 @item @var{label-prefix}
3399 Label prefix string, like @samp{tab:}. The prefix is a short string
3400 used as the start of a label. It may be the empty string. The prefix
3401 may contain the following @samp{%} escapes:@refill
3404 %f Current file name, directory and extension stripped.
3405 %F Current file name relative to master file directory.
3406 %u User login name, on systems which support this.
3407 %S A section prefix derived with variable @code{reftex-section-prefixes}.
3411 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
3412 @samp{eq:intro:}.@refill
3414 @item @var{reference-format}
3415 Format string for reference insert in buffer. @samp{%s} will be
3416 replaced by the label. When the format starts with @samp{~}, this
3417 @samp{~} will only be inserted when the character before point is
3418 @emph{not} a whitespace.@refill
3420 @item @var{context-method}
3421 Indication on how to find the short context.
3424 If @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill
3429 the section heading for section labels.
3431 text following the @samp{\begin@{...@}} statement of environments (not
3432 a good choice for environments like eqnarray or enumerate, where one has
3433 several labels in a single environment).@refill
3435 text after the macro name (starting with the first arg) for
3439 If an integer, use the nth argument of the macro. As a special case,
3440 1000 means to get text after the last macro argument.@refill
3442 If a string, use as regexp to search @emph{backward} from the label.
3443 Context is then the text following the end of the match. E.g. putting
3444 this to @samp{\\caption[[@{]} will use the caption in a figure or table
3445 environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
3448 If any of @code{caption}, @code{item}, @code{eqnarray-like},
3449 @code{alignat-like}, this symbol will internally be translated into an
3450 appropriate regexp (see also the variable
3451 @code{reftex-default-context-regexps}).@refill
3453 If a function, call this function with the name of the environment/macro
3454 as argument. On call, point will be just after the @code{\label} macro.
3455 The function is expected to return a suitable context string. It should
3456 throw an exception (error) when failing to find context. As an example,
3457 here is a function returning the 10 chars following the label macro as
3461 (defun my-context-function (env-or-mac)
3462 (if (> (point-max) (+ 10 (point)))
3463 (buffer-substring (point) (+ 10 (point)))
3464 (error "Buffer too small")))
3468 Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
3469 menu, and to derive a label string. If you want to use a different
3470 method for each of these, specify them as a dotted pair.
3471 E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
3472 display, and text from the default position (@code{t}) to derive a label
3473 string. This is actually used for section labels.@refill
3475 @item @var{magic-word-list}
3476 List of magic words which identify a reference to be of this type. If
3477 the word before point is equal to one of these words when calling
3478 @code{reftex-reference}, the label list offered will be automatically
3479 restricted to labels of the correct type. If the first element of this
3480 word--list is the symbol `regexp', the strings are interpreted as regular
3481 expressions@footnote{Careful: @b{Ref@TeX{}} will add stuff to the
3482 beginning and end of these regular expressions.}.@refill
3485 If the type indicator characters of two or more entries are the same,
3486 @b{Ref@TeX{}} will use@refill
3489 the first non-@code{nil} format and prefix
3491 the magic words of all involved entries.
3494 Any list entry may also be a symbol. If that has an association in
3495 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
3496 spliced into the list. However, builtin defaults should normally be set
3497 with the variable @code{reftex-default-label-alist-entries}.@refill
3500 @defopt reftex-max-section-depth
3501 Maximum depth of section levels in document structure.
3502 Standard LaTeX needs 7, default is 12.
3505 @defopt reftex-section-levels
3506 Commands and levels used for defining sections in the document. The
3507 @code{car} of each cons cell is the name of the section macro. The
3508 @code{cdr} is a number indicating its level. A negative level means the
3509 same as the positive value, but the section will never get a
3510 number. The @code{cdr} amy also be a function which then has to return
3514 @defopt reftex-section-prefixes
3515 Prefixes for section labels. When the label prefix given in an entry in
3516 @code{reftex-label-alist} contains @samp{%S}, this list is used to
3517 determine the correct prefix string depending on the current section
3518 level. The list is an alist, with each entry of the form
3519 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
3520 names like @samp{chapter}, integer section levels (as given in
3521 @code{reftex-section-levels}), and @code{t} for the default.
3524 @defopt reftex-default-context-regexps
3525 Alist with default regular expressions for finding context. The emacs
3526 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
3527 to calculate the final regular expression - so @samp{%s} will be
3528 replaced with the environment or macro.@refill
3531 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
3532 @section Creating Labels
3533 @cindex Options, creating labels
3534 @cindex Creating labels, options
3536 @defopt reftex-insert-label-flags
3537 Flags governing label insertion. The value has the form
3540 (@var{derive} @var{prompt})
3543 If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
3544 label from context. A section label for example will be derived from
3545 the section heading. The conversion of the context to a legal label is
3546 governed by the specifications given in
3547 @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
3548 the default label will consist of the prefix and a unique number, like
3549 @samp{eq:23}.@refill
3551 If @var{prompt} is @code{t}, the user will be prompted for a label
3552 string. When @var{prompt} is @code{nil}, the default label will be
3553 inserted without query.@refill
3555 So the combination of @var{derive} and @var{prompt} controls label
3556 insertion. Here is a table describing all four possibilities:@refill
3560 @var{derive} @var{prompt} @var{action}
3561 -----------------------------------------------------------
3562 nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
3563 nil t @r{Prompt for label.}
3564 t nil @r{Derive a label from context and insert. No query.}
3565 t t @r{Derive a label from context, prompt for confirmation.}
3569 Each flag may be set to @code{t}, @code{nil}, or a string of label type
3570 letters indicating the label types for which it should be true. Thus,
3571 the combination may be set differently for each label type. The default
3572 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
3573 headings (with confirmation). Prompt for figure and table labels. Use
3574 simple labels without confirmation for everything else.@refill
3576 The available label types are: @code{s} (section), @code{f} (figure),
3577 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
3578 (footnote), @code{N} (endnote) plus any definitions in
3579 @code{reftex-label-alist}.@refill
3582 @deffn Hook reftex-format-label-function
3583 If non-@code{nil}, should be a function which produces the string to
3584 insert as a label definition. The function will be called with two
3585 arguments, the @var{label} and the @var{default-format} (usually
3586 @samp{\label@{%s@}}). It should return the string to insert into the
3590 @deffn Hook reftex-string-to-label-function
3591 Function to turn an arbitrary string into a legal label.
3592 @b{Ref@TeX{}}'s default function uses the variable
3593 @code{reftex-derive-label-parameters}.@refill
3596 @deffn Hook reftex-translate-to-ascii-function
3597 Filter function which will process a context string before it is used to
3598 derive a label from it. The intended application is to convert ISO or
3599 Mule characters into something legal in labels. The default function
3600 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
3601 characters. X-Symbol (>=2.6) sets this variable to the much more
3602 general @code{x-symbol-translate-to-ascii}.@refill
3605 @defopt reftex-derive-label-parameters
3606 Parameters for converting a string into a label. This variable is a
3607 list of the following items:@refill
3610 Number of words to use.
3612 Maximum number of characters in a label string.
3614 @code{nil}: Throw away any words containing characters illegal in labels.@*
3615 @code{t}: Throw away only the illegal characters, not the whole word.
3617 @code{nil}: Never abbreviate words.@*
3618 @code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
3619 @code{1}: Abbreviate words if necessary to shorten label string.
3620 @item @var{separator}
3621 String separating different words in the label.
3622 @item @var{ignorewords}
3623 List of words which should not be part of labels.
3624 @item @var{downcase}
3625 @code{t}: Downcase words before putting them into the label.@*
3629 @defopt reftex-label-illegal-re
3630 Regexp matching characters not legal in labels.
3633 @defopt reftex-abbrev-parameters
3634 Parameters for abbreviation of words. A list of four parameters.@refill
3636 @item @var{min-chars}
3637 Minimum number of characters remaining after abbreviation.
3638 @item @var{min-kill}
3639 Minimum number of characters to remove when abbreviating words.@refill
3641 Character class before abbrev point in word.@refill
3643 Character class after abbrev point in word.@refill
3647 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
3648 @section Referencing Labels
3649 @cindex Options, referencing labels
3650 @cindex Referencing labels, options
3652 @defopt reftex-label-menu-flags
3653 List of flags governing the label menu makeup. The flags are:
3655 @item @var{table-of-contents}
3656 Show the labels embedded in a table of context.@refill
3657 @item @var{section-numbers}
3658 Include section numbers (like 4.1.3) in table of contents.@refill
3659 @item @var{counters}
3660 Show counters. This just numbers the labels in the menu.@refill
3661 @item @var{no-context}
3662 Non-@code{nil} means do @emph{not} show the short context.@refill
3664 Follow full context in other window.@refill
3665 @item @var{show-commented}
3666 Show labels from regions which are commented out.@refill
3667 @item @var{match-everywhere}
3668 Obsolete flag.@refill
3669 @item @var{show-files}
3670 Show begin and end of included files.@refill
3673 Each of these flags can be set to @code{t} or @code{nil}, or to a string
3674 of type letters indicating the label types for which it should be true.
3675 These strings work like character classes in regular expressions. Thus,
3676 setting one of the flags to @samp{"sf"} makes the flag true for section
3677 and figure labels, @code{nil} for everything else. Setting it to
3678 @samp{"^sf"} makes it the other way round.@refill
3680 The available label types are: @code{s} (section), @code{f} (figure),
3681 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
3682 (footnote), plus any definitions in @code{reftex-label-alist}.@refill
3684 Most options can also be switched from the label menu itself - so if you
3685 decide here to not have a table of contents in the label menu, you can
3686 still get one interactively during selection from the label menu.@refill
3689 @defopt reftex-multiref-punctuation
3690 Punctuation strings for multiple references. When marking is used in
3691 the selection buffer to select several references, this variable
3692 associates the 3 marking characters @samp{,-+} with prefix strings to be
3693 inserted into the buffer before the corresponding @code{\ref} macro.
3694 This is used to string together whole reference sets, like
3695 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
3696 @code{reftex-reference}.@refill
3699 @defopt reftex-vref-is-default
3700 Non-@code{nil} means, the varioref macro @code{\vref} is used as
3701 default. In the selection buffer, the @kbd{v} key toggles the reference
3702 macro between @code{\ref} and @code{\vref}. The value of this variable
3703 determines the default which is active when entering the selection
3704 process. Instead of @code{nil} or @code{t}, this may also be a string
3705 of type letters indicating the label types for which it should be
3709 @defopt reftex-fref-is-default
3710 Non-@code{nil} means, the fancyref macro @code{\fref} is used as
3711 default. In the selection buffer, the @kbd{V} key toggles the reference
3712 macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of
3713 this variable determines the default which is active when entering the
3714 selection process. Instead of @code{nil} or @code{t}, this may also be
3715 a string of type letters indicating the label types for which it should
3719 @deffn Hook reftex-format-ref-function
3720 If non-@code{nil}, should be a function which produces the string to
3721 insert as a reference. Note that the insertion format can also be
3722 changed with @code{reftex-label-alist}. This hook also is used by the
3723 special commands to insert @code{\vref} and @code{\fref} references, so
3724 even if you set this, your setting will be ignored by the special
3725 commands. The function will be called with two arguments, the
3726 @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
3727 It should return the string to insert into the buffer.@refill
3730 @defopt reftex-level-indent
3731 Number of spaces to be used for indentation per section level.@refill
3734 @defopt reftex-guess-label-type
3735 Non-@code{nil} means, @code{reftex-reference} will try to guess the
3736 label type. To do that, @b{Ref@TeX{}} will look at the word before the
3737 cursor and compare it with the magic words given in
3738 @code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will
3739 immediately offer the correct label menu - otherwise it will prompt you
3740 for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}
3741 will always prompt for a label type.@refill
3744 @deffn {Normal Hook} reftex-display-copied-context-hook
3745 Normal Hook which is run before context is displayed anywhere. Designed
3746 for @w{@code{X-Symbol}}, but may have other uses as well.@refill
3749 @deffn Hook reftex-pre-refontification-functions
3750 @code{X-Symbol} specific hook. Probably not useful for other purposes.
3751 The functions get two arguments, the buffer from where the command
3752 started and a symbol indicating in what context the hook is
3756 @deffn {Normal Hook} reftex-select-label-mode-hook
3757 Normal hook which is run when a selection buffer enters
3758 @code{reftex-select-label-mode}.@refill
3761 @deffn Keymap reftex-select-label-map
3762 The keymap which is active in the labels selection process
3763 (@pxref{Referencing Labels}).@refill
3766 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
3767 @section Creating Citations
3768 @cindex Options, creating citations
3769 @cindex Creating citations, options
3771 @defopt reftex-bibfile-ignore-regexps
3772 List of regular expressions to exclude files in
3773 @code{\\bibliography@{..@}}. File names matched by any of these regexps
3774 will not be parsed. Intended for files which contain only
3775 @code{@@string} macro definitions and the like, which are ignored by
3776 @b{Ref@TeX{}} anyway.@refill
3779 @defopt reftex-default-bibliography
3780 List of BibTeX database files which should be used if none are specified.
3781 When @code{reftex-citation} is called from a document with neither
3782 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
3783 environment, @b{Ref@TeX{}} will scan these files instead. Intended for
3784 using @code{reftex-citation} in non-LaTeX files. The files will be
3785 searched along the BIBINPUTS or TEXBIB path.@refill
3788 @defopt reftex-sort-bibtex-matches
3789 Sorting of the entries found in BibTeX databases by reftex-citation.
3790 Possible values:@refill
3792 nil @r{Do not sort entries.}
3793 author @r{Sort entries by author name.}
3794 year @r{Sort entries by increasing year.}
3795 reverse-year @r{Sort entries by decreasing year.}
3799 @defopt reftex-cite-format
3800 The format of citations to be inserted into the buffer. It can be a
3801 string, an alist or a symbol. In the simplest case this is just the string
3802 @samp{\cite@{%l@}}, which is also the default. See the definition of
3803 @code{reftex-cite-format-builtin} for more complex examples.@refill
3805 If @code{reftex-cite-format} is a string, it will be used as the format.
3806 In the format, the following percent escapes will be expanded.@refill
3810 The BibTeX label of the citation.
3812 List of author names, see also @code{reftex-cite-punctuation}.
3814 Like %a, but abbreviate more than 2 authors like Jones et al.
3816 First author name only.
3818 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
3819 @samp{%E} work a well).@refill
3822 It is also possible to access all other BibTeX database fields:
3825 %b booktitle %c chapter %d edition %h howpublished
3826 %i institution %j journal %k key %m month
3827 %n number %o organization %p pages %P first page
3828 %r address %s school %u publisher %t title
3830 %B booktitle, abbreviated %T title, abbreviated
3834 Usually, only @samp{%l} is needed. The other stuff is mainly for the
3835 echo area display, and for @code{(setq reftex-comment-citations t)}.@refill
3837 @samp{%<} as a special operator kills punctuation and space around it
3838 after the string has been formatted.@refill
3840 Beware that all this only works with BibTeX database files. When
3841 citations are made from the @code{\bibitems} in an explicit
3842 @code{thebibliography} environment, only @samp{%l} is available.@refill
3844 If @code{reftex-cite-format} is an alist of characters and strings, the
3845 user will be prompted for a character to select one of the possible
3846 format strings.@refill
3848 In order to configure this variable, you can either set
3849 @code{reftex-cite-format} directly yourself or set it to the
3850 @emph{symbol} of one of the predefined styles. The predefined symbols
3851 are those which have an association in the constant
3852 @code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
3856 @deffn Hook reftex-format-cite-function
3858 If non-@code{nil}, should be a function which produces the string to
3859 insert as a citation. Note that the citation format can also be changed
3860 with the variable @code{reftex-cite-format}. The function will be
3861 called with two arguments, the @var{citation-key} and the
3862 @var{default-format} (taken from @code{reftex-cite-format}). It should
3863 return the string to insert into the buffer.@refill
3866 @defopt reftex-comment-citations
3867 Non-@code{nil} means add a comment for each citation describing the full
3868 entry. The comment is formatted according to
3869 @code{reftex-cite-comment-format}.@refill
3872 @defopt reftex-cite-comment-format
3873 Citation format used for commented citations. Must @emph{not} contain
3874 @samp{%l}. See the variable @code{reftex-cite-format} for possible
3875 percent escapes.@refill
3878 @defopt reftex-cite-punctuation
3879 Punctuation for formatting of name lists in citations. This is a list
3880 of 3 strings.@refill
3883 normal names separator, like @samp{, } in Jones, Brown and Miller
3885 final names separator, like @samp{ and } in Jones, Brown and Miller
3887 The @samp{et al.} string, like @samp{ @{\it et al.@}} in
3888 Jones @{\it et al.@}
3892 @deffn {Normal Hook} reftex-select-bib-mode-hook
3893 Normal hook which is run when a selection buffer enters
3894 @code{reftex-select-bib-mode}.@refill
3897 @deffn Keymap reftex-select-bib-map
3898 The keymap which is active in the citation-key selection process
3899 (@pxref{Creating Citations}).@refill
3902 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options
3903 @section Index Support
3904 @cindex Options, Index support
3905 @cindex Index support, options
3907 @defopt reftex-support-index
3908 Non-@code{nil} means, index entries are parsed as well. Index support
3909 is resource intensive and the internal structure holding the parsed
3910 information can become quite big. Therefore it can be turned off. When
3911 this is @code{nil} and you execute a command which requires index
3912 support, you will be asked for confirmation to turn it on and rescan the
3916 @defopt reftex-index-special-chars
3917 List of special characters in index entries, given as strings. These
3918 correspond to the @code{MakeIndex} keywords
3919 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
3922 @defopt reftex-index-macros
3923 List of macros which define index entries. The structure of each entry
3926 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude})
3929 @var{macro} is the macro. Arguments should be denoted by empty braces,
3930 as for example in @samp{\index[]@{*@}}. Use square brackets to denote
3931 optional arguments. The star marks where the index key is.@refill
3933 @var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
3934 are reserved for the default index and the glossary. Other indices can
3935 be defined as well. If this is an integer, the Nth argument of the
3936 macro holds the index tag.@refill
3938 @var{key} is a character which is used to identify the macro for input
3939 with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
3940 reserved for default index and glossary.@refill
3942 @var{prefix} can be a prefix which is added to the @var{key} part of the
3943 index entry. If you have a macro
3944 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
3945 should be @samp{Molecules!}.@refill
3947 @var{exclude} can be a function. If this function exists and returns a
3948 non-nil value, the index entry at point is ignored. This was
3949 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
3950 in the LaTeX2e @code{index} package.@refill
3952 The final entry may also be a symbol. It must have an association in
3953 the variable @code{reftex-index-macros-builtin} to specify the main
3954 indexing package you are using. Legal values are currently@refill
3956 default @r{The LaTeX default - unnecessary to specify this one}
3957 multind @r{The multind.sty package}
3958 index @r{The index.sty package}
3959 index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
3960 @r{Should not be used - only for old documents}
3962 Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
3963 so with a sufficiently new version of AUCTeX, you should not set the
3967 @defopt reftex-index-default-macro
3968 The default index macro for @code{reftex-index-selection-or-word}.
3969 This is a list with @code{(@var{macro-key} @var{default-tag} @var{repeat-word})}.
3971 @var{macro-key} is a character identifying an index macro - see
3972 @code{reftex-index-macros}.
3974 @var{default-tag} is the tag to be used if the macro requires a
3975 @var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
3976 @b{Ref@TeX{}} will ask for it. When this is the empty string and the
3977 TAG argument of the index macro is optional, the TAG argument will be
3980 @var{repeat-word}, when non-@code{nil} means, the index macro does not
3981 typeset the entry in the text, so that the text has to be repeated
3982 outside the index macro.
3985 @defopt reftex-index-default-tag
3986 Default index tag. When working with multiple indexes, RefTeX queries
3987 for an index tag when creating index entries or displaying a specific
3988 index. This variable controls the default offered for these queries.
3989 The default can be selected with @key{RET} during selection or
3990 completion. Legal values of this variable are:@refill
3992 nil @r{Do not provide a default index}
3993 "tag" @r{The default index tag given as a string, e.g. "idx"}
3994 last @r{The last used index tag will be offered as default}
3998 @defopt reftex-index-math-format
3999 Format of index entries when copied from inside math mode. When
4000 @code{reftex-index-selection-or-word} is executed inside TeX math mode,
4001 the index key copied from the buffer is processed with this format
4002 string through the @code{format} function. This can be used to add the
4003 math delimiters (e.g. @samp{$}) to the string. Requires the
4004 @file{texmathp.el} library which is part of AUCTeX.@refill
4007 @defopt reftex-index-section-letters
4008 The letters which denote sections in the index. Usually these are all
4009 capital letters. Don't use any downcase letters. Order is not
4010 significant, the index will be sorted by whatever the sort function
4011 thinks is correct. In addition to these letters, RefTeX will create a
4012 group @samp{!} which contains all entries sorted below the lowest
4013 specified letter. In the @file{*Index*} buffer, pressing any of these
4014 capital letters or @kbd{!} will jump to that section.@refill
4017 @defopt reftex-index-include-context
4018 Non-@code{nil} means, display the index definition context in the
4019 @file{*Index*} buffer. This flag may also be toggled from the
4020 @file{*Index*} buffer with the @kbd{c} key.
4023 @defopt reftex-index-follow-mode
4024 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4025 window to follow. The other window will show the corresponding part of
4026 the document. This flag can be toggled from within the @file{*Index*}
4027 buffer with the @kbd{f} key.
4030 @deffn Keymap reftex-index-map
4031 The keymap which is active in the @file{*Index*} buffer
4032 (@pxref{Index Support}).@refill
4035 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options
4036 @section Viewing Cross-References
4037 @cindex Options, viewing cross-references
4038 @cindex Viewing cross-references, options
4040 @defopt reftex-view-crossref-extra
4041 Macros which can be used for the display of cross references.
4042 This is used when `reftex-view-crossref' is called with point in an
4043 argument of a macro. Note that crossref viewing for citations,
4044 references (both ways) and index entries is hard-coded. This variable
4045 is only to configure additional structures for which crossreference
4046 viewing can be useful. Each entry has the structure
4048 (@var{macro-re} @var{search-re} @var{highlight}).
4050 @var{macro-re} is matched against the macro. @var{search-re} is the
4051 regexp used to search for cross references. @samp{%s} in this regexp is
4052 replaced with with the macro argument at point. @var{highlight} is an
4053 integer indicating which subgroup of the match should be highlighted.
4056 @defopt reftex-auto-view-crossref
4057 Non-@code{nil} means, initially turn automatic viewing of crossref info
4058 on. Automatic viewing of crossref info normally uses the echo area.
4059 Whenever point is on the argument of a @code{\ref} or @code{\cite}
4060 macro, and no other message is being displayed, the echo area will
4061 display information about that cross reference. You can also set the
4062 variable to the symbol @code{window}. In this case a small temporary
4063 window is used for the display. This feature can be turned on and of
4064 from the menu (Ref->Options).@refill
4067 @defopt reftex-idle-time
4068 Time (secs) Emacs has to be idle before automatic crossref display is
4072 @defopt reftex-cite-view-format
4073 Citation format used to display citation info in the message area. See
4074 the variable @code{reftex-cite-format} for possible percent
4078 @defopt reftex-revisit-to-echo
4079 Non-@code{nil} means, automatic citation display will revisit files if
4080 necessary. When nil, citation display in echo area will only be active
4081 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4082 BibTeX database files which are already visited by a live associated
4086 @defopt reftex-cache-cite-echo
4087 Non-@code{nil} means, the information displayed in the echo area for
4088 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4089 saved along with the parsing information. The cache survives document
4090 scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
4093 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options
4094 @section Finding Files
4095 @cindex Options, Finding Files
4096 @cindex Finding files, options
4098 @defopt reftex-texpath-environment-variables
4099 List of specifications how to retrieve the search path for TeX files.
4100 Several entries are possible.@refill
4103 If an element is the name of an environment variable, its content is
4106 If an element starts with an exclamation mark, it is used as a command
4107 to retrieve the path. A typical command with the kpathsearch library
4108 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4110 Otherwise the element itself is interpreted as a path.
4112 Multiple directories can be separated by the system dependent
4113 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4114 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4117 @defopt reftex-bibpath-environment-variables
4118 List of specifications how to retrieve the search path for BibTeX
4119 files. Several entries are possible.@refill
4122 If an element is the name of an environment variable, its content is
4125 If an element starts with an exclamation mark, it is used as a command
4126 to retrieve the path. A typical command with the kpathsearch library
4127 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4129 Otherwise the element itself is interpreted as a path.
4131 Multiple directories can be separated by the system dependent
4132 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4133 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4136 @defopt reftex-file-extensions
4137 Association list with file extensions for different file types.
4138 This is a list of items, each item is like:
4139 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4141 @var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
4142 @var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
4143 @var{other-ext}: @r{Any number of other legal extensions for this file type.}
4145 When a files is searched and it does not have any of the legal extensions,
4146 we try the default extension first, and then the naked file name.@refill
4149 @defopt reftex-search-unrecursed-path-first
4150 Non-@code{nil} means, search all specified directories before trying
4151 recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
4152 then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
4153 option is @code{nil}, the subdirectories of @samp{./} are searched
4154 before @samp{/tex/}. This is mainly for speed - most of the time the
4155 recursive path is for the system files and not for the user files. Set
4156 this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
4157 equal names in wrong sequence.@refill
4160 @defopt reftex-use-external-file-finders
4161 Non-@code{nil} means, use external programs to find files. Normally,
4162 @b{Ref@TeX{}} searches the paths given in the environment variables
4163 @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
4164 database files. With this option turned on, it calls an external
4165 program specified in the option @code{reftex-external-file-finders}
4166 instead. As a side effect, the variables
4167 @code{reftex-texpath-environment-variables} and
4168 @code{reftex-bibpath-environment-variables} will be ignored.
4171 @defopt reftex-external-file-finders
4172 Association list with external programs to call for finding files. Each
4173 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
4174 @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
4175 string containing the external program to use with any arguments.
4176 @code{%f} will be replaced by the name of the file to be found. Note
4177 that these commands will be executed directly, not via a shell. Only
4178 relevant when @code{reftex-use-external-file-finders} is
4179 non-@code{nil}.@refill
4183 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
4184 @section Optimizations
4185 @cindex Options, optimizations
4186 @cindex Optimizations, options
4188 @defopt reftex-keep-temporary-buffers
4189 Non-@code{nil} means, keep buffers created for parsing and lookup.
4190 @b{Ref@TeX{}} sometimes needs to visit files related to the current
4191 document. We distinguish files visited for@refill
4194 Parts of a multifile document loaded when (re)-parsing the
4197 BibTeX database files and TeX files loaded to find a reference, to
4198 display label context, etc.@refill
4200 The created buffers can be kept for later use, or be thrown away
4201 immediately after use, depending on the value of this variable:@refill
4205 Throw away as much as possible.
4209 Throw away buffers created for parsing, but keep the ones created for
4213 If a buffer is to be kept, the file is visited normally (which is
4214 potentially slow but will happen only once). If a buffer is to be thrown
4215 away, the initialization of the buffer depends upon the variable
4216 @code{reftex-initialize-temporary-buffers}.@refill
4219 @defopt reftex-initialize-temporary-buffers
4220 Non-@code{nil} means do initializations even when visiting file
4221 temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
4222 other stuff to briefly visit a file. When @code{t}, the full default
4223 initializations are done (@code{find-file-hook} etc.). Instead of
4224 @code{t} or @code{nil}, this variable may also be a list of hook
4225 functions to do a minimal initialization.@refill
4228 @defopt reftex-no-include-regexps
4229 List of regular expressions to exclude certain input files from parsing.
4230 If the name of a file included via @code{\include} or @code{\input} is
4231 matched by any of the regular expressions in this list, that file is not
4232 parsed by @b{Ref@TeX{}}.
4235 @defopt reftex-enable-partial-scans
4236 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4237 Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
4238 commands, or with the @kbd{r} key in menus. When this option is
4239 @code{t} in a multifile document, we will only parse the current buffer,
4240 or the file associated with the label or section heading near point in a
4241 menu. Requesting re-parsing of an entire multifile document then
4242 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
4246 @defopt reftex-save-parse-info
4247 Non-@code{nil} means, save information gathered with parsing in files.
4248 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
4249 used to save the information. When this variable is @code{t},
4252 accessing the parsing information for the first time in an editing
4253 session will read that file (if available) instead of parsing the
4256 exiting Emacs or killing a buffer in reftex-mode will cause a new
4257 version of the file to be written.@refill
4261 @defopt reftex-allow-automatic-rescan
4262 Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
4263 necessary. Applies (currently) only in rare cases, when a new label
4264 cannot be placed with certainty into the internal label list.
4267 @defopt reftex-use-multiple-selection-buffers
4268 Non-@code{nil} means use a separate selection buffer for each label
4269 type. These buffers are kept from one selection to the next and need
4270 not to be created for each use - so the menu generally comes up faster.
4271 The selection buffers will be erased (and therefore updated)
4272 automatically when new labels in its category are added. See the
4273 variable @code{reftex-auto-update-selection-buffers}.@refill
4276 @defopt reftex-auto-update-selection-buffers
4277 Non-@code{nil} means, selection buffers will be updated automatically.
4278 When a new label is defined with @code{reftex-label}, all selection
4279 buffers associated with that label category are emptied, in order to
4280 force an update upon next use. When @code{nil}, the buffers are left
4281 alone and have to be updated by hand, with the @kbd{g} key from the
4282 label selection process. The value of this variable will only have any
4283 effect when @code{reftex-use-multiple-selection-buffers} is
4284 non-@code{nil}.@refill
4287 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
4288 @section Fontification
4289 @cindex Options, fontification
4290 @cindex Fontification, options
4292 @defopt reftex-use-fonts
4293 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
4294 Font-lock must be loaded as well to actually get fontified
4295 display. After changing this option, a rescan may be necessary to
4299 @defopt reftex-refontify-context
4300 Non-@code{nil} means, re-fontify the context in the label menu with
4301 font-lock. This slightly slows down the creation of the label menu. It
4302 is only necessary when you definitely want the context fontified.@refill
4304 This option may have 3 different values:
4311 Refontify when necessary, e.g. with old versions of the x-symbol
4314 The option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill
4317 @defopt reftex-highlight-selection
4318 Non-@code{nil} means, highlight selected text in selection and
4319 @file{*toc*} buffers. Normally, the text near the cursor is the
4320 @emph{selected} text, and it is highlighted. This is the entry most
4321 keys in the selection and @file{*toc*} buffers act on. However, if you
4322 mainly use the mouse to select an item, you may find it nice to have
4323 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
4324 variable may have one of these values:@refill
4327 nil @r{No highlighting.}
4328 cursor @r{Highlighting is cursor driven.}
4329 mouse @r{Highlighting is mouse driven.}
4330 both @r{Both cursor and mouse trigger highlighting.}
4333 Changing this variable requires to rebuild the selection and *toc*
4334 buffers to become effective (keys @kbd{g} or @kbd{r}).@refill
4337 @defopt reftex-cursor-selected-face
4338 Face name to highlight cursor selected item in toc and selection buffers.
4339 See also the variable @code{reftex-highlight-selection}.@refill
4341 @defopt reftex-mouse-selected-face
4342 Face name to highlight mouse selected item in toc and selection buffers.
4343 See also the variable @code{reftex-highlight-selection}.@refill
4345 @defopt reftex-file-boundary-face
4346 Face name for file boundaries in selection buffer.
4348 @defopt reftex-label-face
4349 Face name for labels in selection buffer.
4351 @defopt reftex-section-heading-face
4352 Face name for section headings in toc and selection buffers.
4354 @defopt reftex-toc-header-face
4355 Face name for the header of a toc buffer.
4357 @defopt reftex-bib-author-face
4358 Face name for author names in bib selection buffer.
4360 @defopt reftex-bib-year-face
4361 Face name for year in bib selection buffer.
4363 @defopt reftex-bib-title-face
4364 Face name for article title in bib selection buffer.
4366 @defopt reftex-bib-extra-face
4367 Face name for bibliographic information in bib selection buffer.
4369 @defopt reftex-select-mark-face
4370 Face name for marked entries in the selection buffers.
4372 @defopt reftex-index-header-face
4373 Face name for the header of an index buffer.
4375 @defopt reftex-index-section-face
4376 Face name for the start of a new letter section in the index.
4378 @defopt reftex-index-tag-face
4379 Face name for index names (for multiple indices).
4381 @defopt reftex-index-face
4382 Face name for index entries.
4385 @node Options (Misc), , Options (Fontification), Options
4386 @section Miscellaneous
4387 @cindex Options, misc
4389 @defopt reftex-extra-bindings
4390 Non-@code{nil} means, make additional key bindings on startup. These
4391 extra bindings are located in the users @samp{C-c letter}
4392 map. @xref{Keybindings}.@refill
4395 @defopt reftex-plug-into-AUCTeX
4396 Plug-in flags for AUCTeX interface. This variable is a list of
4397 5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}
4401 - supply labels in new sections and environments (flag 1)
4402 - supply arguments for macros like @code{\label} (flag 2)
4403 - supply arguments for macros like @code{\ref} (flag 3)
4404 - supply arguments for macros like @code{\cite} (flag 4)
4405 - supply arguments for macros like @code{\index} (flag 5)
4408 You may also set the variable itself to t or nil in order to turn all
4409 options on or off, respectively.@*
4410 Supplying labels in new sections and environments applies when creating
4411 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
4412 Supplying macro arguments applies when you insert such a macro
4413 interactively with @kbd{C-c @key{RET}}.@*
4414 See the AUCTeX documentation for more information.
4417 @defopt reftex-revisit-to-follow
4418 Non-@code{nil} means, follow-mode will revisit files if necessary.
4419 When nil, follow-mode will be suspended for stuff in unvisited files.
4422 @defopt reftex-allow-detached-macro-args
4423 Non-@code{nil} means, allow arguments of macros to be detached by
4424 whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
4425 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
4426 this will be the case even if @code{\bb} is defined with zero or one
4430 @node Keymaps and Hooks, Changes, Options, Top
4431 @section Keymaps and Hooks
4434 @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
4436 @deffn Keymap reftex-mode-map
4437 The keymap for @b{Ref@TeX{}} mode.
4440 @deffn {Normal Hook} reftex-load-hook
4441 Normal hook which is being run when loading @file{reftex.el}.
4444 @deffn {Normal Hook} reftex-mode-hook
4445 Normal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill
4448 Furthermore, the 3 modes used for referencing labels, creating citations
4449 and for the table of contents buffer have their own keymaps and mode
4450 hooks. See the respective sections. There are many more hooks which
4451 are described in the relevant sections about options for a specific part
4452 of @b{Ref@TeX{}}.@refill
4454 @node Changes, , Keymaps and Hooks, Top
4458 Here is a list of recent changes to @b{Ref@TeX{}}.
4461 @noindent @b{Version 1.00}
4464 released on 7 Jan 1997.
4467 @noindent @b{Version 1.04}
4470 Macros as wrappers, AMSTeX support, delayed context parsing for
4474 @noindent @b{Version 1.05}
4480 @noindent @b{Version 1.07}
4483 @b{Ref@TeX{}} gets its own menu.
4486 @noindent @b{Version 1.09}
4489 Support for @code{tex-main-file}, an analogue for
4490 @code{TeX-master}.@refill
4495 @noindent @b{Version 2.00}
4498 Labels can be derived from context (default for sections).
4500 Configuration of label insertion and label referencing revised.
4502 Crossref fields in BibTeX database entries.
4504 @code{reftex-toc} introduced (thanks to Stephen Eglen).
4507 @noindent @b{Version 2.03}
4510 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
4511 default environments.@refill
4513 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
4515 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
4516 @code{reftex-arg-cite}.@refill
4518 Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
4521 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
4524 Finding context with a hook function.
4526 Sorting BibTeX entries (new variable:
4527 @code{reftex-sort-bibtex-matches}).
4530 @noindent @b{Version 2.05}
4533 Support for @file{custom.el}.
4535 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
4538 @noindent @b{Version 2.07}
4541 New functions @code{reftex-search-document},
4542 @code{reftex-query-replace-document}.
4545 @noindent @b{Version 2.11}
4548 Submitted for inclusion to Emacs and XEmacs.
4551 @noindent @b{Version 2.14}
4554 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
4558 @noindent @b{Version 2.17}
4561 Label prefix expands % escapes with current file name and other stuff.
4563 Citation format now with % escapes. This is not backward
4566 TEXINPUTS variable recognized when looking for input files.
4568 Context can be the nth argument of a macro.@refill
4570 Searching in the select buffer is now possible (@kbd{C-s} and
4573 Display and derive-label can use two different context methods.
4575 AMSmath @code{xalignat} and @code{xxalignat} added.
4578 @noindent @b{Version 3.00}
4581 @b{Ref@TeX{}} should work better for very large projects:
4583 The new parser works without creating a master buffer.
4585 Rescanning can be limited to a part of a multifile document.
4587 Information from the parser can be stored in a file.
4589 @b{Ref@TeX{}} can deal with macros having a naked label as an argument.
4591 Macros may have white space and newlines between arguments.
4593 Multiple identical section headings no longer confuse
4594 @code{reftex-toc}.@refill
4596 @b{Ref@TeX{}} should work correctly in combination with buffer-altering
4597 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill
4599 All labeled environments discussed in @emph{The LaTeX Companion} by
4600 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
4601 @b{Ref@TeX{}}'s defaults.@refill
4604 @noindent @b{Version 3.03}
4607 Support for the LaTeX package @code{xr}, for inter-document
4610 A few (minor) Mule-related changes.
4612 Fixed bug which could cause @emph{huge} @file{.rel} files.
4614 Search for input and @file{.bib} files with recursive path definitions.
4617 @noindent @b{Version 3.04}
4620 Fixed BUG in the @emph{xr} support.
4623 @noindent @b{Version 3.05}
4626 Compatibility code now first checks for XEmacs feature.
4629 @noindent @b{Version 3.07}
4632 @code{Ref} menu improved.
4635 @noindent @b{Version 3.10}
4638 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
4640 Removed unimportant code which caused OS/2 Emacs to crash.
4642 All customization variables now accessible from menu.
4645 @noindent @b{Version 3.11}
4648 Fixed bug which led to naked label in (e.g.) footnotes.
4650 Added scroll-other-window functions to RefTeX-Select.
4653 @noindent @b{Version 3.12}
4656 There are 3 new keymaps for customization: @code{reftex-toc-map},
4657 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
4659 Refontification uses more standard font-lock stuff.
4661 When no BibTeX database files are specified, citations can also use
4662 @code{\bibitem} entries from a @code{thebibliography} environment.@refill
4665 @noindent @b{Version 3.14}
4668 Selection buffers can be kept between selections: this is faster.
4669 See new variable @code{reftex-use-multiple-selection-buffers}.@refill
4671 Prefix interpretation of reftex-view-crossref changed.
4673 Support for the @code{varioref} package (@kbd{v} key in selection
4677 @noindent @b{Version 3.16}
4680 New hooks @code{reftex-format-label-function},
4681 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill
4683 TeXInfo documentation completed.
4685 Some restrictions in Label inserting and referencing removed.
4687 New variable @code{reftex-default-bibliography}.
4690 @noindent @b{Version 3.17}
4693 Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
4696 New command @code{reftex-save-all-document-buffers}.
4698 Magic word matching made more intelligent.
4700 Selection process can switch to completion (with @key{TAB}).
4702 @code{\appendix} is now recognized and influences section numbering.
4704 File commentary shortened considerably (use Info documentation).
4706 New option @code{reftex-no-include-regexps} to skip some include files.
4708 New option @code{reftex-revisit-to-follow}.
4711 @noindent @b{Version 3.18}
4714 The selection now uses a recursive edit, much like minibuffer input.
4715 This removes all restrictions during selection. E.g. you can now
4716 switch buffers at will, use the mouse etc.@refill
4718 New option @code{reftex-highlight-selection}.
4720 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
4723 Fixed some problems regarding the interaction with VIPER mode.
4725 Follow-mode is now only used after point motion.
4727 @b{Ref@TeX{}} now finally does not fontify temporary files anymore.
4730 @noindent @b{Version 3.19}
4733 Fixed bug with AUCTeX @code{TeX-master}.
4736 @noindent @b{Version 3.21}
4739 New options for all faces used by @b{Ref@TeX{}}. They're in the
4740 customization group @code{reftex-fontification-configurations}.@refill
4743 @noindent @b{Version 3.22}
4746 Fixed bug with empty context strings.
4748 @code{reftex-mouse-view-crossref} is now bound by default at
4749 @kbd{S-mouse-2}.@refill
4752 @noindent @b{Version 3.23}
4755 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
4757 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
4760 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
4761 automatic display of crossref information in the echo area. See
4762 variable @code{reftex-auto-view-crossref}.
4764 AUCTeX interface updates:
4767 AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
4769 @b{Ref@TeX{}} notifies AUCTeX about new labels.
4771 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
4773 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
4775 Settings added to @b{Ref@TeX{}} via style files remain local.
4778 Fixed bug with @code{reftex-citation} in non-latex buffers.
4780 Fixed bug with syntax table and context refontification.
4782 Safety-net for name change of @code{font-lock-reference-face}.
4785 @noindent @b{Version 3.24}
4788 New option @code{reftex-revisit-to-echo}.
4790 Interface with X-Symbol (>=2.6) is now complete and stable.
4792 Adapted to new outline, which uses overlays.
4794 File names in @code{\bibliography} may now have the @code{.bib}
4797 Fixed Bug with parsing "single file" from master file buffer.
4800 @noindent @b{Version 3.25}
4803 Echoing of citation info caches the info for displayed entries.
4804 New option @code{reftex-cache-cite-echo}.@refill
4806 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
4809 Default of @code{reftex-revisit-to-follow} changed to nil.
4812 @noindent @b{Version 3.26}
4815 [X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
4817 New hooks @code{reftex-translate-to-ascii-function},
4818 @code{reftex-string-to-label-function}.@refill
4820 Made sure automatic crossref display will not visit/scan files.
4823 @noindent @b{Version 3.27}
4826 Macros can define @emph{neutral} labels, just like @code{\label}
4829 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
4832 @noindent @b{Version 3.28}
4835 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
4836 timer, since itimer restart is not reliable.@refill
4838 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
4840 Expansion of recursive tex and bib path rewritten.
4842 Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
4844 Fixed bug with section numbering after *-red sections.
4847 @noindent @b{Version 3.30}
4850 In @code{reftex-citation}, the regular expression used to scan BibTeX
4851 files can be specified using completion on known citation keys.
4853 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
4856 New command @code{reftex-renumber-simple-labels} to renumber simple
4857 labels like @samp{eq:13} sequentially through a document.
4859 @noindent @b{Version 3.33}
4862 Multiple selection buffers are now hidden buffers (they start with a
4865 Fixed bug with file search when TEXINPUTS environment variable is empty.
4867 @noindent @b{Version 3.34}
4870 Additional flag in @code{reftex-derive-label-parameters} do make only
4871 lowercase labels (default @code{t}).
4873 All @file{.rel} files have a final newline to avoid queries.
4875 Single byte representations of accented European letters (ISO-8859-1)
4876 are now legal in labels.
4878 @noindent @b{Version 3.35}
4881 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
4882 This takes back the related changes in 3.34 for safety reasons.@refill
4884 @noindent @b{Version 3.36}
4887 New value @code{window} for option @code{reftex-auto-view-crossref}.
4889 @noindent @b{Version 3.38}
4892 @code{reftex-view-crossref} no longer moves to find a macro. Point has
4893 to be on the macro argument.
4895 @noindent @b{Version 3.41}
4898 New options @code{reftex-texpath-environment-variables},
4899 @code{reftex-use-external-file-finders},
4900 @code{reftex-external-file-finders},
4901 @code{reftex-search-unrecursed-path-first}.
4903 @emph{kpathsearch} support. See new options and
4904 @code{reftex-bibpath-environment-variables}.
4907 @noindent @b{Version 3.42}
4910 File search further refined. New option @code{reftex-file-extensions}.
4912 @file{*toc*} buffer can show the file boundaries of a multifile
4913 document, all labels and associated context. New keys @kbd{i}, @kbd{l},
4914 and @kbd{c}. New options @code{reftex-toc-include-labels},
4915 @code{reftex-toc-include-context},
4916 @code{reftex-toc-include-file-boundaries}. @refill
4918 @noindent @b{Version 3.43}
4921 Viewing cross-references generalized. Now works on @code{\label},
4922 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
4923 these, and from BibTeX buffers.@refill
4925 New option @code{reftex-view-crossref-extra}.@refill
4927 Support for the additional sectioning commands @code{\addchap} and
4928 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill
4930 Files in @code{reftex-default-bibliography} will be searched along
4931 @code{BIBINPUTS} path.@refill
4933 Reading a parse file now checks consistency.
4935 @noindent @b{Version 4.00}
4938 RefTeX has been split into several smaller files which are autoloaded on
4941 Index support, along with many new options.
4943 The selection of keys for @code{\ref} and @code{\cite} now allows to
4944 select multiple items by marking entries with the @kbd{m} key.
4948 @noindent @b{Version 4.01}
4951 New command @code{reftex-index-globally} to index a word in many
4952 places in the document. Also available from the index buffer with
4955 The first item in a @code{reftex-label-alist} entry may now also be a parser
4956 function to do non-standard parsing.
4958 @code{reftex-auto-view-crossref} no longer interferes with
4959 @code{pop-up-frames} (patch from Stefan Monnier).
4961 @noindent @b{Version 4.02}
4964 macros ending in @samp{refrange} are considered to contain references.
4966 Index entries made with @code{reftex-index-selection-or-word} in TeX
4967 math mode automatically get enclosing @samp{$} to preserve math mode. See
4968 new option @code{reftex-index-math-format}. Requires AUCTeX.
4970 @noindent @b{Version 4.04}
4973 New option @code{reftex-index-default-tag} implements a default for queries.
4975 @noindent @b{Version 4.06}
4978 @code{reftex-section-levels} can contain a function to compute the level
4979 of a sectioning command.
4981 Multiple @code{thebibliography} environments recognized.
4985 @node Index, , , Top