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.
20 @c Subheadings inside a table. Need a difference between info and the rest.
21 @macro tablesubheading{text}
31 This file documents @b{Ref@TeX{}}, a package to do labels, references,
32 citations and indices for LaTeX documents with Emacs.@refill
34 This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
35 @b{Ref@TeX{}} @value{VERSION}@refill
37 Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
39 Permission is granted to copy, distribute and/or modify this document
40 under the terms of the GNU Free Documentation License, Version 1.1 or
41 any later version published by the Free Software Foundation; with no
42 Invariant Sections, with the Front-Cover texts being ``A GNU
43 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
44 license is included in the section entitled ``GNU Free Documentation
45 License'' in the Emacs manual.
47 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
48 this GNU Manual, like GNU software. Copies published by the Free
49 Software Foundation raise funds for GNU development.''
51 This document is part of a collection distributed under the GNU Free
52 Documentation License. If you want to distribute this document
53 separately from the collection, you can do so by adding a copy of the
54 license to the document, as described in section 6 of the license.
58 @title Ref@TeX{} User Manual
59 @subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
60 @subtitle Edition @value{EDITION}, @value{DATE}
62 @author by Carsten Dominik
64 Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
67 This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
68 @b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
72 Permission is granted to copy, distribute and/or modify this document
73 under the terms of the GNU Free Documentation License, Version 1.1 or
74 any later version published by the Free Software Foundation; with no
75 Invariant Sections, with the Front-Cover texts being ``A GNU
76 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
77 license is included in the section entitled ``GNU Free Documentation
78 License'' in the Emacs manual.
80 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
81 this GNU Manual, like GNU software. Copies published by the Free
82 Software Foundation raise funds for GNU development.''
84 This document is part of a collection distributed under the GNU Free
85 Documentation License. If you want to distribute this document
86 separately from the collection, you can do so by adding a copy of the
87 license to the document, as described in section 6 of the license.
94 @b{Ref@TeX{}} is a package for managing Labels, References,
95 Citations and index entries with GNU Emacs.@refill
97 Don't be discouraged by the size of this manual, which covers
98 @b{Ref@TeX{}} in great depth. All you need to know to use
99 @b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
100 Nutshell}). You can go back later to other parts of this document when
104 * Introduction:: Quick-Start information.
106 * Table of Contents:: A Tool to move around quickly.
107 * Labels and References:: Creating and referencing labels.
108 * Citations:: Creating Citations.
109 * Index Support:: Creating and Checking Index Entries.
110 * Viewing Cross-References:: Who references or cites what?
112 * RefTeXs Menu:: The Ref menu in the menubar.
113 * Key Bindings:: The default key bindings.
114 * Faces:: Fontification of RefTeX's buffers.
115 * Multifile Documents:: Document spread over many files.
116 * Language Support:: How to support other languages.
117 * Finding Files:: Included TeX files and BibTeX .bib files.
118 * AUCTeX:: Cooperation with AUCTeX.
119 * Optimizations:: When RefTeX is too slow.
120 * Problems and Work-Arounds:: First Aid.
121 * Imprint:: Author, Web-site, Thanks
123 * Commands:: Which are the available commands.
124 * Options:: How to extend and configure RefTeX.
125 * Keymaps and Hooks:: For customization.
126 * Changes:: A List of recent changes to RefTeX.
130 * Index:: The full index.
136 * Installation:: How to install and activate RefTeX.
137 * RefTeX in a Nutshell:: A brief summary and quick guide.
139 Labels and References
142 * Referencing Labels::
143 * Builtin Label Environments:: The environments RefTeX knows about.
144 * Defining Label Environments:: ... and environments it doesn't.
145 * Reference Info:: View the label corresponding to a \ref.
146 * xr (LaTeX package):: References to external documents.
147 * varioref (LaTeX package):: How to create \vref instead of \ref.
148 * fancyref (LaTeX package):: How to create \fref instead of \ref.
150 Defining Label Environments
152 * Theorem and Axiom:: Defined with @code{\newenvironment}.
153 * Quick Equation:: When a macro sets the label type.
154 * Figure Wrapper:: When a macro argument is a label.
155 * Adding Magic Words:: Other words for other languages.
156 * Using \eqref:: How to switch to this AMS-LaTeX macro.
157 * Non-Standard Environments:: Environments without \begin and \end
158 * Putting it Together:: How to combine many entries.
162 * Creating Citations:: How to create them.
163 * Citation Styles:: Natbib, Harvard, Chicago and Co.
164 * Citation Info:: View the corresponding database entry.
165 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
166 * Citations Outside LaTeX:: How to make citations in Emails etc.
170 * Creating Index Entries:: Macros and completion of entries.
171 * The Index Phrases File:: A special file for global indexing.
172 * Displaying and Editing the Index:: The index editor.
173 * Builtin Index Macros:: The index macros RefTeX knows about.
174 * Defining Index Macros:: ... and macros it doesn't.
176 The Index Phrases File
178 * Collecting Phrases:: Collecting from document or external.
179 * Consistency Checks:: Check for duplicates etc.
180 * Global Indexing:: The interactive indexing process.
184 * AUCTeX-RefTeX Interface:: How both packages work together
185 * Style Files:: AUCTeX's style files can support RefTeX
186 * Bib-Cite:: Hypertext reading of a document
188 Options, Keymaps, Hooks
190 * Options (Table of Contents)::
191 * Options (Defining Label Environments)::
192 * Options (Creating Labels)::
193 * Options (Referencing Labels)::
194 * Options (Creating Citations)::
195 * Options (Index Support)::
196 * Options (Viewing Cross-References)::
197 * Options (Finding Files)::
198 * Options (Optimizations)::
199 * Options (Fontification)::
207 @node Introduction, Table of Contents, , Top
208 @chapter Introduction
211 @b{Ref@TeX{}} is a specialized package for support of labels,
212 references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
213 itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
214 and @code{\index}. Using these macros usually requires looking up
215 different parts of the document and searching through BibTeX database
216 files. @b{Ref@TeX{}} automates these time--consuming tasks almost
217 entirely. It also provides functions to display the structure of a
218 document and to move around in this structure quickly.@refill
221 Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
222 in great depth. All you need to know to use @b{Ref@TeX{}} can be
223 summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
224 back later to other parts of this document when needed.
227 @xref{Imprint}, for information about who to contact for help, bug
228 reports or suggestions.
231 * Installation:: How to install and activate RefTeX.
232 * RefTeX in a Nutshell:: A brief summary and quick guide.
235 @node Installation, RefTeX in a Nutshell, , Introduction
236 @section Installation
239 @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2.
240 It was also bundled and pre--installed with XEmacs 19.16--20.x. XEmacs
241 21.x users want to install the corresponding plug-in package which is
243 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}. See
244 the XEmacs 21.x documentation on package installation for
247 Users of earlier Emacs distributions (including Emacs 19) can get a copy
248 of the @b{Ref@TeX{}} distribution from the maintainers web-page.
249 @xref{Imprint}, for more information.@refill
252 @cindex Finding files
253 @cindex BibTeX database files, not found
254 @cindex TeX files, not found
255 @cindex @code{TEXINPUTS}, environment variable
256 @cindex @code{BIBINPUTS}, environment variable
258 @b{Ref@TeX{}} needs to access all files which are part of a multifile
259 document, and the BibTeX database files requested by the
260 @code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
261 require a search path, i.e. a list of directories to check. Normally
262 this list is stored in the environment variables @code{TEXINPUTS} and
263 @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
264 systems these variables do not contain the full search path. If
265 @b{Ref@TeX{}} does not work for you because it cannot find some files,
266 read @ref{Finding Files}.
268 @section Entering @b{Ref@TeX{}} Mode
270 @findex turn-on-reftex
272 @vindex LaTeX-mode-hook
273 @vindex latex-mode-hook
274 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
275 @kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
276 files, add the following lines to your @file{.emacs} file:@refill
279 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
280 (add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
284 @node RefTeX in a Nutshell, , Installation, Introduction
285 @section @b{Ref@TeX{}} in a Nutshell
287 @cindex Getting Started
288 @cindex RefTeX in a Nutshell
289 @cindex Nutshell, RefTeX in a
293 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
294 a table of contents of the document. This buffer can display sections,
295 labels and index entries defined in the document. From the buffer, you
296 can jump quickly to every part of your document. Press @kbd{?} to get
300 @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
301 and to find the correct key for references quickly. It distinguishes
302 labels for different environments, knows about all standard
303 environments (and many others), and can be configured to recognize any
304 additional labeled environments you have defined yourself (variable
305 @code{reftex-label-alist}).@refill
309 @b{Creating Labels}@*
310 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
311 @b{Ref@TeX{}} will either
314 derive a label from context (default for section labels)
316 prompt for a label string (default for figures and tables) or
318 insert a simple label made of a prefix and a number (all other
322 Which labels are created how is configurable with the variable
323 @code{reftex-insert-label-flags}.@refill
326 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
327 (@code{reftex-reference}). This shows an outline of the document with
328 all labels of a certain type (figure, equation,...) and some label
329 context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
330 into the original buffer.@refill
335 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
336 regular expression to search in current BibTeX database files (as
337 specified in the @code{\bibliography} command) and pull out a list of
338 matches for you to choose from. The list is @emph{formatted} and
339 sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
340 (see the variable @code{reftex-cite-format} if you want to insert
341 different macros).@refill
345 @b{Ref@TeX{}} helps to enter index entries. It also compiles all
346 entries into an alphabetically sorted @file{*Index*} buffer which you
347 can use to check and edit the entries. @b{Ref@TeX{}} knows about the
348 standard index macros and can be configured to recognize any additional
349 macros you have defined (@code{reftex-index-macros}). Multiple indices
350 are supported.@refill
354 @b{Creating Index Entries}@*
355 To index the current selection or the word at point, type @kbd{C-c /}
356 (@code{reftex-index-selection-or-word}). The default macro
357 @code{reftex-index-default-macro} will be used. For a more complex entry
358 type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
359 and enter the arguments with completion.@refill
362 @b{The Index Phrases File (Delayed Indexing)}@*
363 Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
364 the current word or selection to a special @emph{index phrase file}.
365 @b{Ref@TeX{}} can later search the document for occurrences of these
366 phrases and let you interactively index the matches.@refill
369 @b{Displaying and Editing the Index}@*
370 To display the compiled index in a special buffer, type @kbd{C-c >}
371 (@code{reftex-display-index}). From that buffer you can check and edit
376 @item @b{Viewing Cross-References}@*
377 When point is on the @var{key} argument of a cross--referencing macro
378 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
379 @code{\index}, and variations) or inside a BibTeX database entry, you
380 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
381 corresponding locations in the document and associated BibTeX database
383 When the enclosing macro is @code{\cite} or @code{\ref} and no other
384 message occupies the echo area, information about the citation or label
385 will automatically be displayed in the echo area.@refill
388 @b{Multifile Documents}@*
389 Multifile Documents are fully supported. The included files must have a
390 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
391 master file. @b{Ref@TeX{}} provides cross-referencing information from
392 all parts of the document, and across document borders
393 (@file{xr.sty}).@refill
396 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
397 order to find labels and other information. It does it automatically
398 once and updates its list internally when @code{reftex-label} and
399 @code{reftex-index} are used. To enforce reparsing, call any of the
400 commands described above with a raw @kbd{C-u} prefix, or press the
401 @kbd{r} key in the label selection buffer, the table of contents
402 buffer, or the index buffer.@refill
405 @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
406 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
407 contains style files which trigger appropriate settings in
408 @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
409 additional customizations will be necessary.@refill
412 @b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,
415 (setq reftex-enable-partial-scans t)
416 (setq reftex-save-parse-info t)
417 (setq reftex-use-multiple-selection-buffers t)
420 To integrate with AUCTeX, use
422 (setq reftex-plug-into-AUCTeX t)
425 To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
426 customize the variables@refill
428 @code{reftex-label-alist} @r{(for label macros/environments)}
429 @code{reftex-section-levels} @r{(for sectioning commands)}
430 @code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
431 @code{reftex-index-macros} @r{(for @code{\index}-like macros)}
432 @code{reftex-index-default-macro} @r{(to set the default macro)}
434 If you have a large number of macros defined, you may want to write
435 an AUCTeX style file to support them with both AUCTeX and
436 @b{Ref@TeX{}}.@refill
438 @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
439 until you have picked up the key bindings. For an overview of what you
440 can do in each of the different special buffers, press @kbd{?}. Read
441 the manual if you get stuck, of if you are curious what else might be
442 available. The first part of the manual explains in
443 a tutorial way how to use and customize @b{Ref@TeX{}}. The second
444 part is a command and variable reference.@refill
447 @node Table of Contents, Labels and References, Introduction, Top
448 @chapter Table of Contents
449 @cindex @file{*toc*} buffer
450 @cindex Table of contents buffer
454 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
455 contents of the document. By default, this @file{*toc*} buffer shows
456 only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
457 can display all labels and index entries defined in the document as
460 With the cursor in any of the lines denoting a location in the
461 document, simple key strokes will display the corresponding part in
462 another window, jump to that location, or perform other actions.@refill
465 Here is a list of special commands in the @file{*toc*} buffer. A
466 summary of this information is always available by pressing
471 @tablesubheading{General}
473 Display a summary of commands.
478 @tablesubheading{Moving around}
480 Goto next entry in the table of context.
483 Goto previous entry in the table of context.
486 Goto next section heading. Useful when many labels and index entries
487 separate section headings.@refill
490 Goto previous section heading.
493 Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps
496 @tablesubheading{Access to document locations}
498 Show the corresponding location in another window. This command does
499 @emph{not} select that other window.@refill
502 Goto the location in another window.
505 Go to the location and hide the @file{*toc*} buffer. This will restore
506 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
510 @vindex reftex-highlight-selection
511 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
512 See also variable @code{reftex-highlight-selection}, @ref{Options
513 (Fontification)}.@refill
516 @vindex reftex-toc-follow-mode
517 @vindex reftex-revisit-to-follow
518 Toggle follow mode. When follow mode is active, the other window will
519 always show the location corresponding to the line at point in the
520 @file{*toc*} buffer. This is similar to pressing @key{SPC} after each
521 cursor motion. The default for this flag can be set with the variable
522 @code{reftex-toc-follow-mode}. Note that only context in files already
523 visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
524 mode. See, however, the variable
525 @code{reftex-revisit-to-follow}.@refill
528 Show calling point in another window. This is the point from where
529 @code{reftex-toc} was last called.
531 @tablesubheading{Exiting}
533 Hide the @file{*toc*} buffer, return to the position where
534 @code{reftex-toc} was last called.@refill
537 Kill the @file{*toc*} buffer, return to the position where
538 @code{reftex-toc} was last called.@refill
541 Switch to the @file{*Index*} buffer of this document. With prefix
542 @samp{2}, restrict the index to the section at point in the @file{*toc*}
545 @tablesubheading{Controlling what gets displayed}
548 @vindex reftex-toc-max-level
549 Change the maximum level of toc entries displayed in the @file{*toc*}
550 buffer. Without prefix arg, all levels will be included. With prefix
551 arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
552 @var{arg} (3 in this case). Chapters are level 1, sections are level 2.
553 The mode line @samp{T<>} indicator shows the current value. The default
554 depth can be configured with the variable
555 @code{reftex-toc-max-level}.@refill
558 @vindex reftex-toc-include-file-boundaries
559 Toggle the display of the file borders of a multifile document in the
560 @file{*toc*} buffer. The default for this flag can be set with the
561 variable @code{reftex-toc-include-file-boundaries}.@refill
564 @vindex reftex-toc-include-labels
565 Toggle the display of labels in the @file{*toc*} buffer. The default
566 for this flag can be set with the variable
567 @code{reftex-toc-include-labels}. When called with a prefix argument,
568 @b{Ref@TeX{}} will prompt for a label type and include only labels of
569 the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
570 indicator shows which labels are included.@refill
573 @vindex reftex-toc-include-index-entries
574 Toggle the display of index entries in the @file{*toc*} buffer. The
575 default for this flag can be set with the variable
576 @code{reftex-toc-include-index-entries}. When called with a prefix
577 argument, @b{Ref@TeX{}} will prompt for a specific index and include
578 only entries in the selected index in the @file{*toc*} buffer. The mode
579 line @samp{I<>} indicator shows which index is used.@refill
582 @vindex reftex-toc-include-context
583 Toggle the display of label and index context in the @file{*toc*}
584 buffer. The default for this flag can be set with the variable
585 @code{reftex-toc-include-context}.@refill
587 @tablesubheading{Updating the buffer}
590 Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
594 @vindex reftex-enable-partial-scans
595 Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
596 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
597 location is defined in, not the entire document.@refill
600 Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
604 Switch to the @file{*toc*} buffer of an external document. When the
605 current document is using the @code{xr} package (@pxref{xr (LaTeX
606 package)}), @b{Ref@TeX{}} will switch to one of the external
611 @vindex reftex-toc-map
612 In order to define additional commands for the @file{*toc*} buffer, the
613 keymap @code{reftex-toc-map} may be used.@refill
615 @cindex Sectioning commands
616 @cindex KOMA-Script, LaTeX classes
617 @cindex LaTeX classes, KOMA-Script
618 @cindex TOC entries for environments
619 @vindex reftex-section-levels
620 The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
621 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
622 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
623 Additional macros can be configured with the variable
624 @code{reftex-section-levels}. It is also possible to add certain LaTeX
625 environments to the table of contents. This is probably only useful for
626 theorem-like environments. @xref{Defining Label Environments}, for an
629 @node Labels and References, Citations, Table of Contents, Top
630 @chapter Labels and References
631 @cindex Labels in LaTeX
632 @cindex References in LaTeX
633 @cindex Label category
634 @cindex Label environment
635 @cindex @code{\label}
637 LaTeX provides a powerful mechanism to deal with cross--references in a
638 document. When writing a document, any part of it can be marked with a
639 label, like @samp{\label@{mark@}}. LaTeX records the current value of a
640 certain counter when a label is defined. Later references to this label
641 (like @samp{\ref@{mark@}}) will produce the recorded value of the
644 Labels can be used to mark sections, figures, tables, equations,
645 footnotes, items in enumerate lists etc. LaTeX is context sensitive in
646 doing this: A label defined in a figure environment automatically
647 records the figure counter, not the section counter.@refill
649 Several different environments can share a common counter and therefore
650 a common label category. E.g. labels in both @code{equation} and
651 @code{eqnarray} environments record the value of the same counter - the
652 equation counter.@refill
656 * Referencing Labels::
657 * Builtin Label Environments:: The environments RefTeX knows about.
658 * Defining Label Environments:: ... and environments it doesn't.
659 * Reference Info:: View the label corresponding to a \ref.
660 * xr (LaTeX package):: References to external documents.
661 * varioref (LaTeX package):: How to create \vref instead of \ref.
662 * fancyref (LaTeX package):: How to create \fref instead of \ref.
665 @node Creating Labels, Referencing Labels, , Labels and References
666 @section Creating Labels
667 @cindex Creating labels
668 @cindex Labels, creating
669 @cindex Labels, deriving from context
673 In order to create a label in a LaTeX document, press @kbd{C-c (}
674 (@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
675 and will figure out the environment it currently is in and adapt the
676 label to that environment. A label usually consists of a short prefix
677 indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
678 3 different modes to create this mark.@refill
682 @vindex reftex-translate-to-ascii-function
683 @vindex reftex-derive-label-parameters
684 @vindex reftex-label-illegal-re
685 @vindex reftex-abbrev-parameters
686 A label can be derived from context. This means, @b{Ref@TeX{}} takes
687 the context of the label definition and constructs a label from
688 that@footnote{Note that the context may contain constructs which are
689 illegal in labels. @b{Ref@TeX{}} will therefore strip the accent from
690 accented Latin-1 characters and remove everything else which is not
691 legal in labels. This mechanism is safe, but may not be satisfactory
692 for non-western languages. Check the following variables if you need to
693 change things: @code{reftex-translate-to-ascii-function},
694 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
695 @code{reftex-abbrev-parameters}.}. This works best for section labels,
696 where the section heading is used to construct a label. In fact,
697 @b{Ref@TeX{}}'s default settings use this method only for section
698 labels. You will be asked to confirm the derived label, or edit
702 We may also use a simple unique number to identify a label. This is
703 mostly useful for labels where it is difficult to come up with a very
704 good descriptive name. @b{Ref@TeX{}}'s default settings use this method
705 for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
706 tends to write documents with many equations and finds it impossible
707 to come up with good names for each of them. These simple labels are
708 inserted without query, and are therefore very fast. Good descriptive
709 names are not really necessary as @b{Ref@TeX{}} will provide context to
710 reference a label (@pxref{Referencing Labels}).@refill
713 The third method is to ask the user for a label. This is most
714 useful for things which are easy to describe briefly and do not turn up
715 too frequently in a document. @b{Ref@TeX{}} uses this for figures and
716 tables. Of course, one can enter the label directly by typing the full
717 @samp{\label@{mark@}}. The advantage of using @code{reftex-label}
718 anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
719 It will then not be necessary to rescan the document in order to access
720 this label later.@refill
723 @vindex reftex-insert-label-flags
724 If you want to change the way certain labels are created, check out the
725 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
728 If you are using AUCTeX to write your LaTeX documents, you can
729 set it up to delegate the creation of labels to
730 @b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
732 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
733 @section Referencing Labels
734 @cindex Referencing labels
735 @cindex Labels, referencing
736 @cindex Selection buffer, labels
737 @cindex Selection process
740 @findex reftex-reference
742 Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c
743 )} in order to reference a label (reftex-reference). This will start a
744 selection process and finally insert the complete @samp{\ref@{label@}}
745 into the buffer.@refill
747 First, @b{Ref@TeX{}} will determine the label category which is required.
748 Often that can be figured out from context. For example, if you
749 write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
750 that an equation label is going to be referenced. If it cannot figure
751 out what label category is needed, it will query for one.@refill
753 You will then be presented with a label selection menu. This is a
754 special buffer which contains an outline of the document along with all
755 labels of the given label category. In addition, next to the label
756 there will be one line of context of the label definition, which is some
757 text in the buffer near the label definition. Usually this is
758 sufficient to identify the label. If you are unsure about a certain
759 label, pressing @key{SPC} will show the label definition point in
760 another window.@refill
762 In order to reference a label, move to cursor to the correct label and
763 press @key{RET}. You can also reference several labels with a single
764 call to @code{reftex-reference} by marking entries with the @kbd{m}
768 Here is a list of special commands in the selection buffer. A summary
769 of this information is always available from the selection process by
770 pressing @kbd{?}.@refill
775 @tablesubheading{General}
777 Show a summary of available commands.
782 @tablesubheading{Moving around}
787 Go to previous label.
790 Jump back to the position where you last left the selection buffer.
791 Normally this should get you back to the last referenced label.@refill
794 Goto next section heading.
797 Goto previous section heading.
800 Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to
803 @tablesubheading{Displaying Context}
805 Show the surroundings of the definition of the current label in another
806 window. See also the @kbd{f} key.@refill
809 @vindex reftex-revisit-to-follow
810 Toggle follow mode. When follow mode is active, the other window will
811 always display the full context of the current label. This is similar
812 to pressing @key{SPC} after each cursor motion. Note that only context
813 in files already visited is shown. @b{RefTeX} will not visit a file
814 just for follow mode. See, however, the variable
815 @code{reftex-revisit-to-follow}.@refill
818 Show insertion point in another window. This is the point from where you
819 called @code{reftex-reference}.@refill
821 @tablesubheading{Selecting a label and creating the reference}
823 Insert a reference to the label at point into the buffer from which the
824 selection process was started. When entries have been marked, @key{RET}
825 references all marked labels.@refill
828 @vindex reftex-highlight-selection
829 Clicking with mouse button 2 on a label will accept it like @key{RET}
830 would. See also variable @code{reftex-highlight-selection}, @ref{Options
833 @vindex reftex-multiref-punctuation
835 Mark the current entry. When several entries have been marked, pressing
836 @kbd{RET} will accept all of them and place them into several
837 @code{\ref} macros. The special markers @samp{,-+} also store a
838 separator to be inserted before the corresponding reference. So marking
839 six entries with the keys @samp{m , , - , +} will give a reference list
840 like this (see the variable @code{reftex-multiref-punctuation})
842 In eqs. (1), (2), (3)--(4), (5) and (6)
846 Unmark a marked entry.
848 @c FIXME: Do we need `A' as well for consistency?
849 @cindex LaTeX packages, @code{saferef}
850 @cindex @code{saferef}, LaTeX package
852 Accept the marked entries and put all labels as a comma-separated list
853 into one @emph{single} @code{\ref} macro. Some packages like
854 @file{saferef.sty} support multiple references in this way.@refill
857 Use the last referenced label(s) again. This is equivalent to moving to
858 that label and pressing @key{RET}.@refill
861 Enter a label with completion. This may also be a label which does not
862 yet exist in the document.
865 @cindex @code{varioref}, LaTeX package
867 @cindex LaTeX packages, @code{varioref}
868 Toggle between @code{\ref} and @code{\vref} macro for references. The
869 @code{\vref} macro is defined in the @code{varioref} LaTeX package.
870 With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
871 macro. The current state of this flag is displayed by the @samp{S<>}
872 indicator in the mode line of the selection buffer.@refill
875 @cindex @code{fancyref}, LaTeX package
878 @cindex LaTeX packages, @code{fancyref}
879 Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The
880 @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
881 LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a
882 @code{\fref} or @code{\Fref} macro. The current state of this flag is
883 displayed by the @samp{S<>} indicator in the mode line of the
886 @tablesubheading{Exiting}
889 Exit the selection process without inserting any reference into the
892 @tablesubheading{Controlling what gets displayed}
893 @vindex reftex-label-menu-flags
894 The defaults for the following flags can be configured with the variable
895 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
898 Toggle the display of the one-line label definition context in the
899 selection buffer.@refill
902 Toggle the display of the file borders of a multifile document in the
903 selection buffer.@refill
906 Toggle the display of the table of contents in the selection buffer.
907 With prefix @var{arg}, change the maximum level of toc entries displayed
908 to @var{arg}. Chapters are level 1, section are level 2.@refill
911 Toggle the display of a label counter in the selection buffer.@refill
914 Toggle the display of labels hidden in comments in the selection
915 buffers. Sometimes, you may have commented out parts of your document.
916 If these parts contain label definitions, @b{Ref@TeX{}} can still display
917 and reference these labels.@refill
919 @tablesubheading{Updating the buffer}
921 Update the menu. This will rebuilt the menu from the internal label
922 list, but not reparse the document (see @kbd{r}).@refill
925 @vindex reftex-enable-partial-scans
926 Reparse the document to update the information on all labels and rebuild
927 the menu. If the variable @code{reftex-enable-partial-scans} is
928 non-@code{nil} and your document is a multifile document, this will
929 reparse only a part of the document (the file in which the label at
930 point was defined).@refill
933 Reparse the @emph{entire} document.
936 Switch the label category. After prompting for another label category,
937 a menu for that category will be shown.@refill
940 Reference a label from an external document. With the LaTeX package
941 @code{xr} it is possible to reference labels defined in another
942 document. This key will switch to the label menu of an external
943 document and let you select a label from there (@pxref{xr (LaTeX
944 package),,xr}).@refill
948 @vindex reftex-select-label-map
949 In order to define additional commands for the selection process, the
950 keymap @code{reftex-select-label-map} may be used.@refill
952 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
953 @section Builtin Label Environments
954 @cindex Builtin label environments
955 @cindex Label environments, builtin
956 @cindex Environments, builtin
957 @vindex reftex-label-alist
958 @vindex reftex-label-alist-builtin
960 @b{Ref@TeX{}} needs to be aware of the environments which can be referenced
961 with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}
962 recognizes all labeled environments and macros discussed in @cite{The
963 LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
964 1994.}. These are:@refill
968 @cindex @code{figure}, LaTeX environment
969 @cindex @code{figure*}, LaTeX environment
970 @cindex @code{table}, LaTeX environment
971 @cindex @code{table*}, LaTeX environment
972 @cindex @code{equation}, LaTeX environment
973 @cindex @code{eqnarray}, LaTeX environment
974 @cindex @code{enumerate}, LaTeX environment
975 @cindex @code{\footnote}, LaTeX macro
976 @cindex LaTeX macro @code{footnote}
978 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
979 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
980 the LaTeX core stuff)@refill
983 @cindex @code{amsmath}, LaTeX package
984 @cindex LaTeX packages, @code{amsmath}
985 @cindex @code{align}, AMS-LaTeX environment
986 @cindex @code{gather}, AMS-LaTeX environment
987 @cindex @code{multline}, AMS-LaTeX environment
988 @cindex @code{flalign}, AMS-LaTeX environment
989 @cindex @code{alignat}, AMS-LaTeX environment
990 @cindex @code{xalignat}, AMS-LaTeX environment
991 @cindex @code{xxalignat}, AMS-LaTeX environment
992 @cindex @code{subequations}, AMS-LaTeX environment
993 @code{align}, @code{gather}, @code{multline}, @code{flalign},
994 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
995 (from AMS-LaTeX's @file{amsmath.sty} package)@refill
997 @cindex @code{endnote}, LaTeX package
998 @cindex LaTeX packages, @code{endnote}
999 @cindex @code{\endnote}, LaTeX macro
1000 the @code{\endnote} macro (from @file{endnotes.sty})
1002 @cindex @code{fancybox}, LaTeX package
1003 @cindex LaTeX packages, @code{fancybox}
1004 @cindex @code{Beqnarray}, LaTeX environment
1005 @code{Beqnarray} (@file{fancybox.sty})
1007 @cindex @code{floatfig}, LaTeX package
1008 @cindex LaTeX packages, @code{floatfig}
1009 @cindex @code{floatingfig}, LaTeX environment
1010 @code{floatingfig} (@file{floatfig.sty})
1012 @cindex @code{longtable}, LaTeX package
1013 @cindex LaTeX packages, @code{longtable}
1014 @cindex @code{longtable}, LaTeX environment
1015 @code{longtable} (@file{longtable.sty})
1017 @cindex @code{picinpar}, LaTeX package
1018 @cindex LaTeX packages, @code{picinpar}
1019 @cindex @code{figwindow}, LaTeX environment
1020 @cindex @code{tabwindow}, LaTeX environment
1021 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1023 @cindex @code{sidecap}, LaTeX package
1024 @cindex LaTeX packages, @code{sidecap}
1025 @cindex @code{SCfigure}, LaTeX environment
1026 @cindex @code{SCtable}, LaTeX environment
1027 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1029 @cindex @code{rotating}, LaTeX package
1030 @cindex LaTeX packages, @code{rotating}
1031 @cindex @code{sidewaysfigure}, LaTeX environment
1032 @cindex @code{sidewaystable}, LaTeX environment
1033 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1035 @cindex @code{subfig}, LaTeX package
1036 @cindex LaTeX packages, @code{subfigure}
1037 @cindex @code{subfigure}, LaTeX environment
1038 @cindex @code{subfigure*}, LaTeX environment
1039 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1040 (@file{subfigure.sty})@refill
1042 @cindex @code{supertab}, LaTeX package
1043 @cindex LaTeX packages, @code{supertab}
1044 @cindex @code{supertabular}, LaTeX environment
1045 @code{supertabular} (@file{supertab.sty})
1047 @cindex @code{wrapfig}, LaTeX package
1048 @cindex LaTeX packages, @code{wrapfig}
1049 @cindex @code{wrapfigure}, LaTeX environment
1050 @code{wrapfigure} (@file{wrapfig.sty})
1053 If you want to use other labeled environments, defined with
1054 @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
1055 them (@pxref{Defining Label Environments}).@refill
1057 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1058 @section Defining Label Environments
1059 @cindex Label environments, defining
1061 @vindex reftex-label-alist
1062 @b{Ref@TeX{}} can be configured to recognize additional labeled
1063 environments and macros. This is done with the variable
1064 @code{reftex-label-alist} (@pxref{Options (Defining Label
1065 Environments)}). If you are not familiar with Lisp, you can use the
1066 @code{custom} library to configure this rather complex variable. To do
1070 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1073 @vindex reftex-label-alist-builtin
1074 Here we will discuss a few examples, in order to make things clearer.
1075 It can also be instructive to look at the constant
1076 @code{reftex-label-alist-builtin} which contains the entries for
1077 all the builtin environments and macros (@pxref{Builtin Label
1078 Environments}).@refill
1081 * Theorem and Axiom:: Defined with @code{\newenvironment}.
1082 * Quick Equation:: When a macro sets the label type.
1083 * Figure Wrapper:: When a macro argument is a label.
1084 * Adding Magic Words:: Other words for other languages.
1085 * Using \eqref:: How to switch to this AMS-LaTeX macro.
1086 * Non-Standard Environments:: Environments without \begin and \end
1087 * Putting it Together:: How to combine many entries.
1090 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1091 @subsection Theorem and Axiom Environments
1092 @cindex @code{theorem}, newtheorem
1093 @cindex @code{axiom}, newtheorem
1094 @cindex @code{\newtheorem}
1096 Suppose you are using @code{\newtheorem} in LaTeX in order to define two
1097 new environments, @code{theorem} and @code{axiom}@refill
1100 \newtheorem@{axiom@}@{Axiom@}
1101 \newtheorem@{theorem@}@{Theorem@}
1105 to be used like this:
1114 So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
1115 labeled environments which define their own label categories. We can
1116 either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
1117 library. With Lisp it would look like this
1120 (setq reftex-label-alist
1121 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1122 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3)))
1125 The type indicator characters @code{?a} and @code{?h} are used for
1126 prompts when @b{Ref@TeX{}} queries for a label type. @code{?h}
1127 was chosen for @code{theorem} since @code{?t} is already taken by
1128 @code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
1129 @code{?i}, @code{?n} are already used for standard environments.@refill
1132 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1133 @samp{thr:}, respectively. @xref{AUCTeX}, for information on how
1134 AUCTeX can use RefTeX to automatically create labels when a new environment
1135 is inserted into a buffer. Additionally, the following needs to be
1136 added to one's .emacs file before AUCTeX will automatically create
1137 labels for the new environments.
1140 (add-hook 'LaTeX-mode-hook
1142 (LaTeX-add-environments
1143 '("axiom" LaTeX-env-label)
1144 '("theorem" LaTeX-env-label))))
1149 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1150 references to these labels.@refill
1153 The next item indicates how to grab context of the label definition.@refill
1156 @code{t} means to get it from a default location (from the beginning of
1157 a @code{\macro} or after the @code{\begin} statement). @code{t} is
1158 @emph{not} a good choice for eqnarray and similar environments.@refill
1160 @code{nil} means to use the text right after the label definition.@refill
1162 For more complex ways of getting context, see the variable
1163 @code{reftex-label-alist} (@ref{Options (Defining Label
1164 Environments)}).@refill
1167 The following list of strings is used to guess the correct label type
1168 from the word before point when creating a reference. E.g. if you
1169 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1170 @b{Ref@TeX{}} will know that you are looking for a theorem label and
1171 restrict the menu to only these labels without even asking.@refill
1173 The final item in each entry is the level at which the environment
1174 should produce entries in the table of context buffer. If the number is
1175 positive, the environment will produce numbered entries (like
1176 @code{\section}), if it is negative the entries will be unnumbered (like
1177 @code{\section*}). Use this only for environments which structure the
1178 document similar to sectioning commands. For everything else, omit the
1181 To do the same configuration with @code{customize}, you need to click on
1182 the @code{[INS]} button twice to create two templates and fill them in
1186 Reftex Label Alist: [Hide]
1187 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1188 Environment or \macro : [Value Menu] String: axiom
1189 Type specification : [Value Menu] Char : a
1190 Label prefix string : [Value Menu] String: ax:
1191 Label reference format: [Value Menu] String: ~\ref@{%s@}
1192 Context method : [Value Menu] After label
1194 [INS] [DEL] String: axiom
1195 [INS] [DEL] String: ax.
1197 [X] Make TOC entry : [Value Menu] Level: -2
1198 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1199 Environment or \macro : [Value Menu] String: theorem
1200 Type specification : [Value Menu] Char : h
1201 Label prefix string : [Value Menu] String: thr:
1202 Label reference format: [Value Menu] String: ~\ref@{%s@}
1203 Context method : [Value Menu] Default position
1205 [INS] [DEL] String: theorem
1206 [INS] [DEL] String: theor.
1207 [INS] [DEL] String: th.
1209 [X] Make TOC entry : [Value Menu] Level: -3
1212 @vindex reftex-insert-label-flags
1213 @vindex reftex-label-menu-flags
1214 Depending on how you would like the label insertion and selection for
1215 the new environments to work, you might want to add the letters @samp{a}
1216 and @samp{h} to some of the flags in the variables
1217 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1218 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1222 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1223 @subsection Quick Equation Macro
1224 @cindex Quick equation macro
1225 @cindex Macros as environment wrappers
1227 Suppose you would like to have a macro for quick equations. It
1228 could be defined like this:
1231 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1238 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1241 We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
1242 @code{\quickeq} is an equation label. Here is how to do this with lisp:
1245 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1248 The first element in this list is now the macro with empty braces as an
1249 @emph{image} of the macro arguments. @code{?e} indicates that this is
1250 an equation label, the different @code{nil} elements indicate to use the
1251 default values for equations. The @samp{1} as the fifth element
1252 indicates that the context of the label definition should be the 1st
1253 argument of the macro.@refill
1255 Here is again how this would look in the customization buffer:
1258 Reftex Label Alist: [Hide]
1259 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1260 Environment or \macro : [Value Menu] String: \quickeq@{@}
1261 Type specification : [Value Menu] Char : e
1262 Label prefix string : [Value Menu] Default
1263 Label reference format: [Value Menu] Default
1264 Context method : [Value Menu] Macro arg nr: 1
1267 [ ] Make TOC entry : [Value Menu] No entry
1270 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1271 @subsection Figure Wrapping Macro
1272 @cindex Macros as environment wrappers
1273 @cindex Figure wrapping macro
1275 Suppose you want to make figures not directly with the figure
1276 environment, but with a macro like
1279 \newcommand@{\myfig@}[5][tbp]@{%
1280 \begin@{figure@}[#1]
1288 which would be called like
1291 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1294 Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
1295 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1299 (setq reftex-label-alist
1300 '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1303 The empty pairs of brackets indicate the different arguments of the
1304 @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
1305 indicates that this is a figure label which will be listed together with
1306 labels from normal figure environments. The @code{nil} entries for
1307 prefix and reference format mean to use the defaults for figure labels.
1308 The @samp{3} for the context method means to grab the 3rd macro argument
1309 - the caption.@refill
1311 As a side effect of this configuration, @code{reftex-label} will now
1312 insert the required naked label (without the @code{\label} macro) when
1313 point is directly after the opening parenthesis of a @code{\myfig} macro
1316 Again, here the configuration in the customization buffer:
1319 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1320 Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1321 Type specification : [Value Menu] Char : f
1322 Label prefix string : [Value Menu] Default
1323 Label reference format: [Value Menu] Default
1324 Context method : [Value Menu] Macro arg nr: 3
1327 [ ] Make TOC entry : [Value Menu] No entry
1330 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1331 @subsection Adding Magic Words
1333 @cindex German magic words
1334 @cindex Label category
1336 Sometimes you don't want to define a new label environment or macro, but
1337 just change the information associated with a label category. Maybe you
1338 want to add some magic words, for another language. Changing only the
1339 information associated with a label category is done by giving
1340 @code{nil} for the environment name and then specify the items you want
1341 to define. Here is an example which adds German magic words to all
1342 predefined label categories.@refill
1345 (setq reftex-label-alist
1346 '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1347 (nil ?e nil nil nil ("Gleichung" "Gl."))
1348 (nil ?t nil nil nil ("Tabelle"))
1349 (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1350 (nil ?n nil nil nil ("Anmerkung" "Anm."))
1351 (nil ?i nil nil nil ("Punkt"))))
1354 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1355 @subsection Using @code{\eqref}
1356 @cindex @code{\eqref}, AMS-LaTeX macro
1358 @cindex Label category
1360 Another case where one only wants to change the information associated
1361 with the label category is to change the macro which is used for
1362 referencing the label. When working with the AMS-LaTeX stuff, you might
1363 prefer @code{\eqref} for doing equation references. Here is how to
1367 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1370 @b{Ref@TeX{}} has also a predefined symbol for this special purpose. The
1371 following is equivalent to the line above.@refill
1374 (setq reftex-label-alist '(AMSTeX))
1377 Note that this is automatically done by the @file{amsmath.el} style file
1378 of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
1379 this configuration will not be necessary.@refill
1381 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1382 @subsection Non-standard Environments
1383 @cindex Non-standard environments
1384 @cindex Environments without @code{\begin}
1385 @cindex Special parser functions
1386 @cindex Parser functions, for special environments
1388 Some LaTeX packages define environment-like structures without using the
1389 standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse
1390 these directly, but you can write your own special-purpose parser and
1391 use it instead of the name of an environment in an entry for
1392 @code{reftex-label-alist}. The function should check if point is
1393 currently in the special environment it was written to detect. If so,
1394 it must return a buffer position indicating the start of this
1395 environment. The return value must be @code{nil} on failure to detect
1396 the environment. The function is called with one argument @var{bound}.
1397 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1398 which should be observed. We will discuss two examples.@refill
1400 @cindex LaTeX commands, abbreviated
1402 Some people define abbreviations for
1403 environments, like @code{\be} for @code{\begin@{equation@}}, and
1404 @code{\ee} for @code{\end@{equation@}}. The parser function would have
1405 to search backward for these macros. When the first match is
1406 @code{\ee}, point is not in this environment. When the first match is
1407 @code{\be}, point is in this environment and the function must return
1408 the beginning of the match. To avoid scanning too far, we can also look
1409 for empty lines which cannot occur inside an equation environment.
1410 Here is the setup:@refill
1413 ;; Setup entry in reftex-label-alist, using all defaults for equations
1414 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1416 (defun detect-be-ee (bound)
1417 ;; Search backward for the macros or an empty line
1418 (if (re-search-backward
1419 "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1420 (if (match-beginning 2)
1421 (match-beginning 2) ; Return start of environment
1422 nil) ; Return nil because env is closed
1423 nil)) ; Return nil for not found
1426 @cindex @code{linguex}, LaTeX package
1427 @cindex LaTeX packages, @code{linguex}
1428 A more complex example is the @file{linguex.sty} package which defines
1429 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1430 terminated by @samp{\z.} or by an empty line.@refill
1433 \ex. \label@{ex:12@} Some text in an exotic language ...
1434 \a. \label@{ex:13@} more stuff
1435 \b. \label@{ex:14@} still more stuff
1436 \a. List on a deeper level
1438 \b. and the third one
1440 \b. Third item on this level.
1442 ... text after the empty line terminating all lists
1445 The difficulty is that the @samp{\a.} lists can nest and that an empty
1446 line terminates all list levels in one go. So we have to count nesting
1447 levels between @samp{\a.} and @samp{\z.}. Here is the implementation
1451 (setq reftex-label-alist
1452 '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1454 (defun detect-linguex (bound)
1458 ;; Search backward for all possible delimiters
1460 (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1461 "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1463 ;; Check which delimiter was matched.
1465 ((match-beginning 1)
1466 ;; empty line terminates all - return nil
1468 ((match-beginning 2)
1469 ;; \z. terminates one list level - decrease nesting count
1471 ((match-beginning 3)
1472 ;; \ex. : return match unless there was a \z. on this level
1473 (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1474 ((match-beginning 4)
1475 ;; \a. : return match when on level 0, otherwise
1476 ;; increment nesting count
1478 (throw 'exit (match-beginning 4))
1482 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1483 @subsection Putting it all together
1485 When you have to put several entries into @code{reftex-label-alist}, just
1486 put them after each other in a list, or create that many templates in
1487 the customization buffer. Here is a lisp example which uses several of
1488 the entries described above:
1491 (setq reftex-label-alist
1492 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1493 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3)
1494 ("\\quickeq@{@}" ?e nil nil 1 nil)
1496 ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1497 (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1500 @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
1501 @section Reference Info
1502 @findex reftex-view-crossref
1503 @findex reftex-mouse-view-crossref
1504 @cindex Cross-references, displaying
1505 @cindex Reference info
1506 @cindex Displaying cross-references
1507 @cindex Viewing cross-references
1511 When point is idle on the argument of a @code{\ref} macro, the echo area
1512 will display some information about the label referenced there. Note
1513 that the information is only displayed if the echo area is not occupied
1514 by a different message.
1516 @b{Ref@TeX{}} can also display the label definition corresponding to a
1517 @code{\ref} macro, or all reference locations corresponding to a
1518 @code{\label} macro. @xref{Viewing Cross-References}, for more
1521 @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
1522 @section @code{xr}: Cross-Document References
1523 @cindex @code{xr}, LaTeX package
1524 @cindex LaTeX packages, @code{xr}
1525 @cindex @code{\externaldocument}
1526 @cindex External documents
1527 @cindex References to external documents
1528 @cindex Cross-document references
1530 The LaTeX package @code{xr} makes it possible to create references to
1531 labels defined in external documents. The preamble of a document using
1532 @code{xr} will contain something like this:@refill
1536 \externaldocument[V1-]@{volume1@}
1537 \externaldocument[V3-]@{volume3@}
1541 and we can make references to any labels defined in these
1542 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1543 respectively.@refill
1545 @b{Ref@TeX{}} can be used to create such references as well. Start the
1546 referencing process normally, by pressing @kbd{C-c )}. Select a label
1547 type if necessary. When you see the label selection buffer, pressing
1548 @kbd{x} will switch to the label selection buffer of one of the external
1549 documents. You may then select a label as before and @b{Ref@TeX{}} will
1550 insert it along with the required prefix.@refill
1552 For this kind of inter-document cross-references, saving of parsing
1553 information and the use of multiple selection buffers can mean a large
1554 speed-up (@pxref{Optimizations}).@refill
1556 @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
1557 @section @code{varioref}: Variable Page References
1558 @cindex @code{varioref}, LaTeX package
1559 @cindex @code{\vref}
1560 @cindex LaTeX packages, @code{varioref}
1561 @vindex reftex-vref-is-default
1562 @code{varioref} is a frequently used LaTeX package to create
1563 cross--references with page information. When you want to make a
1564 reference with the @code{\vref} macro, just press the @kbd{v} key in the
1565 selection buffer to toggle between @code{\ref} and @code{\vref}
1566 (@pxref{Referencing Labels}). The mode line of the selection buffer
1567 shows the current status of this switch. If you find that you almost
1568 always use @code{\vref}, you may want to make it the default by
1569 customizing the variable @code{reftex-vref-is-default}. If this
1570 toggling seems too inconvenient, you can also use the command
1571 @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
1572 Or use AUCTeX to create your macros (@pxref{AUCTeX}).@refill
1574 @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
1575 @section @code{fancyref}: Fancy Cross References
1576 @cindex @code{fancyref}, LaTeX package
1577 @cindex @code{\fref}
1578 @cindex @code{\Fref}
1579 @cindex LaTeX packages, @code{fancyref}
1580 @vindex reftex-fref-is-default
1581 @code{fancyref} is a LaTeX package where a macro call like
1582 @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
1583 the referenced counter but also the complete text around it, like
1584 @samp{Figure 3 on the preceding page}. In order to make it work you
1585 need to use label prefixes like @samp{fig:} consistently - something
1586 @b{Ref@TeX{}} does automatically. When you want to make a reference
1587 with the @code{\fref} macro, just press the @kbd{V} key in the selection
1588 buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
1589 (@pxref{Referencing Labels}). The mode line of the selection buffer
1590 shows the current status of this switch. If this cycling seems
1591 inconvenient, you can also use the commands @code{reftex-fancyref-fref}
1592 and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
1593 f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros
1594 (@pxref{AUCTeX}).@refill
1596 @node Citations, Index Support, Labels and References, Top
1599 @cindex @code{\cite}
1601 Citations in LaTeX are done with the @code{\cite} macro or variations of
1602 it. The argument of the macro is a citation key which identifies an
1603 article or book in either a BibTeX database file or in an explicit
1604 @code{thebibliography} environment in the document. @b{Ref@TeX{}}'s
1605 support for citations helps to select the correct key quickly.@refill
1608 * Creating Citations:: How to create them.
1609 * Citation Styles:: Natbib, Harvard, Chicago and Co.
1610 * Citation Info:: View the corresponding database entry.
1611 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
1612 * Citations Outside LaTeX:: How to make citations in Emails etc.
1615 @node Creating Citations, Citation Styles, , Citations
1616 @section Creating Citations
1617 @cindex Creating citations
1618 @cindex Citations, creating
1619 @findex reftex-citation
1621 @cindex Selection buffer, citations
1622 @cindex Selection process
1624 In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then
1625 prompts for a regular expression which will be used to search through
1626 the database and present the list of matches to choose from in a
1627 selection process similar to that for selecting labels
1628 (@pxref{Referencing Labels}).@refill
1630 The regular expression uses an extended syntax: @samp{&&} defines a
1631 logic @code{and} for regular expressions. For example
1632 @samp{Einstein&&Bose} will match all articles which mention
1633 Bose-Einstein condensation, or which are co-authored by Bose and
1634 Einstein. When entering the regular expression, you can complete on
1635 known citation keys. RefTeX also offers a default when prompting for a
1636 regular expression. This default is the word before the cursor or the
1637 word before the current @samp{\cite} command. Sometimes this may be a
1638 good search key.@refill
1640 @cindex @code{\bibliography}
1641 @cindex @code{thebibliography}, LaTeX environment
1642 @cindex @code{BIBINPUTS}, environment variable
1643 @cindex @code{TEXBIB}, environment variable
1644 @b{Ref@TeX{}} prefers to use BibTeX database files specified with a
1645 @code{\bibliography} macro to collect its information. Just like
1646 BibTeX, it will search for the specified files in the current directory
1647 and along the path given in the environment variable @code{BIBINPUTS}.
1648 If you do not use BibTeX, but the document contains an explicit
1649 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
1650 information from there. Note that in this case the information
1651 presented in the selection buffer will just be a copy of relevant
1652 @code{\bibitem} entries, not the structured listing available with
1653 BibTeX database files.@refill
1656 In the selection buffer, the following keys provide special commands. A
1657 summary of this information is always available from the selection
1658 process by pressing @kbd{?}.@refill
1661 @tablesubheading{General}
1663 Show a summary of available commands.
1668 @tablesubheading{Moving around}
1673 Go to previous article.
1675 @tablesubheading{Access to full database entries}
1677 Show the database entry corresponding to the article at point, in
1678 another window. See also the @kbd{f} key.@refill
1681 Toggle follow mode. When follow mode is active, the other window will
1682 always display the full database entry of the current article. This is
1683 equivalent to pressing @key{SPC} after each cursor motion. With BibTeX
1684 entries, follow mode can be rather slow.@refill
1686 @tablesubheading{Selecting entries and creating the citation}
1688 Insert a citation referencing the article at point into the buffer from
1689 which the selection process was started.@refill
1692 @vindex reftex-highlight-selection
1693 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1694 would. See also variable @code{reftex-highlight-selection}, @ref{Options
1698 Mark the current entry. When one or several entries are marked,
1699 pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
1700 @key{RET} behaves like the @kbd{a} key.
1703 Unmark a marked entry.
1706 Accept all (marked) entries in the selection buffer and create a single
1707 @code{\cite} macro referring to them.@refill
1710 Accept all (marked) entries in the selection buffer and create a
1711 separate @code{\cite} macro for each of it.@refill
1714 Enter a citation key with completion. This may also be a key which does
1718 Show insertion point in another window. This is the point from where you
1719 called @code{reftex-citation}.@refill
1721 @tablesubheading{Exiting}
1723 Exit the selection process without inserting a citation into the
1726 @tablesubheading{Updating the buffer}
1729 Start over with a new regular expression. The full database will be
1730 rescanned with the new expression (see also @kbd{r}).@refill
1732 @c FIXME: Should we use something else here? r is usually rescan!
1734 Refine the current selection with another regular expression. This will
1735 @emph{not} rescan the entire database, but just the already selected
1740 @vindex reftex-select-bib-map
1741 In order to define additional commands for this selection process, the
1742 keymap @code{reftex-select-bib-map} may be used.@refill
1744 @node Citation Styles, Citation Info, Creating Citations, Citations
1745 @section Citation Styles
1746 @cindex Citation styles
1747 @cindex Citation styles, @code{natbib}
1748 @cindex Citation styles, @code{harvard}
1749 @cindex Citation styles, @code{chicago}
1750 @cindex @code{natbib}, citation style
1751 @cindex @code{harvard}, citation style
1752 @cindex @code{chicago}, citation style
1754 @vindex reftex-cite-format
1755 The standard LaTeX macro @code{\cite} works well with numeric or simple
1756 key citations. To deal with the more complex task of author-year
1757 citations as used in many natural sciences, a variety of packages has
1758 been developed which define derived forms of the @code{\cite} macro.
1759 @b{Ref@TeX{}} can be configured to produce these citation macros as well by
1760 setting the variable @code{reftex-cite-format}. For the most commonly
1761 used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
1762 be done from the menu, under @code{Ref->Citation Styles}. Since there
1763 are usually several macros to create the citations, executing
1764 @code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
1765 macro. For the Natbib style, this looks like this:
1768 SELECT A CITATION FORMAT
1775 [e] \citep[e.g.][]@{%l@}
1776 [s] \citep[see][]@{%l@}
1777 [a] \citeauthor@{%l@}
1778 [A] \citeauthor*@{%l@}
1782 Following the most generic of these packages, @code{natbib}, the builtin
1783 citation packages always accept the @kbd{t} key for a @emph{textual}
1784 citation (like: @code{Jones et al. (1997) have shown...}) as well as
1785 the @kbd{p} key for a parenthetical citation (like: @code{As shown
1786 earlier (Jones et al, 1997)}).@refill
1788 To make one of these styles the default, customize the variable
1789 @code{reftex-cite-format} or put into @file{.emacs}:
1792 (setq reftex-cite-format 'natbib)
1795 You can also use AUCTeX style files to automatically set the
1796 citation style based on the @code{usepackage} commands in a given
1797 document. @xref{Style Files}, for information on how to set up the style
1798 files correctly.@refill
1800 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
1801 @section Citation Info
1802 @cindex Displaying citations
1803 @cindex Citations, displaying
1804 @cindex Citation info
1805 @cindex Viewing citations
1808 @findex reftex-view-crossref
1809 @findex reftex-mouse-view-crossref
1811 When point is idle on the argument of a @code{\cite} macro, the echo area
1812 will display some information about the article cited there. Note
1813 that the information is only displayed if the echo area is not occupied
1814 by a different message.
1816 @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
1817 entry corresponding to a @code{\cite} macro, or all citation locations
1818 corresponding to a @code{\bibitem} or BibTeX database entry.
1819 @xref{Viewing Cross-References}.@refill
1821 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
1822 @section Chapterbib and Bibunits
1823 @cindex @code{chapterbib}, LaTeX package
1824 @cindex @code{bibunits}, LaTeX package
1825 @cindex Bibliographies, multiple
1827 @code{chapterbib} and @code{bibunits} are two LaTeX packages which
1828 produce multiple bibliographies in a document. This is no problem for
1829 @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
1830 files. If they do not, it is best to have each document part in a
1831 separate file (as it is required for @code{chapterbib} anyway). Then
1832 @b{Ref@TeX{}} will still scan the locally relevant databases correctly. If
1833 you have multiple bibliographies within a @emph{single file}, this may
1834 or may not be the case.
1836 @node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations
1837 @section Citations outside LaTeX
1838 @cindex Citations outside LaTeX
1839 @vindex reftex-default-bibliography
1841 The command @code{reftex-citation} can also be executed outside a LaTeX
1842 buffer. This can be useful to reference articles in the mail buffer and
1843 other documents. You should @emph{not} enter @code{reftex-mode} for
1844 this, just execute the command. The list of BibTeX files will in this
1845 case be taken from the variable @code{reftex-default-bibliography}.
1846 Setting the variable @code{reftex-cite-format} to the symbol
1847 @code{locally} does a decent job of putting all relevant information
1848 about a citation directly into the buffer. Here is the lisp code to add
1849 the @kbd{C-c [} binding to the mail buffer. It also provides a local
1850 binding for @code{reftex-cite-format}.@refill
1853 (add-hook 'mail-setup-hook
1854 (lambda () (define-key mail-mode-map "\C-c["
1855 (lambda () (interactive)
1857 (let ((reftex-cite-format 'locally))
1858 (reftex-citation))))))
1861 @node Index Support, Viewing Cross-References, Citations, Top
1862 @chapter Index Support
1863 @cindex Index Support
1864 @cindex @code{\index}
1866 LaTeX has builtin support for creating an Index. The LaTeX core
1867 supports two different indices, the standard index and a glossary. With
1868 the help of special LaTeX packages (@file{multind.sty} or
1869 @file{index.sty}), any number of indices can be supported.
1871 Index entries are created with the @code{\index@{@var{entry}@}} macro.
1872 All entries defined in a document are written out to the @file{.aux}
1873 file. A separate tool must be used to convert this information into a
1874 nicely formatted index. Tools used with LaTeX include @code{MakeIndex}
1875 and @code{xindy}.@refill
1877 Indexing is a very difficult task. It must follow strict conventions to
1878 make the index consistent and complete. There are basically two
1879 approaches one can follow, and both have their merits.
1883 Part of the indexing should already be done with the markup. The
1884 document structure should be reflected in the index, so when starting
1885 new sections, the basic topics of the section should be indexed. If the
1886 document contains definitions, theorems or the like, these should all
1887 correspond to appropriate index entries. This part of the index can
1888 very well be developed along with the document. Often it is worthwhile
1889 to define special purpose macros which define an item and at the same
1890 time make an index entry, possibly with special formatting to make the
1891 reference page in the index bold or underlined. To make @b{Ref@TeX{}}
1892 support for indexing possible, these special macros must be added to
1893 @b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}).@refill
1896 The rest of the index is often just a collection of where in the
1897 document certain words or phrases are being used. This part is
1898 difficult to develop along with the document, because consistent entries
1899 for each occurrence are needed and are best selected when the document
1900 is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file}
1901 which collects phrases and helps indexing the phrases globally.@refill
1904 Before you start, you need to make sure that @b{Ref@TeX{}} knows about
1905 the index style being used in the current document. @b{Ref@TeX{}} has
1906 builtin support for the default @code{\index} and @code{\glossary}
1907 macros. Other LaTeX packages, like the @file{multind} or @file{index}
1908 package, redefine the @code{\index} macro to have an additional
1909 argument, and @b{Ref@TeX{}} needs to be configured for those. A
1910 sufficiently new version of AUCTeX (9.10c or later) will do this
1911 automatically. If you really don't use AUCTeX (you should!), this
1912 configuration needs to be done by hand with the menu (@code{Ref->Index
1913 Style}), or globally for all your documents with@refill
1916 (setq reftex-index-macros '(multind)) @r{or}
1917 (setq reftex-index-macros '(index))
1921 * Creating Index Entries:: Macros and completion of entries.
1922 * The Index Phrases File:: A special file for global indexing.
1923 * Displaying and Editing the Index:: The index editor.
1924 * Builtin Index Macros:: The index macros RefTeX knows about.
1925 * Defining Index Macros:: ... and macros it doesn't.
1928 @node Creating Index Entries, The Index Phrases File, , Index Support
1929 @section Creating Index Entries
1930 @cindex Creating index entries
1931 @cindex Index entries, creating
1933 @findex reftex-index
1935 @findex reftex-index-selection-or-word
1937 In order to index the current selection or the word at the cursor press
1938 @kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
1939 selection or word @samp{@var{word}} to be replaced with
1940 @samp{\index@{@var{word}@}@var{word}}. The macro which is used
1941 (@code{\index} by default) can be configured with the variable
1942 @code{reftex-index-default-macro}. When the command is called with a
1943 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
1944 generated index entry. Use this to change the case of the word or to
1945 make the entry a subentry, for example by entering
1946 @samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
1947 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
1948 When there is nothing selected and no word at point, this command will
1949 just call @code{reftex-index}, described below.
1951 In order to create a general index entry, press @kbd{C-c <}
1952 (@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the
1953 available index macros and for its arguments. Completion will be
1954 available for the index entry and, if applicable, the index tag. The
1955 index tag is a string identifying one of multiple indices. With the
1956 @file{multind} and @file{index} packages, this tag is the first argument
1957 to the redefined @code{\index} macro.@refill
1959 @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
1960 @section The Index Phrases File
1961 @cindex Index phrase file
1964 @findex reftex-index-visit-phrases-buffer
1965 @cindex Macro definition lines, in phrase buffer
1967 @b{Ref@TeX{}} maintains a file in which phrases can be collected for
1968 later indexing. The file is located in the same directory as the master
1969 file of the document and has the extension @file{.rip} (@b{R}eftex
1970 @b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c
1971 |} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it
1972 is initialized by inserting a file header which contains the definition
1973 of the available index macros. This list is initialized from
1974 @code{reftex-index-macros} (@pxref{Defining Index Macros}). You can
1975 edit the header as needed, but if you define new LaTeX indexing macros,
1976 don't forget to add them to @code{reftex-index-macros} as well. Here is
1977 a phrase file header example:@refill
1980 % -*- mode: reftex-index-phrases -*-
1981 % Key Macro Format Repeat
1982 %----------------------------------------------------------
1983 >>>INDEX_MACRO_DEFINITION: i \index@{%s@} t
1984 >>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil
1985 >>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t
1986 >>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil
1987 %----------------------------------------------------------
1990 The macro definition lines consist of a unique letter identifying a
1991 macro, a format string and the @var{repeat} flag, all separated by
1992 @key{TAB}. The format string shows how the macro is to be applied, the
1993 @samp{%s} will be replaced with the index entry. The repeat flag
1994 indicates if @var{word} is indexed by the macro as
1995 @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
1996 @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the
1997 above example it is assumed that the macro @code{\index*@{@var{word}@}}
1998 already typesets its argument in the text, so that it is unnecessary to
1999 repeat @var{word} outside the macro.@refill
2002 * Collecting Phrases:: Collecting from document or external.
2003 * Consistency Checks:: Check for duplicates etc.
2004 * Global Indexing:: The interactive indexing process.
2007 @node Collecting Phrases, Consistency Checks, , The Index Phrases File
2008 @subsection Collecting Phrases
2009 @cindex Collecting index phrases
2010 @cindex Index phrases, collection
2011 @cindex Phrases, collecting
2013 Phrases for indexing can be collected while writing the document. The
2014 command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2015 copies the current selection (if active) or the word near point into the
2016 phrases buffer. It then selects this buffer, so that the phrase line
2017 can be edited. To return to the LaTeX document, press @kbd{C-c C-c}
2018 (@code{reftex-index-phrases-save-and-return}).
2020 You can also prepare the list of index phrases in a different way and
2021 copy it into the phrases file. For example you might want to start from
2022 a word list of the document and remove all words which should not be
2025 The phrase lines in the phrase buffer must have a specific format.
2026 @b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
2027 format. A phrase line looks like this:
2030 [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
2033 @code{<TABs>} stands for white space containing at least one @key{TAB}.
2034 @var{key} must be at the start of the line and is the character
2035 identifying one of the macros defined in the file header. It is
2036 optional - when omitted, the first macro definition line in the file
2037 will be used for this phrase. The @var{phrase} is the phrase to be
2038 searched for when indexing. It may contain several words separated by
2039 spaces. By default the search phrase is also the text entered as
2040 argument of the index macro. If you want the index entry to be
2041 different from the search phrase, enter another @key{TAB} and the index
2042 argument @var{arg}. If you want to have each match produce several
2043 index entries, separate the different index arguments with @samp{ &&
2044 }@footnote{@samp{&&} with optional spaces, see
2045 @code{reftex-index-phrases-logical-and-regexp}.}. If you want to be
2046 able to choose at each match between several different index arguments,
2047 separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2048 see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an
2052 %--------------------------------------------------------------------
2056 Jupiter Planets!Jupiter
2057 i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2058 i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto
2062 So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2063 @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2064 @samp{Vega} will be indexed as a subitem of @samp{Stars}. The
2065 @samp{Jupiter} line will also use the @samp{i} macro as it was the first
2066 macro definition in the file header (see above example). At each
2067 occurrence of @samp{Mars} you will be able choose between indexing it as
2068 a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2069 Finally, every occurrence of @samp{Pluto} will be indexed as
2070 @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2071 and will therefore create two different index entries.@refill
2073 @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
2074 @subsection Consistency Checks
2075 @cindex Index phrases, consistency checks
2076 @cindex Phrases, consistency checks
2077 @cindex Consistency check for index phrases
2080 Before indexing the phrases in the phrases buffer, they should be
2081 checked carefully for consistency. A first step is to sort the phrases
2082 alphabetically - this is done with the command @kbd{C-c C-s}
2083 (@code{reftex-index-sort-phrases}). It will sort all phrases in the
2084 buffer alphabetically by search phrase. If you want to group certain
2085 phrases and only sort within the groups, insert empty lines between the
2086 groups. Sorting will only change the sequence of phrases within each
2087 group (see the variable @code{reftex-index-phrases-sort-in-blocks}).@refill
2090 A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2091 which lists information about the phrase at point, including an example
2092 of how the index entry will look like and the number of expected matches
2093 in the document.@refill
2096 Another important check is to find out if there are double or
2097 overlapping entries in the buffer. For example if you are first
2098 searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2099 second phrase will not match because of the index macro inserted before
2100 @samp{Mars} earlier. The command @kbd{C-c C-t}
2101 (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2102 the buffer which is either duplicate or a subphrase of another phrase.
2103 In order to check the whole buffer like this, start at the beginning and
2104 execute this command repeatedly.@refill
2106 @node Global Indexing, , Consistency Checks, The Index Phrases File
2107 @subsection Global Indexing
2108 @cindex Global indexing
2109 @cindex Indexing, global
2110 @cindex Indexing, from @file{phrases} buffer
2112 Once the index phrases have been collected and organized, you are set
2113 for global indexing. I recommend to do this only on an otherwise
2114 finished document. Global indexing starts from the phrases buffer.
2115 There are several commands which start indexing: @kbd{C-c C-x} acts on
2116 the current phrase line, @kbd{C-c C-r} on all lines in the current
2117 region and @kbd{C-c C-a} on all phrase lines in the buffer. It is
2118 probably good to do indexing in small chunks since your concentration
2119 may not last long enough to do everything in one go.@refill
2121 @b{Ref@TeX{}} will start at the first phrase line and search the phrase
2122 globally in the whole document. At each match it will stop, compute the
2123 replacement string and offer you the following choices@footnote{Windows
2124 users: Restrict yourself to the described keys during indexing. Pressing
2125 @key{Help} at the indexing prompt can apparently hang Emacs.}:@refill
2129 Replace this match with the proposed string.
2133 Replace this and all further matches in this file.
2135 Skip this match, start with next file.
2137 Skip this match, start with next phrase.
2139 Select a different indexing macro for this match.
2141 Select one of multiple index keys (those separated with @samp{||}).
2143 Edit the replacement text.
2145 Recursive edit. Use @kbd{C-M-c} to return to the indexing process.
2147 Save this buffer and ask again about the current match.
2149 Save all document buffers and ask again about the current match.
2151 Abort the indexing process.
2154 The @samp{Find and Index in Document} menu in the phrases buffer also
2155 lists a few options for the indexing process. The options have
2156 associated customization variables to set the defaults (@pxref{Options
2157 (Index Support)}). Here is a short explanation of what the options do:
2160 @item Match Whole Words
2161 When searching for index phrases, make sure whole words are matched.
2162 This should probably always be on.
2163 @item Case Sensitive Search
2164 Search case sensitively for phrases. I recommend to have this setting
2165 off, in order to match the capitalized words at the beginning of a
2166 sentence, and even typos. You can always say @emph{no} at a match you
2168 @item Wrap Long Lines
2169 Inserting index macros increases the line length. Turn this option on
2170 to allow @b{Ref@TeX{}} to wrap long lines.
2171 @item Skip Indexed Matches
2172 When this is on, @b{Ref@TeX{}} will at each match try to figure out if
2173 this match is already indexed. A match is considered indexed if it is
2174 either the argument of an index macro, or if an index macro is directly
2175 (without whitespace separation) before or after the match. Index macros
2176 are those configured in @code{reftex-index-macros}. Intended for
2177 re-indexing a documents after changes have been made.@refill
2180 Even though indexing should be the last thing you do to a document, you
2181 are bound to make changes afterwards. Indexing then has to be applied
2182 to the changed regions. The command
2183 @code{reftex-index-phrases-apply-to-region} is designed for this
2184 purpose. When called from a LaTeX document with active region, it will
2185 apply @code{reftex-index-all-phrases} to the current region.@refill
2187 @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
2188 @section Displaying and Editing the Index
2189 @cindex Displaying the Index
2190 @cindex Editing the Index
2191 @cindex Index entries, creating
2192 @cindex Index, displaying
2193 @cindex Index, editing
2195 @findex reftex-display-index
2197 In order to compile and display the index, press @kbd{C-c >}. If the
2198 document uses multiple indices, @b{Ref@TeX{}} will ask you to select
2199 one. Then, all index entries will be sorted alphabetically and
2200 displayed in a special buffer, the @file{*Index*} buffer. From that
2201 buffer you can check and edit each entry.@refill
2203 The index can be restricted to the current section or the region. Then
2204 only entries in that part of the document will go into the compiled
2205 index. To restrict to the current section, use a numeric prefix
2206 @samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
2207 region, make the region active and use a numeric prefix @samp{3} (press
2208 @kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
2209 restriction can be moved from one section to the next by pressing the
2210 @kbd{<} and @kbd{>} keys.@refill
2212 One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
2213 by searching near the buffer position where it had found to macro during
2214 scanning. If you have several identical index entries in the same
2215 buffer and significant changes have shifted the entries around, you must
2216 rescan the buffer to ensure the correspondence between the
2217 @file{*Index*} buffer and the definition locations. It is therefore
2218 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2219 frequently while editing the index from the @file{*Index*}
2223 Here is a list of special commands available in the @file{*Index*} buffer. A
2224 summary of this information is always available by pressing
2228 @tablesubheading{General}
2230 Display a summary of commands.
2235 @tablesubheading{Moving around}
2237 Pressing any capital letter will jump to the corresponding section in
2238 the @file{*Index*} buffer. The exclamation mark is special and jumps to
2239 the first entries alphabetically sorted below @samp{A}. These are
2240 usually non-alphanumeric characters.@refill
2242 Go to next entry.@refill
2244 Go to previous entry.@refill
2246 @tablesubheading{Access to document locations}
2248 Show the place in the document where this index entry is defined.@refill
2251 Go to the definition of the current index entry in another
2255 Go to the definition of the current index entry and hide the
2256 @file{*Index*} buffer window.@refill
2259 @vindex reftex-index-follow-mode
2260 @vindex reftex-revisit-to-follow
2261 Toggle follow mode. When follow mode is active, the other window will
2262 always show the location corresponding to the line in the @file{*Index*}
2263 buffer at point. This is similar to pressing @key{SPC} after each
2264 cursor motion. The default for this flag can be set with the variable
2265 @code{reftex-index-follow-mode}. Note that only context in files
2266 already visited is shown. @b{Ref@TeX{}} will not visit a file just for
2267 follow mode. See, however, the variable
2268 @code{reftex-revisit-to-follow}.@refill
2270 @tablesubheading{Entry editing}
2272 Edit the current index entry. In the minibuffer, you can edit the
2273 index macro which defines this entry.@refill
2276 Kill the index entry. Currently not implemented because I don't know
2277 how to implement an @code{undo} function for this.@refill
2280 Edit the @var{key} part of the entry. This is the initial part of the
2281 entry which determines the location of the entry in the index.@refill
2284 Edit the @var{attribute} part of the entry. This is the part after the
2285 vertical bar. With @code{MakeIndex}, this part is an encapsulating
2286 macro. With @code{xindy}, it is called @emph{attribute} and is a
2287 property of the index entry that can lead to special formatting. When
2288 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2292 Edit the @var{visual} part of the entry. This is the part after the
2293 @samp{@@} which is used by @code{MakeIndex} to change the visual
2294 appearance of the entry in the index. When called with @kbd{C-u}
2295 prefix, kill the entire @var{visual} part.@refill
2298 Toggle the beginning of page range property @samp{|(} of the
2302 Toggle the end of page range property @samp{|)} of the entry.@refill
2305 Make the current entry a subentry. This command will prompt for the
2306 superordinate entry and insert it.@refill
2309 Remove the highest superordinate entry. If the current entry is a
2310 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2311 (@samp{bbb!ccc}).@refill
2313 @tablesubheading{Exiting}
2315 Hide the @file{*Index*} buffer.@refill
2318 Kill the @file{*Index*} buffer.@refill
2321 Switch to the Table of Contents buffer of this document.@refill
2323 @tablesubheading{Controlling what gets displayed}
2325 @vindex reftex-index-include-context
2326 Toggle the display of short context in the @file{*Index*} buffer. The
2327 default for this flag can be set with the variable
2328 @code{reftex-index-include-context}.@refill
2331 Restrict the index to a single document section. The corresponding
2332 section number will be displayed in the @code{R<>} indicator in the
2333 mode line and in the header of the @file{*Index*} buffer.@refill
2336 Widen the index to contain all entries of the document.@refill
2339 When the index is currently restricted, move the restriction to the
2340 previous section.@refill
2343 When the index is currently restricted, move the restriction to the
2344 next section.@refill
2346 @tablesubheading{Updating the buffer}
2348 Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
2349 document. However, it sorts the entries again, so that edited entries
2350 will move to the correct position.@refill
2353 @vindex reftex-enable-partial-scans
2354 Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When
2355 @code{reftex-enable-partial-scans} is non-nil, rescan only the file this
2356 location is defined in, not the entire document.@refill
2359 Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
2363 Switch to a different index (for documents with multiple
2368 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2369 @section Builtin Index Macros
2370 @cindex Builtin index macros
2371 @cindex Index macros, builtin
2372 @vindex reftex-index-macros
2373 @cindex @code{multind}, LaTeX package
2374 @cindex @code{index}, LaTeX package
2375 @cindex LaTeX packages, @code{multind}
2376 @cindex LaTeX packages, @code{index}
2378 @b{Ref@TeX{}} by default recognizes the @code{\index} and
2379 @code{\glossary} macros which are defined in the LaTeX core. It has
2380 also builtin support for the re-implementations of @code{\index}
2381 in the @file{multind} and @file{index} packages. However, since
2382 the different definitions of the @code{\index} macro are incompatible,
2383 you will have to explicitly specify the index style used.
2384 @xref{Creating Index Entries}, for information on how to do that.
2386 @node Defining Index Macros, , Builtin Index Macros, Index Support
2387 @section Defining Index Macros
2388 @cindex Defining Index Macros
2389 @cindex Index macros, defining
2390 @vindex reftex-index-macros
2392 When writing a document with an index you will probably define
2393 additional macros which make entries into the index.
2394 Let's look at an example.
2397 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2398 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2399 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2402 The first macro @code{\ix} typesets its argument in the text and places
2403 it into the index. The second macro @code{\nindex} typesets its
2404 argument in the text and places it into a separate index with the tag
2405 @samp{name}@footnote{We are using the syntax of the @file{index} package
2406 here.}. The last macro also places its argument into the index, but as
2407 subitems under the main index entry @samp{Astronomical Objects}. Here
2408 is how to make @b{Ref@TeX{}} recognize and correctly interpret these
2409 macros, first with Emacs Lisp.
2412 (setq reftex-index-macros
2413 '(("\\ix@{*@}" "idx" ?x "" nil nil)
2414 ("\\nindex@{*@}" "name" ?n "" nil nil)
2415 ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2418 Note that the index tag is @samp{idx} for the main index, and
2419 @samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
2420 for the default index and for the glossary.
2422 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2423 quick identification of these macros when @b{Ref@TeX{}} inserts new
2424 index entries with @code{reftex-index}. These codes need to be
2425 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2426 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2429 The following string is empty unless your macro adds a superordinate
2430 entry to the index key - this is the case for the @code{\astobj} macro.
2432 The next entry can be a hook function to exclude certain matches, it
2433 almost always can be @code{nil}.
2435 The final element in the list indicates if the text being indexed needs
2436 to be repeated outside the macro. For the normal index macros, this
2437 should be @code{t}. Only if the macro typesets the entry in the text
2438 (like @code{\ix} and @code{\nindex} in the example do), this should be
2441 To do the same thing with customize, you need to fill in the templates
2447 Macro with args: \ix@{*@}
2448 Index Tag : [Value Menu] String: idx
2451 Exclusion hook : nil
2452 Repeat Outside : [Toggle] off (nil)
2454 Macro with args: \nindex@{*@}
2455 Index Tag : [Value Menu] String: name
2458 Exclusion hook : nil
2459 Repeat Outside : [Toggle] off (nil)
2461 Macro with args: \astobj@{*@}
2462 Index Tag : [Value Menu] String: idx
2464 Key Prefix : Astronomical Objects!
2465 Exclusion hook : nil
2466 Repeat Outside : [Toggle] on (non-nil)
2470 With the macro @code{\ix} defined, you may want to change the default
2471 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2472 This would be done like this
2475 (setq reftex-index-default-macro '(?x "idx"))
2478 which specifies that the macro identified with the character @code{?x} (the
2479 @code{\ix} macro) should be used for indexing phrases and words already
2480 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2481 The index tag is "idx".@refill
2483 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2484 @chapter Viewing Cross--References
2485 @findex reftex-view-crossref
2486 @findex reftex-mouse-view-crossref
2490 @b{Ref@TeX{}} can display cross--referencing information. This means,
2491 if two document locations are linked, @b{Ref@TeX{}} can display the
2492 matching location(s) in another window. The @code{\label} and @code{\ref}
2493 macros are one way of establishing such a link. Also, a @code{\cite}
2494 macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
2495 database entry.@refill
2497 The feature is invoked by pressing @kbd{C-c &}
2498 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2499 of a macro involved in cross--referencing. You can also click with
2500 @kbd{S-mouse-2} on the macro argument. Here is what will happen for
2501 individual classes of macros:@refill
2507 Display the corresponding label definition. All usual
2508 variants@footnote{all macros that start with @samp{ref} or end with
2509 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2510 cross--reference display. This works also for labels defined in an
2511 external document when the current document refers to them through the
2512 @code{xr} interface (@pxref{xr (LaTeX package)}).@refill
2515 @cindex @code{\label}
2516 @vindex reftex-label-alist
2517 Display a document location which references this label. Pressing
2518 @kbd{C-c &} several times moves through the entire document and finds
2519 all locations. Not only the @code{\label} macro but also other macros
2520 with label arguments (as configured with @code{reftex-label-alist}) are
2521 active for cross--reference display.@refill
2524 @cindex @code{\cite}
2525 Display the corresponding BibTeX database entry or @code{\bibitem}.
2526 All usual variants@footnote{all macros that either start or end with
2527 @samp{cite}} of the @code{\cite} macro are active for cross--reference
2530 @item @code{\bibitem}
2531 @cindex @code{\bibitem}
2532 Display a document location which cites this article. Pressing
2533 @kbd{C-c &} several times moves through the entire document and finds
2534 all locations.@refill
2537 @cindex BibTeX buffer, viewing cite locations from
2538 @cindex Viewing cite locations from BibTeX buffer
2539 @kbd{C-c &} is also active in BibTeX buffers. All locations in a
2540 document where the database entry at point is cited will be displayed.
2541 On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
2542 the document you want to search. Subsequent calls will use the same
2543 document, until you break this link with a prefix argument to @kbd{C-c
2547 @cindex @code{\index}
2548 Display other locations in the document which are marked by an index
2549 macro with the same key argument. Along with the standard @code{\index}
2550 and @code{\glossary} macros, all macros configured in
2551 @code{reftex-index-macros} will be recognized.@refill
2554 @vindex reftex-view-crossref-extra
2555 While the display of cross referencing information for the above
2556 mentioned macros is hard--coded, you can configure additional relations
2557 in the variable @code{reftex-view-crossref-extra}.
2560 @chapter All the Rest
2563 @node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
2564 @section @b{Ref@TeX{}}'s Menu
2565 @cindex RefTeXs Menu
2566 @cindex Menu, in the menu bar
2568 @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
2569 which support this. From this menu you can access all of
2570 @b{Ref@TeX{}}'s commands and a few of its options. There is also a
2571 @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
2572 entire set of options.@refill
2574 @node Key Bindings, Faces, RefTeXs Menu, Top
2575 @section Default Key Bindings
2576 @cindex Key Bindings, summary
2578 Here is a summary of the available key bindings.
2592 @kbd{C-c =} @code{reftex-toc}
2593 @kbd{C-c (} @code{reftex-label}
2594 @kbd{C-c )} @code{reftex-reference}
2595 @kbd{C-c [} @code{reftex-citation}
2596 @kbd{C-c &} @code{reftex-view-crossref}
2597 @kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
2598 @kbd{C-c /} @code{reftex-index-selection-or-word}
2599 @kbd{C-c \} @code{reftex-index-phrase-selection-or-word}
2600 @kbd{C-c |} @code{reftex-index-visit-phrases-buffer}
2601 @kbd{C-c <} @code{reftex-index}
2602 @kbd{C-c >} @code{reftex-display-index}
2605 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2606 not already used by some other package. @b{Ref@TeX{}} will not override an
2607 existing binding to @kbd{S-mouse-2}.@refill
2609 Personally, I also bind some functions in the users @kbd{C-c} map for
2610 easier access.@refill
2612 @c FIXME: Do we need bindings for the Index macros here as well?
2613 @c C-c i C-c I or so????
2614 @c How about key bindings for reftex-reset-mode and reftex-parse-document?
2623 @kbd{C-c t} @code{reftex-toc}
2624 @kbd{C-c l} @code{reftex-label}
2625 @kbd{C-c r} @code{reftex-reference}
2626 @kbd{C-c c} @code{reftex-citation}
2627 @kbd{C-c v} @code{reftex-view-crossref}
2628 @kbd{C-c s} @code{reftex-search-document}
2629 @kbd{C-c g} @code{reftex-grep-document}
2632 @noindent These keys are reserved for the user, so I cannot bind them by
2633 default. If you want to have these key bindings available, set in your
2636 @vindex reftex-extra-bindings
2638 (setq reftex-extra-bindings t)
2641 @vindex reftex-load-hook
2642 Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook
2643 @code{reftex-load-hook}. For information on the keymaps
2644 which should be used to add keys, see @ref{Keymaps and Hooks}.
2646 @node Faces, AUCTeX, Key Bindings, Top
2650 @b{Ref@TeX{}} uses faces when available to structure the selection and
2651 table of contents buffers. It does not create its own faces, but uses
2652 the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will
2653 use faces only when @code{font-lock} is loaded. This seems to be
2654 reasonable because people who like faces will very likely have it
2655 loaded. If you wish to turn off fontification or change the involved
2656 faces, see @ref{Options (Fontification)}.@refill
2658 @node Multifile Documents, Language Support, AUCTeX, Top
2659 @section Multifile Documents
2660 @cindex Multifile documents
2661 @cindex Documents, spread over files
2663 The following is relevant when working with documents spread over many
2668 @b{Ref@TeX{}} has full support for multifile documents. You can edit parts of
2669 several (multifile) documents at the same time without conflicts.
2670 @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
2671 @code{query-replace} on all files which are part of a multifile
2675 @vindex tex-main-file
2677 All files belonging to a multifile document should define a File
2678 Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
2679 standard Emacs LaTeX mode) containing the name of the master file. For
2680 example, to set the file variable @code{TeX-master}, include something
2681 like the following at the end of each TeX file:@refill
2684 %%% Local Variables: ***
2686 %%% TeX-master: "thesis.tex" ***
2690 AUCTeX with the setting
2693 (setq-default TeX-master nil)
2696 will actually ask you for each new file about the master file and insert
2697 this comment automatically. For more details see the documentation of
2698 the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
2699 documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2700 The GNU Emacs Manual}) and the Emacs documentation on File Variables
2701 (@pxref{File Variables,,,emacs, The GNU Emacs Manual}).@refill
2704 The context of a label definition must be found in the same file as the
2705 label itself in order to be processed correctly by @b{Ref@TeX{}}. The only
2706 exception is that section labels referring to a section statement
2707 outside the current file can still use that section title as
2711 @node Language Support, Finding Files, Multifile Documents, Top
2712 @section Language Support
2713 @cindex Language support
2715 Some parts of @b{Ref@TeX{}} are language dependent. The default
2716 settings work well for English. If you are writing in a different
2717 language, the following hints may be useful:
2721 @vindex reftex-derive-label-parameters
2722 @vindex reftex-abbrev-parameters
2723 The mechanism to derive a label from context includes the abbreviation
2724 of words and omission of unimportant words. These mechanisms may have
2725 to be changed for other languages. See the variables
2726 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2729 @vindex reftex-translate-to-ascii-function
2730 @vindex reftex-label-illegal-re
2731 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
2732 context string from non-ASCII characters in order to make a legal label.
2733 If there should ever be a version of @TeX{} which allows extended
2734 characters @emph{in labels}, then we will have to look at the
2735 variables @code{reftex-translate-to-ascii-function} and
2736 @code{reftex-label-illegal-re}.
2739 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
2740 to guess which label type is required. These @emph{magic words} are
2741 different in every language. For an example of how to add magic words,
2742 see @ref{Adding Magic Words}.
2744 @vindex reftex-multiref-punctuation
2745 @vindex reftex-cite-punctuation
2747 @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
2748 for the author list in citations. Some of this may be language
2749 dependent. See the variables @code{reftex-multiref-punctuation} and
2750 @code{reftex-cite-punctuation}.
2753 @node Finding Files, Optimizations, Language Support, Top
2754 @section Finding Files
2755 @cindex Finding files
2757 In order to find files included in a document via @code{\input} or
2758 @code{\include}, @b{Ref@TeX{}} searches all directories specified in the
2759 environment variable @code{TEXINPUTS}. Similarly, it will search the
2760 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
2761 BibTeX database files.
2763 When searching, @b{Ref@TeX{}} will also expand recursive path
2764 definitions (directories ending in @samp{//} or @samp{!!}). But it will
2765 only search and expand directories @emph{explicitly} given in these
2766 variables. This may cause problems under the following circumstances:
2770 Most TeX system have a default search path for both TeX files and BibTeX
2771 files which is defined in some setup file. Usually this default path is
2772 for system files which @b{Ref@TeX{}} does not need to see. But if your
2773 document needs TeX files or BibTeX database files in a directory only
2774 given in the default search path, @b{Ref@TeX{}} will fail to find them.
2776 Some TeX systems do not use environment variables at all in order to
2777 specify the search path. Both default and user search path are then
2778 defined in setup files.
2782 There are three ways to solve this problem:
2786 Specify all relevant directories explicitly in the environment
2787 variables. If for some reason you don't want to mess with the default
2788 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
2789 variables and configure @b{Ref@TeX{}} to use them instead:
2792 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
2793 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
2797 Specify the full search path directly in @b{Ref@TeX{}}'s variables.
2800 (setq reftex-texpath-environment-variables
2801 '("./inp:/home/cd/tex//:/usr/local/tex//"))
2802 (setq reftex-bibpath-environment-variables
2803 '("/home/cd/tex/lit/"))
2807 Some TeX systems provide stand--alone programs to do the file search just
2808 like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the
2809 @code{kpathsearch} library which provides the command @code{kpsewhich}
2810 to search for files. @b{Ref@TeX{}} can be configured to use this
2811 program. Note that the exact syntax of the @code{kpsewhich}
2812 command depends upon the version of that program.
2815 (setq reftex-use-external-file-finders t)
2816 (setq reftex-external-file-finders
2817 '(("tex" . "kpsewhich -format=.tex %f")
2818 ("bib" . "kpsewhich -format=.bib %f")))
2823 @vindex reftex-file-extensions
2824 @vindex TeX-file-extensions
2825 Some people like to use RefTeX with noweb files, which usually have the
2826 extension @file{.nw}. In order to deal with such files, the new
2827 extension must be added to the list of valid extensions in the variable
2828 @code{reftex-file-extensions}. When working with AUCTeX as major mode,
2829 the new extension must also be known to AUCTeX via the variable
2830 @code{TeX-file-extension}. For example:
2833 (setq reftex-file-extensions
2834 '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
2835 (setq TeX-file-extensions
2836 '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
2839 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
2840 @section Optimizations
2841 @cindex Optimizations
2843 Implementing the principle of least surprises, the default settings of
2844 @b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
2845 when using @b{Ref@TeX{}} for a large project and/or on a small computer,
2846 there are ways to improve speed or memory usage.@refill
2850 @b{Removing Lookup Buffers}@*
2851 @cindex Removing lookup buffers
2852 @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
2853 database files for lookup purposes. These buffers are kept, so that
2854 subsequent use of the same files is fast. If you can't afford keeping
2855 these buffers around, and if you can live with a speed penalty, try
2857 @vindex reftex-keep-temporary-buffers
2859 (setq reftex-keep-temporary-buffers nil)
2863 @b{Partial Document Scans}@*
2864 @cindex Partial documents scans
2865 @cindex Document scanning, partial
2866 A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
2867 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
2868 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
2869 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
2870 re-parsing of the entire document in order to update the parsing
2871 information. For a large document this can be unnecessary, in
2872 particular if only one file has changed. @b{Ref@TeX{}} can be configured
2873 to do partial scans instead of full ones. @kbd{C-u} re-parsing then
2874 does apply only to the current buffer and files included from it.
2875 Likewise, the @kbd{r} key in both the label selection buffer and the
2876 table-of-contents buffer will only prompt scanning of the file in which
2877 the label or section macro near the cursor was defined. Re-parsing of
2878 the entire document is still available by using @kbd{C-u C-u} as a
2879 prefix, or the capital @kbd{R} key in the menus. To use this feature,
2882 @vindex reftex-enable-partial-scans
2884 (setq reftex-enable-partial-scans t)
2888 @b{Saving Parser Information}@*
2889 @cindex Saving parser information
2890 @cindex Parse information, saving to a file
2891 @vindex reftex-parse-file-extension
2892 Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
2893 scan, when you start working with a document. To avoid this, parsing
2894 information can be stored in a file. The file @file{MASTER.rel} is used
2895 for storing information about a document with master file
2896 @file{MASTER.tex}. It is written automatically when you kill a buffer
2897 in @code{reftex-mode} or when you exit Emacs. The information is
2898 restored when you begin working with a document in a new editing
2899 session. To use this feature, put into @file{.emacs}:@refill
2901 @vindex reftex-save-parse-info
2903 (setq reftex-save-parse-info t)
2907 @b{Automatic Document Scans}@*
2908 @cindex Automatic document scans
2909 @cindex Document scanning, automatic
2910 At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
2911 document. If this gets into your way, it can be turned off with
2913 @vindex reftex-allow-automatic-rescan
2915 (setq reftex-allow-automatic-rescan nil)
2918 @b{Ref@TeX{}} will then occasionally annotate new labels in the selection
2919 buffer, saying that their position in the label list in uncertain. A
2920 manual document scan will fix this.@refill
2923 @b{Multiple Selection Buffers}@*
2924 @cindex Multiple selection buffers
2925 @cindex Selection buffers, multiple
2926 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
2927 every selection process. In documents with very many labels this can
2928 take several seconds. @b{Ref@TeX{}} provides an option to create a
2929 separate selection buffer for each label type and to keep this buffer
2930 from one selection to the next. These buffers are updated automatically
2931 only when a new label has been added in the buffers category with
2932 @code{reftex-label}. Updating the buffer takes as long as recreating it
2933 - so the time saving is limited to cases where no new labels of that
2934 category have been added. To turn on this feature, use@refill
2936 @vindex reftex-use-multiple-selection-buffers
2938 (setq reftex-use-multiple-selection-buffers t)
2942 @cindex Selection buffers, updating
2943 You can also inhibit the automatic updating entirely. Then the
2944 selection buffer will always pop up very fast, but may not contain the
2945 most recently defined labels. You can always update the buffer by hand,
2946 with the @kbd{g} key. To get this behavior, use instead@refill
2948 @vindex reftex-auto-update-selection-buffers
2950 (setq reftex-use-multiple-selection-buffers t
2951 reftex-auto-update-selection-buffers nil)
2957 @b{As a summary}, here are the settings I recommend for heavy use of
2958 @b{Ref@TeX{}} with large documents:
2962 (setq reftex-enable-partial-scans t
2963 reftex-save-parse-info t
2964 reftex-use-multiple-selection-buffers t)
2968 @node AUCTeX, Multifile Documents, Faces, Top
2969 @section @w{AUC @TeX{}}
2970 @cindex @code{AUCTeX}, Emacs package
2971 @cindex Emacs packages, @code{AUCTeX}
2973 AUCTeX is without doubt the best major mode for editing TeX and LaTeX
2974 files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
2975 If AUCTeX is not part of your Emacs distribution, you can get
2976 it@footnote{XEmacs 21.x users may want to install the corresponding
2977 XEmacs package.} by ftp from the
2978 @uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.
2981 * AUCTeX-RefTeX Interface:: How both packages work together
2982 * Style Files:: AUCTeX's style files can support RefTeX
2983 * Bib-Cite:: Hypertext reading of a document
2986 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
2987 @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
2989 @b{Ref@TeX{}} contains code to interface with AUCTeX. When this
2990 interface is turned on, both packages will interact closely. Instead of
2991 using @b{Ref@TeX{}}'s commands directly, you can then also use them
2992 indirectly as part of the AUCTeX
2993 environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
2994 needed for all of this to work. Parts of it work also with earlier
2995 versions.}. The interface is turned on with@refill
2998 (setq reftex-plug-into-AUCTeX t)
3001 If you need finer control about which parts of the interface are used
3002 and which not, read the docstring of the variable
3003 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
3004 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
3006 The following list describes the individual parts of the interface.
3010 @findex reftex-label
3011 @vindex LaTeX-label-function, @r{AUCTeX}
3014 @findex LaTeX-section, @r{AUCTeX}
3015 @findex TeX-insert-macro, @r{AUCTeX}
3016 @b{AUCTeX calls @code{reftex-label} to insert labels}@*
3017 When a new section is created with @kbd{C-c C-s}, or a new environment
3018 is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
3019 go with it. With the interface, @code{reftex-label} is called instead.
3020 For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
3021 @b{Ref@TeX{}} will insert
3031 without further prompts.
3033 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
3034 will offer its default label which is derived from the section title.
3037 @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
3038 When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
3039 have to rescan the buffer in order to see it.@refill
3042 @findex reftex-arg-label
3043 @findex TeX-arg-label, @r{AUCTeX function}
3044 @findex reftex-arg-ref
3045 @findex TeX-arg-ref, @r{AUCTeX function}
3046 @findex reftex-arg-cite
3047 @findex TeX-arg-cite, @r{AUCTeX function}
3048 @findex reftex-arg-index
3049 @findex TeX-arg-index, @r{AUCTeX function}
3050 @findex TeX-insert-macro, @r{AUCTeX function}
3051 @kindex C-c @key{RET}
3052 @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
3053 interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
3054 macro arguments. Internally, it uses the functions
3055 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3056 prompt for arguments which are labels, citation keys and index entries.
3057 The interface takes over these functions@footnote{@code{fset} is used to
3058 do this, which is not reversible. However, @b{Ref@TeX{}} implements the
3059 old functionality when you later decide to turn off the interface.} and
3060 supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For
3061 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
3062 will supply its label selection process (@pxref{Referencing
3066 @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
3067 @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
3070 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
3071 @subsection Style Files
3072 @cindex Style files, AUCTeX
3073 @findex TeX-add-style-hook, @r{AUCTeX}
3074 Style files are Emacs Lisp files which are evaluated by AUCTeX in
3075 association with the @code{\documentclass} and @code{\usepackage}
3076 commands of a document (@pxref{Style Files,,,auctex}). Support for
3077 @b{Ref@TeX{}} in such a style file is useful when the LaTeX style
3078 defines macros or environments connected with labels, citations, or the
3079 index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el})
3080 distributed with AUCTeX already support @b{Ref@TeX{}} in this
3083 Before calling a @b{Ref@TeX{}} function, the style hook should always
3084 test for the availability of the function, so that the style file will
3085 also work for people who do not use @b{Ref@TeX{}}. @refill
3087 Additions made with style files in the way described below remain local
3088 to the current document. For example, if one package uses AMSTeX, the
3089 style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
3090 this will not affect other documents.@refill
3092 @findex reftex-add-label-environments
3093 @findex reftex-add-to-label-alist
3094 A style hook may contain calls to
3095 @code{reftex-add-label-environments}@footnote{This used to be the
3096 function @code{reftex-add-to-label-alist} which is still available as an
3097 alias for compatibility.} which defines additions to
3098 @code{reftex-label-alist}. The argument taken by this function must have
3099 the same format as @code{reftex-label-alist}. The @file{amsmath.el}
3100 style file of AUCTeX for example contains the following:@refill
3104 (TeX-add-style-hook "amsmath"
3106 (if (fboundp 'reftex-add-label-environments)
3107 (reftex-add-label-environments '(AMSTeX)))))
3112 @findex LaTeX-add-environments, @r{AUCTeX}
3113 while a package @code{myprop} defining a @code{proposition} environment
3114 with @code{\newtheorem} might use@refill
3118 (TeX-add-style-hook "myprop"
3120 (LaTeX-add-environments '("proposition" LaTeX-env-label))
3121 (if (fboundp 'reftex-add-label-environments)
3122 (reftex-add-label-environments
3123 '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3124 ("Proposition" "Prop.") -3))))))
3128 @findex reftex-set-cite-format
3129 Similarly, a style hook may contain a call to
3130 @code{reftex-set-cite-format} to set the citation format. The style
3131 file @file{natbib.el} for the Natbib citation style does switch
3132 @b{Ref@TeX{}}'s citation format like this:@refill
3135 (TeX-add-style-hook "natbib"
3137 (if (fboundp 'reftex-set-cite-format)
3138 (reftex-set-cite-format 'natbib))))
3141 @findex reftex-add-index-macros
3142 The hook may contain a call to @code{reftex-add-index-macros} to
3143 define additional @code{\index}-like macros. The argument must have
3144 the same format as @code{reftex-index-macros}. It may be a symbol, to
3145 trigger support for one of the builtin index packages. For example,
3146 the style @file{multind.el} contains
3149 (TeX-add-style-hook "multind"
3151 (and (fboundp 'reftex-add-index-macros)
3152 (reftex-add-index-macros '(multind)))))
3155 If you have your own package @file{myindex} which defines the
3156 following macros to be used with the LaTeX @file{index.sty} file
3158 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3159 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3162 you could write this in the style file @file{myindex.el}:
3165 (TeX-add-style-hook "myindex"
3168 '("molec" TeX-arg-index)
3169 '("aindex" TeX-arg-index))
3170 (if (fboundp 'reftex-add-index-macros)
3171 (reftex-add-index-macros
3172 '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3173 ("aindex@{*@}" "author" ?a "" nil nil))))))
3176 @findex reftex-add-section-levels
3177 Finally the hook may contain a call to @code{reftex-add-section-levels}
3178 to define additional section statements. For example, the FoilTeX class
3179 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
3180 is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
3183 (TeX-add-style-hook "foils"
3185 (if (fboundp 'reftex-add-section-levels)
3186 (reftex-add-section-levels '(("foilhead" . 3)
3187 ("rotatefoilhead" . 3))))))
3190 @node Bib-Cite, , Style Files, AUCTeX
3191 @subsection Bib-Cite
3192 @cindex @code{bib-cite}, Emacs package
3193 @cindex Emacs packages, @code{bib-cite}
3195 Once you have written a document with labels, references and citations,
3196 it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has
3197 support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3198 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3199 @code{reftex-search-document}. A somewhat fancier interface with mouse
3200 highlighting is provided (among other things) by Peter S. Galbraith's
3201 @file{bib-cite.el}. There is some overlap in the functionalities of
3202 Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with
3205 Bib-cite version 3.06 and later can be configured so that bib-cite's
3206 mouse functions use @b{Ref@TeX{}} for displaying references and citations.
3207 This can be useful in particular when working with the LaTeX @code{xr}
3208 package or with an explicit @code{thebibliography} environment (rather
3209 than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To
3210 make use of this feature, try@refill
3212 @vindex bib-cite-use-reftex-view-crossref
3214 (setq bib-cite-use-reftex-view-crossref t)
3218 @node Problems and Work-Arounds, Imprint, Optimizations, Top
3219 @section Problems and Work-arounds
3220 @cindex Problems and work-arounds
3224 @b{LaTeX commands}@*
3225 @cindex LaTeX commands, not found
3226 @code{\input}, @code{\include}, and @code{\section} (etc.) statements
3227 have to be first on a line (except for white space).@refill
3230 @b{Commented regions}@*
3231 @cindex Labels, commented out
3232 @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
3233 make duplicates of such labels. This is considered to be a feature.@refill
3236 @b{Wrong section numbers}@*
3237 @cindex Section numbers, wrong
3238 @vindex reftex-enable-partial-scans
3239 When using partial scans (@code{reftex-enable-partial-scans}), the section
3240 numbers in the table of contents may eventually become wrong. A full
3241 scan will fix this.@refill
3244 @b{Local settings}@*
3245 @cindex Settings, local
3246 @findex reftex-add-label-environments
3247 @findex reftex-set-cite-format
3248 @findex reftex-add-section-levels
3249 The label environment definitions in @code{reftex-label-alist} are
3250 global and apply to all documents. If you need to make definitions
3251 local to a document, because they would interfere with settings in other
3252 documents, you should use AUCTeX and set up style files with calls to
3253 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3254 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3255 Settings made with these functions remain local to the current
3256 document. @xref{AUCTeX}.@refill
3259 @b{Funny display in selection buffer}@*
3260 @cindex @code{x-symbol}, Emacs package
3261 @cindex Emacs packages, @code{x-symbol}
3262 @cindex @code{isotex}, Emacs package
3263 @cindex Emacs packages, @code{isotex}
3264 @cindex @code{iso-cvt}, Emacs package
3265 @cindex Emacs packages, @code{iso-cvt}
3266 When using packages which make the buffer representation of a file
3267 different from its disk representation (e.g. x-symbol, isotex,
3268 iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
3269 reflects the disk state of a file. This happens only in @emph{unvisited}
3270 parts of a multifile document, because @b{Ref@TeX{}} visits these files
3271 literally for speed reasons. Then both short context and section
3272 headings may look different from what you usually see on your screen.
3273 In rare cases @code{reftex-toc} may have problems to jump to an affected
3274 section heading. There are three possible ways to deal with
3278 @vindex reftex-keep-temporary-buffers
3279 @code{(setq reftex-keep-temporary-buffers t)}@*
3280 This implies that @b{Ref@TeX{}} will load all parts of a multifile
3281 document into Emacs (i.e. there won't be any temporary buffers).@refill
3283 @vindex reftex-initialize-temporary-buffers
3284 @code{(setq reftex-initialize-temporary-buffers t)}@*
3285 This means full initialization of temporary buffers. It involves
3286 a penalty when the same unvisited file is used for lookup often.@refill
3288 Set @code{reftex-initialize-temporary-buffers} to a list of hook
3289 functions doing a minimal initialization.@refill
3291 @vindex reftex-refontify-context
3292 See also the variable @code{reftex-refontify-context}.
3295 @b{Labels as arguments to \begin}@*
3296 @cindex @code{pf}, LaTeX package
3297 @cindex LaTeX packages, @code{pf}
3298 Some packages use an additional argument to a @code{\begin} macro
3299 to specify a label. E.g. Lamport's @file{pf.sty} uses both
3301 \step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
3307 We need to trick @b{Ref@TeX{}} into swallowing this:
3311 ;; Configuration for Lamport's pf.sty
3312 (setq reftex-label-alist
3313 '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3314 ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3319 The first line is just a normal configuration for a macro. For the
3320 @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
3321 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3322 argument (which really is a second argument to the macro @code{\begin})
3323 as a label of type @code{?p}. Argument count for this macro starts only
3324 after the @samp{@{step+@}}, also when specifying how to get
3328 @b{Idle timers in XEmacs}@*
3329 @cindex Idle timer restart
3330 @vindex reftex-use-itimer-in-xemacs
3331 In XEmacs, idle timer restart does not work reliably after fast
3332 keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command
3333 hook to start the timer used for automatic crossref information. When
3334 this bug gets fixed, a real idle timer can be requested with
3336 (setq reftex-use-itimer-in-xemacs t)
3342 @cindex Key bindings, problems with Viper mode
3343 @findex viper-harness-minor-mode
3344 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3345 @b{Ref@TeX{}}'s keymaps with@refill
3348 (viper-harness-minor-mode "reftex")
3354 @node Imprint, Commands, Problems and Work-Arounds, Top
3358 @cindex Acknowledgments
3361 @cindex @code{http}, @b{Ref@TeX{}} home page
3362 @cindex @code{ftp}, @b{Ref@TeX{}} site
3364 @b{Ref@TeX{}} was written by @i{@value{Carsten Dominik}}
3365 @email{dominik@@science.uva.nl}, with contributions by @i{Stephen
3366 Eglen}. @b{Ref@TeX{}} is currently maintained by @refill
3369 @value{Carsten Dominik} @email{dominik@@science.uva.nl}
3371 If you have questions about @b{Ref@TeX{}}, there are several Usenet
3372 groups which have competent readers: @code{comp.emacs},
3373 @code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}.
3374 You can also write directly to the maintainer.
3376 If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
3377 to contribute code or ideas, please
3378 @uref{mailto:dominik@@science.uva.nl,contact the maintainer}. Remember
3379 to provide all necessary information such as version numbers of Emacs
3380 and @b{Ref@TeX{}}, and the relevant part of your configuration in
3381 @file{.emacs}. When reporting a bug which throws an exception, please
3382 include a backtrace if you know how to produce one.
3384 @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
3385 It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
3386 21.x users want to install the corresponding plugin package which is
3387 available from the XEmacs @code{ftp} site. See the XEmacs 21.x
3388 documentation on package installation for details.@refill
3390 Users of earlier Emacs distributions (including Emacs 19) can get a
3391 @b{Ref@TeX{}} distribution from the
3392 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainers
3393 webpage}. Note that the Emacs 19 version supports many but not all
3394 features described in this manual.@refill
3396 Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
3397 developing it with their reports. In particular thanks to @i{Fran
3398 Burstall, Alastair Burt, Lars Clausen, Soren Dayton, Stephen Eglen, Karl
3399 Eichwalder, Erik Frik, Erik Frisk, Peter Galbraith, Kai Grossjohann,
3400 Frank Harrell, Stephan Heuel, Alan Ho, Dieter Kraft, Adrian Lanz, Rory
3401 Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat, Daniel
3402 Polani, Alan Shutko, Robin Socha, Richard Stanton, Allan Strand, Jan
3403 Vroonhof, Christoph Wedler, Alan Williams, Roland Winkler, Eli
3406 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3407 @file{bib-cite.el}.@refill
3409 Finally thanks to @i{Uwe Bolick} who first got me (some years ago) into
3410 supporting LaTeX labels and references with an editor (which was
3411 MicroEmacs at the time).@refill
3413 @node Commands, Options, Imprint, Top
3415 @cindex Commands, list of
3417 Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
3418 LaTeX files. Command which are executed from the special buffers are
3419 not described here. All commands are available from the @code{Ref}
3420 menu. See @xref{Key Bindings}.
3422 @deffn Command reftex-toc
3423 Show the table of contents for the current document. When called with
3424 one ore two @kbd{C-u} prefixes, rescan the document first.@refill
3427 @deffn Command reftex-label
3428 Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
3429 document rescan first.
3432 @deffn Command reftex-reference
3433 Start a selection process to select a label, and insert a reference to
3434 it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
3437 @deffn Command reftex-citation
3438 Make a citation using BibTeX database files. After prompting for a regular
3439 expression, scans the buffers with BibTeX entries (taken from the
3440 @code{\bibliography} command or a @code{thebibliography} environment)
3441 and offers the matching entries for selection. The selected entry is
3442 formatted according to @code{reftex-cite-format} and inserted into the
3444 When called with one or two @kbd{C-u} prefixes, first rescans the
3445 document. When called with a numeric prefix, make that many citations.
3446 When called with point inside the braces of a @code{\cite} command, it
3447 will add another key, ignoring the value of
3448 @code{reftex-cite-format}.@refill @*
3449 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3450 as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
3451 both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
3452 on knows citation keys is possible. @samp{=} is a good regular
3453 expression to match all entries in all files.@refill
3456 @deffn Command reftex-index
3457 Query for an index macro and insert it along with its arguments. The
3458 index macros available are those defined in @code{reftex-index-macro} or
3459 by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
3460 style file. @b{Ref@TeX{}} provides completion for the index tag and the
3461 index key, and will prompt for other arguments.@refill
3464 @deffn Command reftex-index-selection-or-word
3465 Put current selection or the word near point into the default index
3466 macro. This uses the information in @code{reftex-index-default-macro}
3467 to make an index entry. The phrase indexed is the current selection or
3468 the word near point. When called with one @kbd{C-u} prefix, let the
3469 user have a chance to edit the index entry. When called with 2
3470 @kbd{C-u} as prefix, also ask for the index macro and other stuff. When
3471 called inside TeX math mode as determined by the @file{texmathp.el}
3472 library which is part of AUCTeX, the string is first processed with the
3473 @code{reftex-index-math-format}, which see.@refill
3476 @deffn Command reftex-index-phrase-selection-or-word
3477 Add current selection or the word at point to the phrases buffer.
3478 When you are in transient-mark-mode and the region is active, the
3479 selection will be used - otherwise the word at point.
3480 You get a chance to edit the entry in the phrases buffer - to save the
3481 buffer and return to the LaTeX document, finish with @kbd{C-c C-c}.
3484 @deffn Command reftex-index-visit-phrases-buffer
3485 Switch to the phrases buffer, initialize if empty.
3488 @deffn Command reftex-index-phrases-apply-to-region
3489 Index all index phrases in the current region.
3490 This works exactly like global indexing from the index phrases buffer,
3491 but operation is restricted to the current region.
3494 @deffn Command reftex-display-index
3495 Display a buffer with an index compiled from the current document.
3496 When the document has multiple indices, first prompts for the correct one.
3497 When index support is turned off, offer to turn it on.
3498 With one or two @kbd{C-u} prefixes, rescan document first.
3499 With prefix 2, restrict index to current document section.
3500 With prefix 3, restrict index to active region.@refill
3503 @deffn Command reftex-view-crossref
3504 View cross reference of macro at point. Point must be on the @var{key}
3505 argument. Works with the macros @code{\label}, @code{\ref},
3506 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3507 these. Where it makes sense, subsequent calls show additional
3508 locations. See also the variable @code{reftex-view-crossref-extra} and
3509 the command @code{reftex-view-crossref-from-bibtex}. With one or two
3510 @kbd{C-u} prefixes, enforce rescanning of the document. With argument
3511 2, select the window showing the cross reference.
3514 @deffn Command reftex-view-crossref-from-bibtex
3515 View location in a LaTeX document which cites the BibTeX entry at point.
3516 Since BibTeX files can be used by many LaTeX documents, this function
3517 prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
3518 link to a document, call the function with a prefix arg. Calling
3519 this function several times find successive citation locations.
3522 @deffn Command reftex-create-tags-file
3523 Create TAGS file by running @code{etags} on the current document. The
3524 TAGS file is also immediately visited with
3525 @code{visit-tags-table}.@refill
3528 @deffn Command reftex-grep-document
3529 Run grep query through all files related to this document.
3530 With prefix arg, force to rescan document.
3531 No active TAGS table is required.@refill
3534 @deffn Command reftex-search-document
3535 Regexp search through all files of the current document.
3536 Starts always in the master file. Stops when a match is found.
3537 No active TAGS table is required.@refill
3540 @deffn Command reftex-query-replace-document
3541 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3542 document. With prefix arg, replace only word-delimited matches. No
3543 active TAGS table is required.@refill
3546 @deffn Command reftex-change-label
3547 Query replace @var{from} with @var{to} in all @code{\label} and
3548 @code{\ref} commands. Works on the entire multifile document. No
3549 active TAGS table is required.@refill
3552 @deffn Command reftex-renumber-simple-labels
3553 Renumber all simple labels in the document to make them sequentially.
3554 Simple labels are the ones created by RefTeX, consisting only of the
3555 prefix and a number. After the command completes, all these labels will
3556 have sequential numbers throughout the document. Any references to the
3557 labels will be changed as well. For this, @b{Ref@TeX{}} looks at the
3558 arguments of any macros which either start or end with the string
3559 @samp{ref}. This command should be used with care, in particular in
3560 multifile documents. You should not use it if another document refers
3561 to this one with the @code{xr} package.@refill
3564 @deffn Command reftex-find-duplicate-labels
3565 Produce a list of all duplicate labels in the document.@refill
3568 @deffn Command reftex-customize
3569 Run the customize browser on the @b{Ref@TeX{}} group.
3571 @deffn Command reftex-show-commentary
3572 Show the commentary section from @file{reftex.el}.
3574 @deffn Command reftex-info
3575 Run info on the top @b{Ref@TeX{}} node.
3577 @deffn Command reftex-parse-document
3578 Parse the entire document in order to update the parsing information.
3580 @deffn Command reftex-reset-mode
3581 Enforce rebuilding of several internal lists and variables. Also
3582 removes the parse file associated with the current document.
3585 @node Options, Keymaps and Hooks, Commands, Top
3586 @chapter Options, Keymaps, Hooks
3587 @cindex Options, list of
3589 Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All
3590 variables have customize support - so if you are not familiar with Emacs
3591 Lisp (and even if you are) you might find it more comfortable to use
3592 @code{customize} to look at and change these variables. @kbd{M-x
3593 reftex-customize} will get you there.@refill
3596 * Options (Table of Contents)::
3597 * Options (Defining Label Environments)::
3598 * Options (Creating Labels)::
3599 * Options (Referencing Labels)::
3600 * Options (Creating Citations)::
3601 * Options (Index Support)::
3602 * Options (Viewing Cross-References)::
3603 * Options (Finding Files)::
3604 * Options (Optimizations)::
3605 * Options (Fontification)::
3609 @node Options (Table of Contents), Options (Defining Label Environments), , Options
3610 @section Table of Contents
3611 @cindex Options, table of contents
3612 @cindex Table of contents, options
3614 @defopt reftex-include-file-commands
3615 List of LaTeX commands which input another file.
3616 The file name is expected after the command, either in braces or separated
3620 @defopt reftex-max-section-depth
3621 Maximum depth of section levels in document structure.
3622 Standard LaTeX needs 7, default is 12.
3625 @defopt reftex-section-levels
3626 Commands and levels used for defining sections in the document. The
3627 @code{car} of each cons cell is the name of the section macro. The
3628 @code{cdr} is a number indicating its level. A negative level means the
3629 same as the positive value, but the section will never get a
3630 number. The @code{cdr} may also be a function which then has to return
3634 @defopt reftex-toc-max-level
3635 The maximum level of toc entries which will be included in the TOC.
3636 Section headings with a bigger level will be ignored. In RefTeX,
3637 chapters are level 1, sections level 2 etc. This variable can be
3638 changed from within the @file{*toc*} buffer with the @kbd{t} key.@refill
3641 @defopt reftex-toc-split-windows-horizontally
3642 Non-@code{nil} means, create TOC window by splitting window
3643 horizontally. The default is to split vertically.
3646 @defopt reftex-toc-split-windows-horizontally-fraction
3647 Fraction of the horizontal width of the frame to be used for TOC window.
3648 Only relevant when @code{reftex-toc-split-windows-horizontally} is
3652 @defopt reftex-toc-keep-other-windows
3653 Non-@code{nil} means, split the selected window to display the
3654 @file{*toc*} buffer. This helps to keep the window configuration, but
3655 makes the @file{*toc*} small. When @code{nil}, all other windows except
3656 the selected one will be deleted, so that the @file{*toc*} window fills
3657 half the frame.@refill
3660 @defopt reftex-toc-include-file-boundaries
3661 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3662 This flag can be toggled from within the @file{*toc*} buffer with the
3666 @defopt reftex-toc-include-labels
3667 Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
3668 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3672 @defopt reftex-toc-include-index-entries
3673 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3674 This flag can be toggled from within the @file{*toc*} buffer with the
3678 @defopt reftex-toc-include-context
3679 Non-@code{nil} means, include context with labels in the @file{*toc*}
3680 buffer. Context will only be shown if the labels are visible as well.
3681 This flag can be toggled from within the @file{*toc*} buffer with the
3685 @defopt reftex-toc-follow-mode
3686 Non-@code{nil} means, point in @file{*toc*} buffer (the
3687 table-of-contents buffer) will cause other window to follow. The other
3688 window will show the corresponding part of the document. This flag can
3689 be toggled from within the @file{*toc*} buffer with the @kbd{f}
3693 @deffn {Normal Hook} reftex-toc-mode-hook
3694 Normal hook which is run when a @file{*toc*} buffer is
3698 @deffn Keymap reftex-toc-map
3699 The keymap which is active in the @file{*toc*} buffer.
3700 (@pxref{Table of Contents}).@refill
3703 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
3704 @section Defining Label Environments
3705 @cindex Options, defining label environments
3706 @cindex Defining label environments, options
3708 @defopt reftex-default-label-alist-entries
3709 Default label alist specifications. It is a list of symbols with
3710 associations in the constant @code{reftex-label-alist-builtin}.
3711 @code{LaTeX} should always be the last entry.@refill
3714 @defopt reftex-label-alist
3715 Set this variable to define additions and changes to the defaults in
3716 @code{reftex-default-label-alist-entries}. The only things you
3717 @emph{must not} change is that @code{?s} is the type indicator for
3718 section labels, and @key{SPC} for the @code{any} label type. These are
3719 hard-coded at other places in the code.@refill
3721 The value of the variable must be a list of items. Each item is a list
3722 itself and has the following structure:
3725 (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
3726 @var{context-method} (@var{magic-word} ... ) @var{toc-level})
3729 Each list entry describes either an environment carrying a counter for
3730 use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
3731 label as (or inside) one of its arguments. The elements of each list
3735 @item @var{env-or-macro}
3736 Name of the environment (like @samp{table}) or macro (like
3737 @samp{\myfig}). For macros, indicate the arguments, as in
3738 @samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
3739 arguments, a star to mark the label argument, if any. The macro does
3740 not have to have a label argument - you could also use
3741 @samp{\label@{...@}} inside one of its arguments.@refill
3743 Special names: @code{section} for section labels, @code{any} to define a
3744 group which contains all labels.@refill
3746 This may also be a function to do local parsing and identify point to be
3747 in a non-standard label environment. The function must take an
3748 argument @var{bound} and limit backward searches to this value. It
3749 should return either nil or a cons cell @code{(@var{function}
3750 . @var{position})} with the function symbol and the position where the
3751 special environment starts. See the Info documentation for an
3754 Finally this may also be @code{nil} if the entry is only meant to change
3755 some settings associated with the type indicator character (see
3758 @item @var{type-key}
3759 Type indicator character, like @code{?t}, must be a printable ASCII
3760 character. The type indicator is a single character which defines a
3761 label type. Any label inside the environment or macro is assumed to
3762 belong to this type. The same character may occur several times in this
3763 list, to cover cases in which different environments carry the same
3764 label type (like @code{equation} and @code{eqnarray}). If the type
3765 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
3766 the macro defines neutral labels just like @code{\label}. In this case
3767 the reminder of this entry is ignored.@refill
3769 @item @var{label-prefix}
3770 Label prefix string, like @samp{tab:}. The prefix is a short string
3771 used as the start of a label. It may be the empty string. The prefix
3772 may contain the following @samp{%} escapes:@refill
3775 %f Current file name, directory and extension stripped.
3776 %F Current file name relative to master file directory.
3777 %u User login name, on systems which support this.
3778 %S A section prefix derived with variable @code{reftex-section-prefixes}.
3782 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
3783 @samp{eq:intro:}.@refill
3785 @item @var{reference-format}
3786 Format string for reference insert in buffer. @samp{%s} will be
3787 replaced by the label. When the format starts with @samp{~}, this
3788 @samp{~} will only be inserted when the character before point is
3789 @emph{not} a whitespace.@refill
3791 @item @var{context-method}
3792 Indication on how to find the short context.
3795 If @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill
3800 the section heading for section labels.
3802 text following the @samp{\begin@{...@}} statement of environments (not
3803 a good choice for environments like eqnarray or enumerate, where one has
3804 several labels in a single environment).@refill
3806 text after the macro name (starting with the first arg) for
3810 If an integer, use the nth argument of the macro. As a special case,
3811 1000 means to get text after the last macro argument.@refill
3813 If a string, use as regexp to search @emph{backward} from the label.
3814 Context is then the text following the end of the match. E.g. putting
3815 this to @samp{\\caption[[@{]} will use the caption in a figure or table
3816 environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
3819 If any of @code{caption}, @code{item}, @code{eqnarray-like},
3820 @code{alignat-like}, this symbol will internally be translated into an
3821 appropriate regexp (see also the variable
3822 @code{reftex-default-context-regexps}).@refill
3824 If a function, call this function with the name of the environment/macro
3825 as argument. On call, point will be just after the @code{\label} macro.
3826 The function is expected to return a suitable context string. It should
3827 throw an exception (error) when failing to find context. As an example,
3828 here is a function returning the 10 chars following the label macro as
3832 (defun my-context-function (env-or-mac)
3833 (if (> (point-max) (+ 10 (point)))
3834 (buffer-substring (point) (+ 10 (point)))
3835 (error "Buffer too small")))
3839 Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
3840 menu, and to derive a label string. If you want to use a different
3841 method for each of these, specify them as a dotted pair.
3842 E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
3843 display, and text from the default position (@code{t}) to derive a label
3844 string. This is actually used for section labels.@refill
3846 @item @var{magic-word-list}
3847 List of magic words which identify a reference to be of this type. If
3848 the word before point is equal to one of these words when calling
3849 @code{reftex-reference}, the label list offered will be automatically
3850 restricted to labels of the correct type. If the first element of this
3851 word--list is the symbol `regexp', the strings are interpreted as regular
3854 @item @var{toc-level}
3855 The integer level at which this environment should be added to the table
3856 of contents. See also @code{reftex-section-levels}. A positive value
3857 will number the entries mixed with the sectioning commands of the same
3858 level. A negative value will make unnumbered entries. Useful only for
3859 theorem-like environments which structure the document. Will be ignored
3860 for macros. When omitted or @code{nil}, no TOC entries will be
3864 If the type indicator characters of two or more entries are the same,
3865 @b{Ref@TeX{}} will use@refill
3868 the first non-@code{nil} format and prefix
3870 the magic words of all involved entries.
3873 Any list entry may also be a symbol. If that has an association in
3874 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
3875 spliced into the list. However, builtin defaults should normally be set
3876 with the variable @code{reftex-default-label-alist-entries}.@refill
3879 @defopt reftex-section-prefixes
3880 Prefixes for section labels. When the label prefix given in an entry in
3881 @code{reftex-label-alist} contains @samp{%S}, this list is used to
3882 determine the correct prefix string depending on the current section
3883 level. The list is an alist, with each entry of the form
3884 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
3885 names like @samp{chapter}, integer section levels (as given in
3886 @code{reftex-section-levels}), and @code{t} for the default.
3889 @defopt reftex-default-context-regexps
3890 Alist with default regular expressions for finding context. The emacs
3891 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
3892 to calculate the final regular expression - so @samp{%s} will be
3893 replaced with the environment or macro.@refill
3896 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
3897 @section Creating Labels
3898 @cindex Options, creating labels
3899 @cindex Creating labels, options
3901 @defopt reftex-insert-label-flags
3902 Flags governing label insertion. The value has the form
3905 (@var{derive} @var{prompt})
3908 If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
3909 label from context. A section label for example will be derived from
3910 the section heading. The conversion of the context to a legal label is
3911 governed by the specifications given in
3912 @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
3913 the default label will consist of the prefix and a unique number, like
3914 @samp{eq:23}.@refill
3916 If @var{prompt} is @code{t}, the user will be prompted for a label
3917 string. When @var{prompt} is @code{nil}, the default label will be
3918 inserted without query.@refill
3920 So the combination of @var{derive} and @var{prompt} controls label
3921 insertion. Here is a table describing all four possibilities:@refill
3925 @var{derive} @var{prompt} @var{action}
3926 -----------------------------------------------------------
3927 nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
3928 nil t @r{Prompt for label.}
3929 t nil @r{Derive a label from context and insert. No query.}
3930 t t @r{Derive a label from context, prompt for confirmation.}
3934 Each flag may be set to @code{t}, @code{nil}, or a string of label type
3935 letters indicating the label types for which it should be true. Thus,
3936 the combination may be set differently for each label type. The default
3937 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
3938 headings (with confirmation). Prompt for figure and table labels. Use
3939 simple labels without confirmation for everything else.@refill
3941 The available label types are: @code{s} (section), @code{f} (figure),
3942 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
3943 (footnote), @code{N} (endnote) plus any definitions in
3944 @code{reftex-label-alist}.@refill
3947 @deffn Hook reftex-format-label-function
3948 If non-@code{nil}, should be a function which produces the string to
3949 insert as a label definition. The function will be called with two
3950 arguments, the @var{label} and the @var{default-format} (usually
3951 @samp{\label@{%s@}}). It should return the string to insert into the
3955 @deffn Hook reftex-string-to-label-function
3956 Function to turn an arbitrary string into a legal label.
3957 @b{Ref@TeX{}}'s default function uses the variable
3958 @code{reftex-derive-label-parameters}.@refill
3961 @deffn Hook reftex-translate-to-ascii-function
3962 Filter function which will process a context string before it is used to
3963 derive a label from it. The intended application is to convert ISO or
3964 Mule characters into something legal in labels. The default function
3965 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
3966 characters. X-Symbol (>=2.6) sets this variable to the much more
3967 general @code{x-symbol-translate-to-ascii}.@refill
3970 @defopt reftex-derive-label-parameters
3971 Parameters for converting a string into a label. This variable is a
3972 list of the following items:@refill
3975 Number of words to use.
3977 Maximum number of characters in a label string.
3979 @code{nil}: Throw away any words containing characters illegal in labels.@*
3980 @code{t}: Throw away only the illegal characters, not the whole word.
3982 @code{nil}: Never abbreviate words.@*
3983 @code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
3984 @code{1}: Abbreviate words if necessary to shorten label string.
3985 @item @var{separator}
3986 String separating different words in the label.
3987 @item @var{ignorewords}
3988 List of words which should not be part of labels.
3989 @item @var{downcase}
3990 @code{t}: Downcase words before putting them into the label.@*
3994 @defopt reftex-label-illegal-re
3995 Regexp matching characters not legal in labels.
3998 @defopt reftex-abbrev-parameters
3999 Parameters for abbreviation of words. A list of four parameters.@refill
4001 @item @var{min-chars}
4002 Minimum number of characters remaining after abbreviation.
4003 @item @var{min-kill}
4004 Minimum number of characters to remove when abbreviating words.@refill
4006 Character class before abbrev point in word.@refill
4008 Character class after abbrev point in word.@refill
4012 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
4013 @section Referencing Labels
4014 @cindex Options, referencing labels
4015 @cindex Referencing labels, options
4017 @defopt reftex-label-menu-flags
4018 List of flags governing the label menu makeup. The flags are:
4020 @item @var{table-of-contents}
4021 Show the labels embedded in a table of context.@refill
4022 @item @var{section-numbers}
4023 Include section numbers (like 4.1.3) in table of contents.@refill
4024 @item @var{counters}
4025 Show counters. This just numbers the labels in the menu.@refill
4026 @item @var{no-context}
4027 Non-@code{nil} means do @emph{not} show the short context.@refill
4029 Follow full context in other window.@refill
4030 @item @var{show-commented}
4031 Show labels from regions which are commented out.@refill
4032 @item @var{match-everywhere}
4033 Obsolete flag.@refill
4034 @item @var{show-files}
4035 Show begin and end of included files.@refill
4038 Each of these flags can be set to @code{t} or @code{nil}, or to a string
4039 of type letters indicating the label types for which it should be true.
4040 These strings work like character classes in regular expressions. Thus,
4041 setting one of the flags to @samp{"sf"} makes the flag true for section
4042 and figure labels, @code{nil} for everything else. Setting it to
4043 @samp{"^sf"} makes it the other way round.@refill
4045 The available label types are: @code{s} (section), @code{f} (figure),
4046 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4047 (footnote), plus any definitions in @code{reftex-label-alist}.@refill
4049 Most options can also be switched from the label menu itself - so if you
4050 decide here to not have a table of contents in the label menu, you can
4051 still get one interactively during selection from the label menu.@refill
4054 @defopt reftex-multiref-punctuation
4055 Punctuation strings for multiple references. When marking is used in
4056 the selection buffer to select several references, this variable
4057 associates the 3 marking characters @samp{,-+} with prefix strings to be
4058 inserted into the buffer before the corresponding @code{\ref} macro.
4059 This is used to string together whole reference sets, like
4060 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
4061 @code{reftex-reference}.@refill
4064 @defopt reftex-vref-is-default
4065 Non-@code{nil} means, the varioref macro @code{\vref} is used as
4066 default. In the selection buffer, the @kbd{v} key toggles the reference
4067 macro between @code{\ref} and @code{\vref}. The value of this variable
4068 determines the default which is active when entering the selection
4069 process. Instead of @code{nil} or @code{t}, this may also be a string
4070 of type letters indicating the label types for which it should be
4074 @defopt reftex-fref-is-default
4075 Non-@code{nil} means, the fancyref macro @code{\fref} is used as
4076 default. In the selection buffer, the @kbd{V} key toggles the reference
4077 macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of
4078 this variable determines the default which is active when entering the
4079 selection process. Instead of @code{nil} or @code{t}, this may also be
4080 a string of type letters indicating the label types for which it should
4084 @deffn Hook reftex-format-ref-function
4085 If non-@code{nil}, should be a function which produces the string to
4086 insert as a reference. Note that the insertion format can also be
4087 changed with @code{reftex-label-alist}. This hook also is used by the
4088 special commands to insert @code{\vref} and @code{\fref} references, so
4089 even if you set this, your setting will be ignored by the special
4090 commands. The function will be called with two arguments, the
4091 @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
4092 It should return the string to insert into the buffer.@refill
4095 @defopt reftex-level-indent
4096 Number of spaces to be used for indentation per section level.@refill
4099 @defopt reftex-guess-label-type
4100 Non-@code{nil} means, @code{reftex-reference} will try to guess the
4101 label type. To do that, @b{Ref@TeX{}} will look at the word before the
4102 cursor and compare it with the magic words given in
4103 @code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will
4104 immediately offer the correct label menu - otherwise it will prompt you
4105 for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}
4106 will always prompt for a label type.@refill
4109 @deffn {Normal Hook} reftex-display-copied-context-hook
4110 Normal Hook which is run before context is displayed anywhere. Designed
4111 for @w{@code{X-Symbol}}, but may have other uses as well.@refill
4114 @deffn Hook reftex-pre-refontification-functions
4115 @code{X-Symbol} specific hook. Probably not useful for other purposes.
4116 The functions get two arguments, the buffer from where the command
4117 started and a symbol indicating in what context the hook is
4121 @deffn {Normal Hook} reftex-select-label-mode-hook
4122 Normal hook which is run when a selection buffer enters
4123 @code{reftex-select-label-mode}.@refill
4126 @deffn Keymap reftex-select-label-map
4127 The keymap which is active in the labels selection process
4128 (@pxref{Referencing Labels}).@refill
4131 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
4132 @section Creating Citations
4133 @cindex Options, creating citations
4134 @cindex Creating citations, options
4136 @defopt reftex-bibliography-commands
4137 LaTeX commands which specify the BibTeX databases to use with the document.
4140 @defopt reftex-bibfile-ignore-regexps
4141 List of regular expressions to exclude files in
4142 @code{\\bibliography@{..@}}. File names matched by any of these regexps
4143 will not be parsed. Intended for files which contain only
4144 @code{@@string} macro definitions and the like, which are ignored by
4145 @b{Ref@TeX{}} anyway.@refill
4148 @defopt reftex-default-bibliography
4149 List of BibTeX database files which should be used if none are specified.
4150 When @code{reftex-citation} is called from a document with neither
4151 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4152 environment, @b{Ref@TeX{}} will scan these files instead. Intended for
4153 using @code{reftex-citation} in non-LaTeX files. The files will be
4154 searched along the BIBINPUTS or TEXBIB path.@refill
4157 @defopt reftex-sort-bibtex-matches
4158 Sorting of the entries found in BibTeX databases by reftex-citation.
4159 Possible values:@refill
4161 nil @r{Do not sort entries.}
4162 author @r{Sort entries by author name.}
4163 year @r{Sort entries by increasing year.}
4164 reverse-year @r{Sort entries by decreasing year.}
4168 @defopt reftex-cite-format
4169 The format of citations to be inserted into the buffer. It can be a
4170 string, an alist or a symbol. In the simplest case this is just the string
4171 @samp{\cite@{%l@}}, which is also the default. See the definition of
4172 @code{reftex-cite-format-builtin} for more complex examples.@refill
4174 If @code{reftex-cite-format} is a string, it will be used as the format.
4175 In the format, the following percent escapes will be expanded.@refill
4179 The BibTeX label of the citation.
4181 List of author names, see also @code{reftex-cite-punctuation}.
4183 Like %a, but abbreviate more than 2 authors like Jones et al.
4185 First author name only.
4187 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4188 @samp{%E} work a well).@refill
4191 It is also possible to access all other BibTeX database fields:
4194 %b booktitle %c chapter %d edition %h howpublished
4195 %i institution %j journal %k key %m month
4196 %n number %o organization %p pages %P first page
4197 %r address %s school %u publisher %t title
4199 %B booktitle, abbreviated %T title, abbreviated
4203 Usually, only @samp{%l} is needed. The other stuff is mainly for the
4204 echo area display, and for @code{(setq reftex-comment-citations t)}.@refill
4206 @samp{%<} as a special operator kills punctuation and space around it
4207 after the string has been formatted.@refill
4209 Beware that all this only works with BibTeX database files. When
4210 citations are made from the @code{\bibitems} in an explicit
4211 @code{thebibliography} environment, only @samp{%l} is available.@refill
4213 If @code{reftex-cite-format} is an alist of characters and strings, the
4214 user will be prompted for a character to select one of the possible
4215 format strings.@refill
4217 In order to configure this variable, you can either set
4218 @code{reftex-cite-format} directly yourself or set it to the
4219 @emph{symbol} of one of the predefined styles. The predefined symbols
4220 are those which have an association in the constant
4221 @code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
4225 @deffn Hook reftex-format-cite-function
4227 If non-@code{nil}, should be a function which produces the string to
4228 insert as a citation. Note that the citation format can also be changed
4229 with the variable @code{reftex-cite-format}. The function will be
4230 called with two arguments, the @var{citation-key} and the
4231 @var{default-format} (taken from @code{reftex-cite-format}). It should
4232 return the string to insert into the buffer.@refill
4235 @defopt reftex-comment-citations
4236 Non-@code{nil} means add a comment for each citation describing the full
4237 entry. The comment is formatted according to
4238 @code{reftex-cite-comment-format}.@refill
4241 @defopt reftex-cite-comment-format
4242 Citation format used for commented citations. Must @emph{not} contain
4243 @samp{%l}. See the variable @code{reftex-cite-format} for possible
4244 percent escapes.@refill
4247 @defopt reftex-cite-punctuation
4248 Punctuation for formatting of name lists in citations. This is a list
4249 of 3 strings.@refill
4252 normal names separator, like @samp{, } in Jones, Brown and Miller
4254 final names separator, like @samp{ and } in Jones, Brown and Miller
4256 The @samp{et al.} string, like @samp{ @{\it et al.@}} in
4257 Jones @{\it et al.@}
4261 @deffn {Normal Hook} reftex-select-bib-mode-hook
4262 Normal hook which is run when a selection buffer enters
4263 @code{reftex-select-bib-mode}.@refill
4266 @deffn Keymap reftex-select-bib-map
4267 The keymap which is active in the citation-key selection process
4268 (@pxref{Creating Citations}).@refill
4271 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options
4272 @section Index Support
4273 @cindex Options, Index support
4274 @cindex Index support, options
4276 @defopt reftex-support-index
4277 Non-@code{nil} means, index entries are parsed as well. Index support
4278 is resource intensive and the internal structure holding the parsed
4279 information can become quite big. Therefore it can be turned off. When
4280 this is @code{nil} and you execute a command which requires index
4281 support, you will be asked for confirmation to turn it on and rescan the
4285 @defopt reftex-index-special-chars
4286 List of special characters in index entries, given as strings. These
4287 correspond to the @code{MakeIndex} keywords
4288 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4291 @defopt reftex-index-macros
4292 List of macros which define index entries. The structure of each entry
4295 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4298 @var{macro} is the macro. Arguments should be denoted by empty braces,
4299 as for example in @samp{\index[]@{*@}}. Use square brackets to denote
4300 optional arguments. The star marks where the index key is.@refill
4302 @var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
4303 are reserved for the default index and the glossary. Other indices can
4304 be defined as well. If this is an integer, the Nth argument of the
4305 macro holds the index tag.@refill
4307 @var{key} is a character which is used to identify the macro for input
4308 with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
4309 reserved for default index and glossary.@refill
4311 @var{prefix} can be a prefix which is added to the @var{key} part of the
4312 index entry. If you have a macro
4313 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4314 should be @samp{Molecules!}.@refill
4316 @var{exclude} can be a function. If this function exists and returns a
4317 non-nil value, the index entry at point is ignored. This was
4318 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4319 in the LaTeX2e @code{index} package.@refill
4321 @var{repeat}, if non-@code{nil}, means the index macro does not typeset
4322 the entry in the text, so that the text has to be repeated outside the
4323 index macro. Needed for @code{reftex-index-selection-or-word} and for
4324 indexing from the phrase buffer.@refill
4326 The final entry may also be a symbol. It must have an association in
4327 the variable @code{reftex-index-macros-builtin} to specify the main
4328 indexing package you are using. Legal values are currently@refill
4330 default @r{The LaTeX default - unnecessary to specify this one}
4331 multind @r{The multind.sty package}
4332 index @r{The index.sty package}
4333 index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
4334 @r{Should not be used - only for old documents}
4336 Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
4337 so with a sufficiently new version of AUCTeX, you should not set the
4341 @defopt reftex-index-default-macro
4342 The default index macro for @code{reftex-index-selection-or-word}.
4343 This is a list with @code{(@var{macro-key} @var{default-tag})}.
4345 @var{macro-key} is a character identifying an index macro - see
4346 @code{reftex-index-macros}.
4348 @var{default-tag} is the tag to be used if the macro requires a
4349 @var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
4350 @b{Ref@TeX{}} will ask for it. When this is the empty string and the
4351 TAG argument of the index macro is optional, the TAG argument will be
4355 @defopt reftex-index-default-tag
4356 Default index tag. When working with multiple indexes, RefTeX queries
4357 for an index tag when creating index entries or displaying a specific
4358 index. This variable controls the default offered for these queries.
4359 The default can be selected with @key{RET} during selection or
4360 completion. Legal values of this variable are:@refill
4362 nil @r{Do not provide a default index}
4363 "tag" @r{The default index tag given as a string, e.g. "idx"}
4364 last @r{The last used index tag will be offered as default}
4368 @defopt reftex-index-math-format
4369 Format of index entries when copied from inside math mode. When
4370 @code{reftex-index-selection-or-word} is executed inside TeX math mode,
4371 the index key copied from the buffer is processed with this format
4372 string through the @code{format} function. This can be used to add the
4373 math delimiters (e.g. @samp{$}) to the string. Requires the
4374 @file{texmathp.el} library which is part of AUCTeX.@refill
4377 @defopt reftex-index-phrase-file-extension
4378 File extension for the index phrase file. This extension will be added
4379 to the base name of the master file.
4382 @defopt reftex-index-phrases-logical-and-regexp
4383 Regexp matching the @samp{and} operator for index arguments in phrases
4384 file. When several index arguments in a phrase line are separated by
4385 this operator, each part will generate an index macro. So each match of
4386 the search phrase will produce @emph{several} different index entries.
4387 Make sure this does no match things which are not separators. This
4388 logical @samp{and} has higher priority than the logical @samp{or}
4389 specified in @code{reftex-index-phrases-logical-or-regexp}.@refill
4392 @defopt reftex-index-phrases-logical-or-regexp
4393 Regexp matching the @samp{or} operator for index arguments in phrases
4394 file. When several index arguments in a phrase line are separated by
4395 this operator, the user will be asked to select one of them at each
4396 match of the search phrase. The first index arg will be the default. A
4397 number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make
4398 sure this does no match things which are not separators. The logical
4399 @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4400 has higher priority than this logical @samp{or}.@refill
4403 @defopt reftex-index-phrases-search-whole-words
4404 Non-@code{nil} means phrases search will look for whole words, not subwords.
4405 This works by requiring word boundaries at the beginning and end of
4406 the search string. When the search phrase already has a non-word-char
4407 at one of these points, no word boundary is required there.
4410 @defopt reftex-index-phrases-case-fold-search
4411 Non-@code{nil} means, searching for index phrases will ignore
4415 @defopt reftex-index-verify-function
4416 A function which is called at each match during global indexing.
4417 If the function returns nil, the current match is skipped.
4420 @defopt reftex-index-phrases-skip-indexed-matches
4421 Non-@code{nil} means, skip matches which appear to be indexed already.
4422 When doing global indexing from the phrases buffer, searches for some
4423 phrases may match at places where that phrase was already indexed. In
4424 particular when indexing an already processed document again, this
4425 will even be the norm. When this variable is non-@code{nil},
4426 @b{Ref@TeX{}} checks if the match is an index macro argument, or if an
4427 index macro is directly before or after the phrase. If that is the
4428 case, that match will be ignored.@refill
4431 @defopt reftex-index-phrases-wrap-long-lines
4432 Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
4433 Inserting indexing commands in a line makes the line longer - often
4434 so long that it does not fit onto the screen. When this variable is
4435 non-@code{nil}, newlines will be added as necessary before and/or after the
4436 indexing command to keep lines short. However, the matched text
4437 phrase and its index command will always end up on a single line.@refill
4440 @defopt reftex-index-phrases-sort-prefers-entry
4441 Non-@code{nil} means when sorting phrase lines, the explicit index entry
4442 is used. Phrase lines in the phrases buffer contain a search phrase, and
4443 sorting is normally based on these. Some phrase lines also have
4444 an explicit index argument specified. When this variable is
4445 non-@code{nil}, the index argument will be used for sorting.@refill
4448 @defopt reftex-index-phrases-sort-in-blocks
4449 Non-@code{nil} means, empty and comment lines separate phrase buffer
4450 into blocks. Sorting will then preserve blocks, so that lines are
4451 re-arranged only within blocks.
4454 @defopt reftex-index-phrases-map
4455 Keymap for the Index Phrases buffer.
4458 @defopt reftex-index-phrases-mode-hook
4459 Normal hook which is run when a buffer is put into
4460 @code{reftex-index-phrases-mode}.@refill
4463 @defopt reftex-index-section-letters
4464 The letters which denote sections in the index. Usually these are all
4465 capital letters. Don't use any downcase letters. Order is not
4466 significant, the index will be sorted by whatever the sort function
4467 thinks is correct. In addition to these letters, @b{Ref@TeX{}} will
4468 create a group @samp{!} which contains all entries sorted below the
4469 lowest specified letter. In the @file{*Index*} buffer, pressing any of
4470 these capital letters or @kbd{!} will jump to that section.@refill
4473 @defopt reftex-index-include-context
4474 Non-@code{nil} means, display the index definition context in the
4475 @file{*Index*} buffer. This flag may also be toggled from the
4476 @file{*Index*} buffer with the @kbd{c} key.
4479 @defopt reftex-index-follow-mode
4480 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4481 window to follow. The other window will show the corresponding part of
4482 the document. This flag can be toggled from within the @file{*Index*}
4483 buffer with the @kbd{f} key.
4486 @deffn Keymap reftex-index-map
4487 The keymap which is active in the @file{*Index*} buffer
4488 (@pxref{Index Support}).@refill
4491 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options
4492 @section Viewing Cross-References
4493 @cindex Options, viewing cross-references
4494 @cindex Viewing cross-references, options
4496 @defopt reftex-view-crossref-extra
4497 Macros which can be used for the display of cross references.
4498 This is used when `reftex-view-crossref' is called with point in an
4499 argument of a macro. Note that crossref viewing for citations,
4500 references (both ways) and index entries is hard-coded. This variable
4501 is only to configure additional structures for which crossreference
4502 viewing can be useful. Each entry has the structure
4504 (@var{macro-re} @var{search-re} @var{highlight}).
4506 @var{macro-re} is matched against the macro. @var{search-re} is the
4507 regexp used to search for cross references. @samp{%s} in this regexp is
4508 replaced with the macro argument at point. @var{highlight} is an
4509 integer indicating which subgroup of the match should be highlighted.
4512 @defopt reftex-auto-view-crossref
4513 Non-@code{nil} means, initially turn automatic viewing of crossref info
4514 on. Automatic viewing of crossref info normally uses the echo area.
4515 Whenever point is on the argument of a @code{\ref} or @code{\cite}
4516 macro, and no other message is being displayed, the echo area will
4517 display information about that cross reference. You can also set the
4518 variable to the symbol @code{window}. In this case a small temporary
4519 window is used for the display. This feature can be turned on and of
4520 from the menu (Ref->Options).@refill
4523 @defopt reftex-idle-time
4524 Time (secs) Emacs has to be idle before automatic crossref display is
4528 @defopt reftex-cite-view-format
4529 Citation format used to display citation info in the message area. See
4530 the variable @code{reftex-cite-format} for possible percent
4534 @defopt reftex-revisit-to-echo
4535 Non-@code{nil} means, automatic citation display will revisit files if
4536 necessary. When nil, citation display in echo area will only be active
4537 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4538 BibTeX database files which are already visited by a live associated
4542 @defopt reftex-cache-cite-echo
4543 Non-@code{nil} means, the information displayed in the echo area for
4544 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4545 saved along with the parsing information. The cache survives document
4546 scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
4549 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options
4550 @section Finding Files
4551 @cindex Options, Finding Files
4552 @cindex Finding files, options
4554 @defopt reftex-texpath-environment-variables
4555 List of specifications how to retrieve the search path for TeX files.
4556 Several entries are possible.@refill
4559 If an element is the name of an environment variable, its content is
4562 If an element starts with an exclamation mark, it is used as a command
4563 to retrieve the path. A typical command with the kpathsearch library
4564 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4566 Otherwise the element itself is interpreted as a path.
4568 Multiple directories can be separated by the system dependent
4569 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4570 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4573 @defopt reftex-bibpath-environment-variables
4574 List of specifications how to retrieve the search path for BibTeX
4575 files. Several entries are possible.@refill
4578 If an element is the name of an environment variable, its content is
4581 If an element starts with an exclamation mark, it is used as a command
4582 to retrieve the path. A typical command with the kpathsearch library
4583 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4585 Otherwise the element itself is interpreted as a path.
4587 Multiple directories can be separated by the system dependent
4588 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4589 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4592 @defopt reftex-file-extensions
4593 Association list with file extensions for different file types.
4594 This is a list of items, each item is like:
4595 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4597 @var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
4598 @var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
4599 @var{other-ext}: @r{Any number of other legal extensions for this file type.}
4601 When a files is searched and it does not have any of the legal extensions,
4602 we try the default extension first, and then the naked file name.@refill
4605 @defopt reftex-search-unrecursed-path-first
4606 Non-@code{nil} means, search all specified directories before trying
4607 recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
4608 then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
4609 option is @code{nil}, the subdirectories of @samp{./} are searched
4610 before @samp{/tex/}. This is mainly for speed - most of the time the
4611 recursive path is for the system files and not for the user files. Set
4612 this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
4613 equal names in wrong sequence.@refill
4616 @defopt reftex-use-external-file-finders
4617 Non-@code{nil} means, use external programs to find files. Normally,
4618 @b{Ref@TeX{}} searches the paths given in the environment variables
4619 @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
4620 database files. With this option turned on, it calls an external
4621 program specified in the option @code{reftex-external-file-finders}
4622 instead. As a side effect, the variables
4623 @code{reftex-texpath-environment-variables} and
4624 @code{reftex-bibpath-environment-variables} will be ignored.
4627 @defopt reftex-external-file-finders
4628 Association list with external programs to call for finding files. Each
4629 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
4630 @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
4631 string containing the external program to use with any arguments.
4632 @code{%f} will be replaced by the name of the file to be found. Note
4633 that these commands will be executed directly, not via a shell. Only
4634 relevant when @code{reftex-use-external-file-finders} is
4635 non-@code{nil}.@refill
4639 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
4640 @section Optimizations
4641 @cindex Options, optimizations
4642 @cindex Optimizations, options
4644 @defopt reftex-keep-temporary-buffers
4645 Non-@code{nil} means, keep buffers created for parsing and lookup.
4646 @b{Ref@TeX{}} sometimes needs to visit files related to the current
4647 document. We distinguish files visited for@refill
4650 Parts of a multifile document loaded when (re)-parsing the
4653 BibTeX database files and TeX files loaded to find a reference, to
4654 display label context, etc.@refill
4656 The created buffers can be kept for later use, or be thrown away
4657 immediately after use, depending on the value of this variable:@refill
4661 Throw away as much as possible.
4665 Throw away buffers created for parsing, but keep the ones created for
4669 If a buffer is to be kept, the file is visited normally (which is
4670 potentially slow but will happen only once). If a buffer is to be thrown
4671 away, the initialization of the buffer depends upon the variable
4672 @code{reftex-initialize-temporary-buffers}.@refill
4675 @defopt reftex-initialize-temporary-buffers
4676 Non-@code{nil} means do initializations even when visiting file
4677 temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
4678 other stuff to briefly visit a file. When @code{t}, the full default
4679 initializations are done (@code{find-file-hook} etc.). Instead of
4680 @code{t} or @code{nil}, this variable may also be a list of hook
4681 functions to do a minimal initialization.@refill
4684 @defopt reftex-no-include-regexps
4685 List of regular expressions to exclude certain input files from parsing.
4686 If the name of a file included via @code{\include} or @code{\input} is
4687 matched by any of the regular expressions in this list, that file is not
4688 parsed by @b{Ref@TeX{}}.
4691 @defopt reftex-enable-partial-scans
4692 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4693 Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
4694 commands, or with the @kbd{r} key in menus. When this option is
4695 @code{t} in a multifile document, we will only parse the current buffer,
4696 or the file associated with the label or section heading near point in a
4697 menu. Requesting re-parsing of an entire multifile document then
4698 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
4702 @defopt reftex-save-parse-info
4703 Non-@code{nil} means, save information gathered with parsing in files.
4704 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
4705 used to save the information. When this variable is @code{t},
4708 accessing the parsing information for the first time in an editing
4709 session will read that file (if available) instead of parsing the
4712 exiting Emacs or killing a buffer in reftex-mode will cause a new
4713 version of the file to be written.@refill
4717 @defopt reftex-parse-file-extension
4718 File extension for the file in which parser information is stored.
4719 This extension is added to the base name of the master file.
4722 @defopt reftex-allow-automatic-rescan
4723 Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
4724 necessary. Applies (currently) only in rare cases, when a new label
4725 cannot be placed with certainty into the internal label list.
4728 @defopt reftex-use-multiple-selection-buffers
4729 Non-@code{nil} means use a separate selection buffer for each label
4730 type. These buffers are kept from one selection to the next and need
4731 not to be created for each use - so the menu generally comes up faster.
4732 The selection buffers will be erased (and therefore updated)
4733 automatically when new labels in its category are added. See the
4734 variable @code{reftex-auto-update-selection-buffers}.@refill
4737 @defopt reftex-auto-update-selection-buffers
4738 Non-@code{nil} means, selection buffers will be updated automatically.
4739 When a new label is defined with @code{reftex-label}, all selection
4740 buffers associated with that label category are emptied, in order to
4741 force an update upon next use. When @code{nil}, the buffers are left
4742 alone and have to be updated by hand, with the @kbd{g} key from the
4743 label selection process. The value of this variable will only have any
4744 effect when @code{reftex-use-multiple-selection-buffers} is
4745 non-@code{nil}.@refill
4748 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
4749 @section Fontification
4750 @cindex Options, fontification
4751 @cindex Fontification, options
4753 @defopt reftex-use-fonts
4754 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
4755 Font-lock must be loaded as well to actually get fontified
4756 display. After changing this option, a rescan may be necessary to
4760 @defopt reftex-refontify-context
4761 Non-@code{nil} means, re-fontify the context in the label menu with
4762 font-lock. This slightly slows down the creation of the label menu. It
4763 is only necessary when you definitely want the context fontified.@refill
4765 This option may have 3 different values:
4772 Refontify when necessary, e.g. with old versions of the x-symbol
4775 The option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill
4778 @defopt reftex-highlight-selection
4779 Non-@code{nil} means, highlight selected text in selection and
4780 @file{*toc*} buffers. Normally, the text near the cursor is the
4781 @emph{selected} text, and it is highlighted. This is the entry most
4782 keys in the selection and @file{*toc*} buffers act on. However, if you
4783 mainly use the mouse to select an item, you may find it nice to have
4784 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
4785 variable may have one of these values:@refill
4788 nil @r{No highlighting.}
4789 cursor @r{Highlighting is cursor driven.}
4790 mouse @r{Highlighting is mouse driven.}
4791 both @r{Both cursor and mouse trigger highlighting.}
4794 Changing this variable requires to rebuild the selection and *toc*
4795 buffers to become effective (keys @kbd{g} or @kbd{r}).@refill
4798 @defopt reftex-cursor-selected-face
4799 Face name to highlight cursor selected item in toc and selection buffers.
4800 See also the variable @code{reftex-highlight-selection}.@refill
4802 @defopt reftex-mouse-selected-face
4803 Face name to highlight mouse selected item in toc and selection buffers.
4804 See also the variable @code{reftex-highlight-selection}.@refill
4806 @defopt reftex-file-boundary-face
4807 Face name for file boundaries in selection buffer.
4809 @defopt reftex-label-face
4810 Face name for labels in selection buffer.
4812 @defopt reftex-section-heading-face
4813 Face name for section headings in toc and selection buffers.
4815 @defopt reftex-toc-header-face
4816 Face name for the header of a toc buffer.
4818 @defopt reftex-bib-author-face
4819 Face name for author names in bib selection buffer.
4821 @defopt reftex-bib-year-face
4822 Face name for year in bib selection buffer.
4824 @defopt reftex-bib-title-face
4825 Face name for article title in bib selection buffer.
4827 @defopt reftex-bib-extra-face
4828 Face name for bibliographic information in bib selection buffer.
4830 @defopt reftex-select-mark-face
4831 Face name for marked entries in the selection buffers.
4833 @defopt reftex-index-header-face
4834 Face name for the header of an index buffer.
4836 @defopt reftex-index-section-face
4837 Face name for the start of a new letter section in the index.
4839 @defopt reftex-index-tag-face
4840 Face name for index names (for multiple indices).
4842 @defopt reftex-index-face
4843 Face name for index entries.
4846 @node Options (Misc), , Options (Fontification), Options
4847 @section Miscellaneous
4848 @cindex Options, misc
4850 @defopt reftex-extra-bindings
4851 Non-@code{nil} means, make additional key bindings on startup. These
4852 extra bindings are located in the users @samp{C-c letter}
4853 map. @xref{Key Bindings}.@refill
4856 @defopt reftex-plug-into-AUCTeX
4857 Plug-in flags for AUCTeX interface. This variable is a list of
4858 5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}
4862 - supply labels in new sections and environments (flag 1)
4863 - supply arguments for macros like @code{\label} (flag 2)
4864 - supply arguments for macros like @code{\ref} (flag 3)
4865 - supply arguments for macros like @code{\cite} (flag 4)
4866 - supply arguments for macros like @code{\index} (flag 5)
4869 You may also set the variable itself to t or nil in order to turn all
4870 options on or off, respectively.@*
4871 Supplying labels in new sections and environments applies when creating
4872 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
4873 Supplying macro arguments applies when you insert such a macro
4874 interactively with @kbd{C-c @key{RET}}.@*
4875 See the AUCTeX documentation for more information.
4878 @defopt reftex-revisit-to-follow
4879 Non-@code{nil} means, follow-mode will revisit files if necessary.
4880 When nil, follow-mode will be suspended for stuff in unvisited files.
4883 @defopt reftex-allow-detached-macro-args
4884 Non-@code{nil} means, allow arguments of macros to be detached by
4885 whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
4886 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
4887 this will be the case even if @code{\bb} is defined with zero or one
4891 @node Keymaps and Hooks, Changes, Options, Top
4892 @section Keymaps and Hooks
4895 @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
4897 @deffn Keymap reftex-mode-map
4898 The keymap for @b{Ref@TeX{}} mode.
4901 @deffn {Normal Hook} reftex-load-hook
4902 Normal hook which is being run when loading @file{reftex.el}.
4905 @deffn {Normal Hook} reftex-mode-hook
4906 Normal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill
4909 Furthermore, the 4 modes used for referencing labels, creating
4910 citations, the table of contents buffer and the phrases buffer have
4911 their own keymaps and mode hooks. See the respective sections. There
4912 are many more hooks which are described in the relevant sections about
4913 options for a specific part of @b{Ref@TeX{}}.@refill
4915 @node Changes, , Keymaps and Hooks, Top
4919 Here is a list of recent changes to @b{Ref@TeX{}}.
4922 @noindent @b{Version 1.00}
4925 released on 7 Jan 1997.
4928 @noindent @b{Version 1.04}
4931 Macros as wrappers, AMSTeX support, delayed context parsing for
4935 @noindent @b{Version 1.05}
4941 @noindent @b{Version 1.07}
4944 @b{Ref@TeX{}} gets its own menu.
4947 @noindent @b{Version 1.09}
4950 Support for @code{tex-main-file}, an analogue for
4951 @code{TeX-master}.@refill
4956 @noindent @b{Version 2.00}
4959 Labels can be derived from context (default for sections).
4961 Configuration of label insertion and label referencing revised.
4963 Crossref fields in BibTeX database entries.
4965 @code{reftex-toc} introduced (thanks to Stephen Eglen).
4968 @noindent @b{Version 2.03}
4971 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
4972 default environments.@refill
4974 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
4976 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
4977 @code{reftex-arg-cite}.@refill
4979 Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
4982 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
4985 Finding context with a hook function.
4987 Sorting BibTeX entries (new variable:
4988 @code{reftex-sort-bibtex-matches}).
4991 @noindent @b{Version 2.05}
4994 Support for @file{custom.el}.
4996 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
4999 @noindent @b{Version 2.07}
5002 New functions @code{reftex-search-document},
5003 @code{reftex-query-replace-document}.
5006 @noindent @b{Version 2.11}
5009 Submitted for inclusion to Emacs and XEmacs.
5012 @noindent @b{Version 2.14}
5015 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
5019 @noindent @b{Version 2.17}
5022 Label prefix expands % escapes with current file name and other stuff.
5024 Citation format now with % escapes. This is not backward
5027 TEXINPUTS variable recognized when looking for input files.
5029 Context can be the nth argument of a macro.@refill
5031 Searching in the select buffer is now possible (@kbd{C-s} and
5034 Display and derive-label can use two different context methods.
5036 AMSmath @code{xalignat} and @code{xxalignat} added.
5039 @noindent @b{Version 3.00}
5042 @b{Ref@TeX{}} should work better for very large projects:
5044 The new parser works without creating a master buffer.
5046 Rescanning can be limited to a part of a multifile document.
5048 Information from the parser can be stored in a file.
5050 @b{Ref@TeX{}} can deal with macros having a naked label as an argument.
5052 Macros may have white space and newlines between arguments.
5054 Multiple identical section headings no longer confuse
5055 @code{reftex-toc}.@refill
5057 @b{Ref@TeX{}} should work correctly in combination with buffer-altering
5058 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill
5060 All labeled environments discussed in @emph{The LaTeX Companion} by
5061 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
5062 @b{Ref@TeX{}}'s defaults.@refill
5065 @noindent @b{Version 3.03}
5068 Support for the LaTeX package @code{xr}, for inter-document
5071 A few (minor) Mule-related changes.
5073 Fixed bug which could cause @emph{huge} @file{.rel} files.
5075 Search for input and @file{.bib} files with recursive path definitions.
5078 @noindent @b{Version 3.04}
5081 Fixed BUG in the @emph{xr} support.
5084 @noindent @b{Version 3.05}
5087 Compatibility code now first checks for XEmacs feature.
5090 @noindent @b{Version 3.07}
5093 @code{Ref} menu improved.
5096 @noindent @b{Version 3.10}
5099 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5101 Removed unimportant code which caused OS/2 Emacs to crash.
5103 All customization variables now accessible from menu.
5106 @noindent @b{Version 3.11}
5109 Fixed bug which led to naked label in (e.g.) footnotes.
5111 Added scroll-other-window functions to RefTeX-Select.
5114 @noindent @b{Version 3.12}
5117 There are 3 new keymaps for customization: @code{reftex-toc-map},
5118 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5120 Refontification uses more standard font-lock stuff.
5122 When no BibTeX database files are specified, citations can also use
5123 @code{\bibitem} entries from a @code{thebibliography} environment.@refill
5126 @noindent @b{Version 3.14}
5129 Selection buffers can be kept between selections: this is faster.
5130 See new variable @code{reftex-use-multiple-selection-buffers}.@refill
5132 Prefix interpretation of reftex-view-crossref changed.
5134 Support for the @code{varioref} package (@kbd{v} key in selection
5138 @noindent @b{Version 3.16}
5141 New hooks @code{reftex-format-label-function},
5142 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill
5144 TeXInfo documentation completed.
5146 Some restrictions in Label inserting and referencing removed.
5148 New variable @code{reftex-default-bibliography}.
5151 @noindent @b{Version 3.17}
5154 Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
5157 New command @code{reftex-save-all-document-buffers}.
5159 Magic word matching made more intelligent.
5161 Selection process can switch to completion (with @key{TAB}).
5163 @code{\appendix} is now recognized and influences section numbering.
5165 File commentary shortened considerably (use Info documentation).
5167 New option @code{reftex-no-include-regexps} to skip some include files.
5169 New option @code{reftex-revisit-to-follow}.
5172 @noindent @b{Version 3.18}
5175 The selection now uses a recursive edit, much like minibuffer input.
5176 This removes all restrictions during selection. E.g. you can now
5177 switch buffers at will, use the mouse etc.@refill
5179 New option @code{reftex-highlight-selection}.
5181 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
5184 Fixed some problems regarding the interaction with VIPER mode.
5186 Follow-mode is now only used after point motion.
5188 @b{Ref@TeX{}} now finally does not fontify temporary files anymore.
5191 @noindent @b{Version 3.19}
5194 Fixed bug with AUCTeX @code{TeX-master}.
5197 @noindent @b{Version 3.21}
5200 New options for all faces used by @b{Ref@TeX{}}. They're in the
5201 customization group @code{reftex-fontification-configurations}.@refill
5204 @noindent @b{Version 3.22}
5207 Fixed bug with empty context strings.
5209 @code{reftex-mouse-view-crossref} is now bound by default at
5210 @kbd{S-mouse-2}.@refill
5213 @noindent @b{Version 3.23}
5216 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5218 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
5221 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5222 automatic display of crossref information in the echo area. See
5223 variable @code{reftex-auto-view-crossref}.
5225 AUCTeX interface updates:
5228 AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
5230 @b{Ref@TeX{}} notifies AUCTeX about new labels.
5232 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
5234 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5236 Settings added to @b{Ref@TeX{}} via style files remain local.
5239 Fixed bug with @code{reftex-citation} in non-latex buffers.
5241 Fixed bug with syntax table and context refontification.
5243 Safety-net for name change of @code{font-lock-reference-face}.
5246 @noindent @b{Version 3.24}
5249 New option @code{reftex-revisit-to-echo}.
5251 Interface with X-Symbol (>=2.6) is now complete and stable.
5253 Adapted to new outline, which uses overlays.
5255 File names in @code{\bibliography} may now have the @code{.bib}
5258 Fixed Bug with parsing "single file" from master file buffer.
5261 @noindent @b{Version 3.25}
5264 Echoing of citation info caches the info for displayed entries.
5265 New option @code{reftex-cache-cite-echo}.@refill
5267 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
5270 Default of @code{reftex-revisit-to-follow} changed to nil.
5273 @noindent @b{Version 3.26}
5276 [X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
5278 New hooks @code{reftex-translate-to-ascii-function},
5279 @code{reftex-string-to-label-function}.@refill
5281 Made sure automatic crossref display will not visit/scan files.
5284 @noindent @b{Version 3.27}
5287 Macros can define @emph{neutral} labels, just like @code{\label}
5290 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5293 @noindent @b{Version 3.28}
5296 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5297 timer, since itimer restart is not reliable.@refill
5299 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5301 Expansion of recursive tex and bib path rewritten.
5303 Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
5305 Fixed bug with section numbering after *-red sections.
5308 @noindent @b{Version 3.30}
5311 In @code{reftex-citation}, the regular expression used to scan BibTeX
5312 files can be specified using completion on known citation keys.
5314 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5317 New command @code{reftex-renumber-simple-labels} to renumber simple
5318 labels like @samp{eq:13} sequentially through a document.
5320 @noindent @b{Version 3.33}
5323 Multiple selection buffers are now hidden buffers (they start with a
5326 Fixed bug with file search when TEXINPUTS environment variable is empty.
5328 @noindent @b{Version 3.34}
5331 Additional flag in @code{reftex-derive-label-parameters} do make only
5332 lowercase labels (default @code{t}).
5334 All @file{.rel} files have a final newline to avoid queries.
5336 Single byte representations of accented European letters (ISO-8859-1)
5337 are now legal in labels.
5339 @noindent @b{Version 3.35}
5342 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5343 This takes back the related changes in 3.34 for safety reasons.@refill
5345 @noindent @b{Version 3.36}
5348 New value @code{window} for option @code{reftex-auto-view-crossref}.
5350 @noindent @b{Version 3.38}
5353 @code{reftex-view-crossref} no longer moves to find a macro. Point has
5354 to be on the macro argument.
5356 @noindent @b{Version 3.41}
5359 New options @code{reftex-texpath-environment-variables},
5360 @code{reftex-use-external-file-finders},
5361 @code{reftex-external-file-finders},
5362 @code{reftex-search-unrecursed-path-first}.
5364 @emph{kpathsearch} support. See new options and
5365 @code{reftex-bibpath-environment-variables}.
5367 @noindent @b{Version 3.42}
5370 File search further refined. New option @code{reftex-file-extensions}.
5372 @file{*toc*} buffer can show the file boundaries of a multifile
5373 document, all labels and associated context. New keys @kbd{i}, @kbd{l},
5374 and @kbd{c}. New options @code{reftex-toc-include-labels},
5375 @code{reftex-toc-include-context},
5376 @code{reftex-toc-include-file-boundaries}. @refill
5378 @noindent @b{Version 3.43}
5381 Viewing cross-references generalized. Now works on @code{\label},
5382 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5383 these, and from BibTeX buffers.@refill
5385 New option @code{reftex-view-crossref-extra}.@refill
5387 Support for the additional sectioning commands @code{\addchap} and
5388 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill
5390 Files in @code{reftex-default-bibliography} will be searched along
5391 @code{BIBINPUTS} path.@refill
5393 Reading a parse file now checks consistency.
5396 @noindent @b{Version 4.00}
5399 RefTeX has been split into several smaller files which are autoloaded on
5402 Index support, along with many new options.
5404 The selection of keys for @code{\ref} and @code{\cite} now allows to
5405 select multiple items by marking entries with the @kbd{m} key.
5409 @noindent @b{Version 4.01}
5412 New command @code{reftex-index-globally} to index a word in many
5413 places in the document. Also available from the index buffer with
5416 The first item in a @code{reftex-label-alist} entry may now also be a parser
5417 function to do non-standard parsing.
5419 @code{reftex-auto-view-crossref} no longer interferes with
5420 @code{pop-up-frames} (patch from Stefan Monnier).
5422 @noindent @b{Version 4.02}
5425 macros ending in @samp{refrange} are considered to contain references.
5427 Index entries made with @code{reftex-index-selection-or-word} in TeX
5428 math mode automatically get enclosing @samp{$} to preserve math mode. See
5429 new option @code{reftex-index-math-format}. Requires AUCTeX.
5431 @noindent @b{Version 4.04}
5434 New option @code{reftex-index-default-tag} implements a default for queries.
5436 @noindent @b{Version 4.06}
5439 @code{reftex-section-levels} can contain a function to compute the level
5440 of a sectioning command.
5442 Multiple @code{thebibliography} environments recognized.
5444 @noindent @b{Version 4.09}
5447 New option @code{reftex-toc-max-level} to limit the depth of the toc.
5448 New key binding @kbd{t} in the @file{*toc*} buffer to change this
5451 RefTeX maintains an @file{Index Phrases} file in which phrases can be
5452 collected. When the document is ready, RefTeX can search all
5453 these phrases and assist indexing all matches.@refill
5455 The variables @code{reftex-index-macros} and
5456 @code{reftex-index-default-macro} have changed their syntax slightly.
5457 The @var{repeat} parameter has move from the latter to the former.
5458 Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5459 need to be adapted.@refill
5461 The variable @code{reftex-section-levels} no longer contains the
5462 default stuff which has been moved to a constant.@refill
5464 Environments like theorems can be placed into the TOC by putting
5465 entries for @samp{"begin@{theorem@}"} in
5466 @code{reftex-setion-levels}.@refill
5468 @noindent @b{Version 4.10}
5471 Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5472 with @file{reftex-vars.el} on DOS machines.
5474 New options @code{reftex-parse-file-extension} and
5475 @code{reftex-index-phrase-file-extension}.
5477 @noindent @b{Version 4.11}
5480 Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5482 @noindent @b{Version 4.12}
5485 Support for @file{bibentry} citation style.
5487 @noindent @b{Version 4.15}
5490 Fixed bug with parsing of BibTeX files, when fields contain quotes or
5491 unmatched parenthesis.
5495 Improved interaction with Emacs LaTeX mode.
5497 @noindent @b{Version 4.17}
5500 The toc window can be split off horizontally. See new options
5501 @code{reftex-toc-split-windows-horizontally},
5502 @code{reftex-toc-split-windows-horizontally-fraction}.
5504 It is possible to specify a function which verifies an index match
5505 during global indexing. See new option @code{reftex-index-verify-function}.
5507 The macros which input a file in LaTeX (like \input, \include) can
5508 be configured. See new option @code{reftex-include-file-commands}.
5510 The macros which specify the bibliography file (like \bibliography) can
5511 be configured. See new option @code{reftex-bibliography-commands}.
5513 The regular expression used to search for the \bibliography macro has
5514 been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
5519 @noindent @b{Version 4.18}
5522 @code{reftex-citation} uses the word before the cursor as a default
5526 @node Index, , , Top