1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/reftex
4 @settitle RefTeX User Manual
9 @c Version and Contact Info
12 @set DATE February 2006
13 @set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site}
14 @set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page}
15 @set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers}
16 @set MAINTAINER the AUC@TeX{} project
17 @set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org})
18 @set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org})
19 @set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org})
20 @set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}
24 This file documents @b{Ref@TeX{}}, a package to do labels, references,
25 citations and indices for LaTeX documents with Emacs.
27 This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
28 @b{Ref@TeX{}} @value{VERSION}
30 Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
31 2005, 2006, 2007 Free Software Foundation, Inc.
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.2 or
36 any later version published by the Free Software Foundation; with no
37 Invariant Sections, with the Front-Cover texts being ``A GNU
38 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
39 license is included in the section entitled ``GNU Free Documentation
40 License'' in the Emacs manual.
42 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
43 this GNU Manual, like GNU software. Copies published by the Free
44 Software Foundation raise funds for GNU development.''
46 This document is part of a collection distributed under the GNU Free
47 Documentation License. If you want to distribute this document
48 separately from the collection, you can do so by adding a copy of the
49 license to the document, as described in section 6 of the license.
55 * RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
62 @c Subheadings inside a table. Need a difference between info and the rest.
63 @macro tablesubheading{text}
73 @title Ref@TeX{} User Manual
74 @subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
75 @subtitle Edition @value{EDITION}, @value{DATE}
77 @author by Carsten Dominik
79 @vskip 0pt plus 1filll
86 @b{Ref@TeX{}} is a package for managing Labels, References,
87 Citations and index entries with GNU Emacs.
89 Don't be discouraged by the size of this manual, which covers
90 @b{Ref@TeX{}} in great depth. All you need to know to use
91 @b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
92 Nutshell}). You can go back later to other parts of this document when
96 * Introduction:: Quick-Start information.
98 * Table of Contents:: A Tool to move around quickly.
99 * Labels and References:: Creating and referencing labels.
100 * Citations:: Creating Citations.
101 * Index Support:: Creating and Checking Index Entries.
102 * Viewing Cross-References:: Who references or cites what?
104 * RefTeXs Menu:: The Ref menu in the menubar.
105 * Key Bindings:: The default key bindings.
106 * Faces:: Fontification of RefTeX's buffers.
107 * Multifile Documents:: Document spread over many files.
108 * Language Support:: How to support other languages.
109 * Finding Files:: Included TeX files and BibTeX .bib files.
110 * AUCTeX:: Cooperation with AUCTeX.
111 * Optimizations:: When RefTeX is too slow.
112 * Problems and Work-Arounds:: First Aid.
113 * Imprint:: Author, Web-site, Thanks
115 * Commands:: Which are the available commands.
116 * Options:: How to extend and configure RefTeX.
117 * Keymaps and Hooks:: For customization.
118 * Changes:: A List of recent changes to RefTeX.
122 * Index:: The full index.
128 * Installation:: How to install and activate RefTeX.
129 * RefTeX in a Nutshell:: A brief summary and quick guide.
131 Labels and References
134 * Referencing Labels::
135 * Builtin Label Environments:: The environments RefTeX knows about.
136 * Defining Label Environments:: ... and environments it doesn't.
137 * Reference Info:: View the label corresponding to a \ref.
138 * xr (LaTeX package):: References to external documents.
139 * varioref (LaTeX package):: How to create \vref instead of \ref.
140 * fancyref (LaTeX package):: How to create \fref instead of \ref.
142 Defining Label Environments
144 * Theorem and Axiom:: Defined with @code{\newenvironment}.
145 * Quick Equation:: When a macro sets the label type.
146 * Figure Wrapper:: When a macro argument is a label.
147 * Adding Magic Words:: Other words for other languages.
148 * Using \eqref:: How to switch to this AMS-LaTeX macro.
149 * Non-Standard Environments:: Environments without \begin and \end
150 * Putting it Together:: How to combine many entries.
154 * Creating Citations:: How to create them.
155 * Citation Styles:: Natbib, Harvard, Chicago and Co.
156 * Citation Info:: View the corresponding database entry.
157 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
158 * Citations Outside LaTeX:: How to make citations in Emails etc.
159 * BibTeX Database Subsets:: Extract parts of a big database.
163 * Creating Index Entries:: Macros and completion of entries.
164 * The Index Phrases File:: A special file for global indexing.
165 * Displaying and Editing the Index:: The index editor.
166 * Builtin Index Macros:: The index macros RefTeX knows about.
167 * Defining Index Macros:: ... and macros it doesn't.
169 The Index Phrases File
171 * Collecting Phrases:: Collecting from document or external.
172 * Consistency Checks:: Check for duplicates etc.
173 * Global Indexing:: The interactive indexing process.
177 * AUCTeX-RefTeX Interface:: How both packages work together
178 * Style Files:: AUCTeX's style files can support RefTeX
179 * Bib-Cite:: Hypertext reading of a document
181 Options, Keymaps, Hooks
183 * Options (Table of Contents)::
184 * Options (Defining Label Environments)::
185 * Options (Creating Labels)::
186 * Options (Referencing Labels)::
187 * Options (Creating Citations)::
188 * Options (Index Support)::
189 * Options (Viewing Cross-References)::
190 * Options (Finding Files)::
191 * Options (Optimizations)::
192 * Options (Fontification)::
200 @node Introduction, Table of Contents, , Top
201 @chapter Introduction
204 @b{Ref@TeX{}} is a specialized package for support of labels,
205 references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
206 itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
207 and @code{\index}. Using these macros usually requires looking up
208 different parts of the document and searching through BibTeX database
209 files. @b{Ref@TeX{}} automates these time--consuming tasks almost
210 entirely. It also provides functions to display the structure of a
211 document and to move around in this structure quickly.
214 Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
215 in great depth. All you need to know to use @b{Ref@TeX{}} can be
216 summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
217 back later to other parts of this document when needed.
220 @xref{Imprint}, for information about who to contact for help, bug
221 reports or suggestions.
224 * Installation:: How to install and activate RefTeX.
225 * RefTeX in a Nutshell:: A brief summary and quick guide.
228 @node Installation, RefTeX in a Nutshell, , Introduction
229 @section Installation
232 @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version
233 20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x.
234 XEmacs 21.x users want to install the corresponding plug-in package
235 which is available from the @value{XEMACSFTP}. See the XEmacs 21.x
236 documentation on package installation for details.
238 Users of earlier Emacs distributions (including Emacs 19) can get a copy
239 of the @b{Ref@TeX{}} distribution from the maintainers web-page.
240 @xref{Imprint}, for more information.
243 @cindex Finding files
244 @cindex BibTeX database files, not found
245 @cindex TeX files, not found
246 @cindex @code{TEXINPUTS}, environment variable
247 @cindex @code{BIBINPUTS}, environment variable
249 @b{Ref@TeX{}} needs to access all files which are part of a multifile
250 document, and the BibTeX database files requested by the
251 @code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
252 require a search path, i.e. a list of directories to check. Normally
253 this list is stored in the environment variables @code{TEXINPUTS} and
254 @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
255 systems these variables do not contain the full search path. If
256 @b{Ref@TeX{}} does not work for you because it cannot find some files,
257 read @ref{Finding Files}.
259 @section Entering @b{Ref@TeX{}} Mode
261 @findex turn-on-reftex
263 @vindex LaTeX-mode-hook
264 @vindex latex-mode-hook
265 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
266 @kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
267 files, add the following lines to your @file{.emacs} file:
270 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
271 (add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
275 @node RefTeX in a Nutshell, , Installation, Introduction
276 @section @b{Ref@TeX{}} in a Nutshell
278 @cindex Getting Started
279 @cindex RefTeX in a Nutshell
280 @cindex Nutshell, RefTeX in a
284 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
285 a table of contents of the document. This buffer can display sections,
286 labels and index entries defined in the document. From the buffer, you
287 can jump quickly to every part of your document. Press @kbd{?} to get
291 @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
292 and to find the correct key for references quickly. It distinguishes
293 labels for different environments, knows about all standard
294 environments (and many others), and can be configured to recognize any
295 additional labeled environments you have defined yourself (variable
296 @code{reftex-label-alist}).
300 @b{Creating Labels}@*
301 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
302 @b{Ref@TeX{}} will either
305 derive a label from context (default for section labels)
307 prompt for a label string (default for figures and tables) or
309 insert a simple label made of a prefix and a number (all other
313 Which labels are created how is configurable with the variable
314 @code{reftex-insert-label-flags}.
317 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
318 (@code{reftex-reference}). This shows an outline of the document with
319 all labels of a certain type (figure, equation,...) and some label
320 context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
321 into the original buffer.
326 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
327 regular expression to search in current BibTeX database files (as
328 specified in the @code{\bibliography} command) and pull out a list of
329 matches for you to choose from. The list is @emph{formatted} and
330 sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
331 (see the variable @code{reftex-cite-format} if you want to insert
336 @b{Ref@TeX{}} helps to enter index entries. It also compiles all
337 entries into an alphabetically sorted @file{*Index*} buffer which you
338 can use to check and edit the entries. @b{Ref@TeX{}} knows about the
339 standard index macros and can be configured to recognize any additional
340 macros you have defined (@code{reftex-index-macros}). Multiple indices
345 @b{Creating Index Entries}@*
346 To index the current selection or the word at point, type @kbd{C-c /}
347 (@code{reftex-index-selection-or-word}). The default macro
348 @code{reftex-index-default-macro} will be used. For a more complex entry
349 type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
350 and enter the arguments with completion.
353 @b{The Index Phrases File (Delayed Indexing)}@*
354 Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
355 the current word or selection to a special @emph{index phrase file}.
356 @b{Ref@TeX{}} can later search the document for occurrences of these
357 phrases and let you interactively index the matches.
360 @b{Displaying and Editing the Index}@*
361 To display the compiled index in a special buffer, type @kbd{C-c >}
362 (@code{reftex-display-index}). From that buffer you can check and edit
367 @item @b{Viewing Cross-References}@*
368 When point is on the @var{key} argument of a cross--referencing macro
369 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
370 @code{\index}, and variations) or inside a BibTeX database entry, you
371 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
372 corresponding locations in the document and associated BibTeX database
374 When the enclosing macro is @code{\cite} or @code{\ref} and no other
375 message occupies the echo area, information about the citation or label
376 will automatically be displayed in the echo area.
379 @b{Multifile Documents}@*
380 Multifile Documents are fully supported. The included files must have a
381 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
382 master file. @b{Ref@TeX{}} provides cross-referencing information from
383 all parts of the document, and across document borders
387 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
388 order to find labels and other information. It does it automatically
389 once and updates its list internally when @code{reftex-label} and
390 @code{reftex-index} are used. To enforce reparsing, call any of the
391 commands described above with a raw @kbd{C-u} prefix, or press the
392 @kbd{r} key in the label selection buffer, the table of contents
393 buffer, or the index buffer.
396 @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
397 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
398 contains style files which trigger appropriate settings in
399 @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
400 additional customizations will be necessary.
403 @b{Useful Settings}@*
404 To integrate RefTeX with AUCTeX, use
406 (setq reftex-plug-into-AUCTeX t)
409 To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
410 customize the variables
412 @code{reftex-label-alist} @r{(for label macros/environments)}
413 @code{reftex-section-levels} @r{(for sectioning commands)}
414 @code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
415 @code{reftex-index-macros} @r{(for @code{\index}-like macros)}
416 @code{reftex-index-default-macro} @r{(to set the default macro)}
418 If you have a large number of macros defined, you may want to write
419 an AUCTeX style file to support them with both AUCTeX and
422 @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
423 until you have picked up the key bindings. For an overview of what you
424 can do in each of the different special buffers, press @kbd{?}. Read
425 the manual if you get stuck, of if you are curious what else might be
426 available. The first part of the manual explains in
427 a tutorial way how to use and customize @b{Ref@TeX{}}. The second
428 part is a command and variable reference.
431 @node Table of Contents, Labels and References, Introduction, Top
432 @chapter Table of Contents
433 @cindex @file{*toc*} buffer
434 @cindex Structure editing
435 @cindex Table of contents buffer
439 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
440 contents of the document. By default, this @file{*toc*} buffer shows
441 only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
442 can display all labels and index entries defined in the document as
445 With the cursor in any of the lines denoting a location in the
446 document, simple key strokes will display the corresponding part in
447 another window, jump to that location, or perform other actions.
450 Here is a list of special commands in the @file{*toc*} buffer. A
451 summary of this information is always available by pressing
456 @tablesubheading{General}
458 Display a summary of commands.
463 @tablesubheading{Moving around}
465 Goto next entry in the table of context.
468 Goto previous entry in the table of context.
471 Goto next section heading. Useful when many labels and index entries
472 separate section headings.
475 Goto previous section heading.
478 Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps
481 @tablesubheading{Access to document locations}
483 Show the corresponding location in another window. This command does
484 @emph{not} select that other window.
487 Goto the location in another window.
490 Go to the location and hide the @file{*toc*} buffer. This will restore
491 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
495 @vindex reftex-highlight-selection
496 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
497 See also variable @code{reftex-highlight-selection}, @ref{Options
501 @vindex reftex-toc-follow-mode
502 @vindex reftex-revisit-to-follow
503 Toggle follow mode. When follow mode is active, the other window will
504 always show the location corresponding to the line at point in the
505 @file{*toc*} buffer. This is similar to pressing @key{SPC} after each
506 cursor motion. The default for this flag can be set with the variable
507 @code{reftex-toc-follow-mode}. Note that only context in files already
508 visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
509 mode. See, however, the variable
510 @code{reftex-revisit-to-follow}.
513 Show calling point in another window. This is the point from where
514 @code{reftex-toc} was last called.
517 @tablesubheading{Promotion and Demotion}
520 Promote the current section. This will convert @code{\section} to
521 @code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
522 an active region, all sections in the region will be promoted, including
523 the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh
524 document scan before executing this command - if necessary, it will
525 automatically do this scan and ask the user to repeat the promotion
529 Demote the current section. This is the opposite of promotion. It will
530 convert @code{\chapter} to @code{\section} etc. If there is an active
531 region, all sections in the region will be demoted, including the one at
535 Rename the label at point. While generally not recommended, this can be
536 useful when a package like @file{fancyref} is used where the label
537 prefix determines the wording of a reference. After a
538 promotion/demotion it may be necessary to change a few labels from
539 @samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be
540 used to do this - it launches a query replace to rename the definition
541 and all references of a label.
543 @tablesubheading{Exiting}
545 Hide the @file{*toc*} buffer, return to the position where
546 @code{reftex-toc} was last called.
549 Kill the @file{*toc*} buffer, return to the position where
550 @code{reftex-toc} was last called.
553 Switch to the @file{*Index*} buffer of this document. With prefix
554 @samp{2}, restrict the index to the section at point in the @file{*toc*}
557 @tablesubheading{Controlling what gets displayed}
560 @vindex reftex-toc-max-level
561 Change the maximum level of toc entries displayed in the @file{*toc*}
562 buffer. Without prefix arg, all levels will be included. With prefix
563 arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
564 @var{arg} (3 in this case). Chapters are level 1, sections are level 2.
565 The mode line @samp{T<>} indicator shows the current value. The default
566 depth can be configured with the variable
567 @code{reftex-toc-max-level}.
570 @vindex reftex-toc-include-file-boundaries
571 Toggle the display of the file borders of a multifile document in the
572 @file{*toc*} buffer. The default for this flag can be set with the
573 variable @code{reftex-toc-include-file-boundaries}.
576 @vindex reftex-toc-include-labels
577 Toggle the display of labels in the @file{*toc*} buffer. The default
578 for this flag can be set with the variable
579 @code{reftex-toc-include-labels}. When called with a prefix argument,
580 @b{Ref@TeX{}} will prompt for a label type and include only labels of
581 the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
582 indicator shows which labels are included.
585 @vindex reftex-toc-include-index-entries
586 Toggle the display of index entries in the @file{*toc*} buffer. The
587 default for this flag can be set with the variable
588 @code{reftex-toc-include-index-entries}. When called with a prefix
589 argument, @b{Ref@TeX{}} will prompt for a specific index and include
590 only entries in the selected index in the @file{*toc*} buffer. The mode
591 line @samp{I<>} indicator shows which index is used.
594 @vindex reftex-toc-include-context
595 Toggle the display of label and index context in the @file{*toc*}
596 buffer. The default for this flag can be set with the variable
597 @code{reftex-toc-include-context}.
599 @tablesubheading{Updating the buffer}
602 Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
606 @vindex reftex-enable-partial-scans
607 Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
608 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
609 location is defined in, not the entire document.
612 Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
616 Switch to the @file{*toc*} buffer of an external document. When the
617 current document is using the @code{xr} package (@pxref{xr (LaTeX
618 package)}), @b{Ref@TeX{}} will switch to one of the external
622 @tablesubheading{Automatic recentering}
625 Toggle the display of a dedicated frame displaying just the @file{*toc*}
626 buffer. Follow mode and visiting locations will not work that frame,
627 but automatic recentering will make this frame always show your current
628 editing location in the document (see below).
631 Toggle the automatic recentering of the @file{*toc*} buffer. When this
632 option is on, moving around in the document will cause the @file{*toc*}
633 to always highlight the current section. By default, this option is
634 active while the dedicated @file{*TOC*} frame exists. See also the
635 variable @code{reftex-auto-recenter-toc}.
639 @vindex reftex-toc-map
640 In order to define additional commands for the @file{*toc*} buffer, the
641 keymap @code{reftex-toc-map} may be used.
643 @findex reftex-toc-recenter
644 @vindex reftex-auto-recenter-toc
645 @vindex reftex-idle-time
646 @cindex @file{*toc*} buffer, recentering
647 @cindex Table of contents buffer, recentering
649 If you call @code{reftex-toc} while the @file{*toc*} buffer already
650 exists, the cursor will immediately jump to the right place, i.e. the
651 section from which @code{reftex-toc} was called will be highlighted.
652 The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
653 the @file{*toc*} buffer and highlight the correct line without actually
654 selecting the @file{*toc*} window. This can be useful to quickly find
655 out where in the document you currently are. You can also automate this
656 by asking RefTeX to keep track of your current editing position in the
657 TOC. The TOC window will then be updated whenever you stop typing for
658 more than @code{reftex-idle-time} seconds. By default this works only
659 with the dedicated @file{*TOC*} frame. But you can also force automatic
660 recentering of the TOC window on the current frame with
662 (setq reftex-auto-recenter-toc t)
666 @cindex Sectioning commands
667 @cindex KOMA-Script, LaTeX classes
668 @cindex LaTeX classes, KOMA-Script
669 @cindex TOC entries for environments
670 @vindex reftex-section-levels
671 The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
672 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
673 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
674 Additional macros can be configured with the variable
675 @code{reftex-section-levels}. It is also possible to add certain LaTeX
676 environments to the table of contents. This is probably only useful for
677 theorem-like environments. @xref{Defining Label Environments}, for an
680 @node Labels and References, Citations, Table of Contents, Top
681 @chapter Labels and References
682 @cindex Labels in LaTeX
683 @cindex References in LaTeX
684 @cindex Label category
685 @cindex Label environment
686 @cindex @code{\label}
688 LaTeX provides a powerful mechanism to deal with cross--references in a
689 document. When writing a document, any part of it can be marked with a
690 label, like @samp{\label@{mark@}}. LaTeX records the current value of a
691 certain counter when a label is defined. Later references to this label
692 (like @samp{\ref@{mark@}}) will produce the recorded value of the
695 Labels can be used to mark sections, figures, tables, equations,
696 footnotes, items in enumerate lists etc. LaTeX is context sensitive in
697 doing this: A label defined in a figure environment automatically
698 records the figure counter, not the section counter.
700 Several different environments can share a common counter and therefore
701 a common label category. E.g. labels in both @code{equation} and
702 @code{eqnarray} environments record the value of the same counter - the
707 * Referencing Labels::
708 * Builtin Label Environments:: The environments RefTeX knows about.
709 * Defining Label Environments:: ... and environments it doesn't.
710 * Reference Info:: View the label corresponding to a \ref.
711 * xr (LaTeX package):: References to external documents.
712 * varioref (LaTeX package):: How to create \vref instead of \ref.
713 * fancyref (LaTeX package):: How to create \fref instead of \ref.
716 @node Creating Labels, Referencing Labels, , Labels and References
717 @section Creating Labels
718 @cindex Creating labels
719 @cindex Labels, creating
720 @cindex Labels, deriving from context
724 In order to create a label in a LaTeX document, press @kbd{C-c (}
725 (@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
726 and will figure out the environment it currently is in and adapt the
727 label to that environment. A label usually consists of a short prefix
728 indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
729 3 different modes to create this mark.
733 @vindex reftex-translate-to-ascii-function
734 @vindex reftex-derive-label-parameters
735 @vindex reftex-label-illegal-re
736 @vindex reftex-abbrev-parameters
737 A label can be derived from context. This means, @b{Ref@TeX{}} takes
738 the context of the label definition and constructs a label from
739 that@footnote{Note that the context may contain constructs which are
740 invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from
741 accented Latin-1 characters and remove everything else which is not
742 valid in labels. This mechanism is safe, but may not be satisfactory
743 for non-western languages. Check the following variables if you need to
744 change things: @code{reftex-translate-to-ascii-function},
745 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
746 @code{reftex-abbrev-parameters}.}. This works best for section labels,
747 where the section heading is used to construct a label. In fact,
748 @b{Ref@TeX{}}'s default settings use this method only for section
749 labels. You will be asked to confirm the derived label, or edit
753 We may also use a simple unique number to identify a label. This is
754 mostly useful for labels where it is difficult to come up with a very
755 good descriptive name. @b{Ref@TeX{}}'s default settings use this method
756 for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
757 tends to write documents with many equations and finds it impossible
758 to come up with good names for each of them. These simple labels are
759 inserted without query, and are therefore very fast. Good descriptive
760 names are not really necessary as @b{Ref@TeX{}} will provide context to
761 reference a label (@pxref{Referencing Labels}).
764 The third method is to ask the user for a label. This is most
765 useful for things which are easy to describe briefly and do not turn up
766 too frequently in a document. @b{Ref@TeX{}} uses this for figures and
767 tables. Of course, one can enter the label directly by typing the full
768 @samp{\label@{mark@}}. The advantage of using @code{reftex-label}
769 anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
770 It will then not be necessary to rescan the document in order to access
774 @vindex reftex-insert-label-flags
775 If you want to change the way certain labels are created, check out the
776 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
779 If you are using AUCTeX to write your LaTeX documents, you can
780 set it up to delegate the creation of labels to
781 @b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
783 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
784 @section Referencing Labels
785 @cindex Referencing labels
786 @cindex Labels, referencing
787 @cindex Selection buffer, labels
788 @cindex Selection process
791 @findex reftex-reference
793 @vindex reftex-trust-label-prefix
794 @b{Ref@TeX{}} scans the document in order to find all labels. To make
795 referencing labels easier, it assigns to each label a category, the
796 @emph{label type} (for example section, table, figure, equation, etc.).
797 In order to determine the label type, RefTeX parses around each label
798 to see in what kind of environments it is located. You can speed up
799 the parsing by using type-specific prefixes for labels and configuring
800 the variable @code{reftex-trust-label-prefix}.
802 Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c
803 )} in order to reference a label (reftex-reference). This will start a
804 selection process and finally insert the complete @samp{\ref@{label@}}
807 First, @b{Ref@TeX{}} will determine the label category which is required.
808 Often that can be figured out from context. For example, if you
809 write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
810 that an equation label is going to be referenced. If it cannot figure
811 out what label category is needed, it will query for one.
813 You will then be presented with a label selection menu. This is a
814 special buffer which contains an outline of the document along with all
815 labels of the given label category. In addition, next to the label
816 there will be one line of context of the label definition, which is some
817 text in the buffer near the label definition. Usually this is
818 sufficient to identify the label. If you are unsure about a certain
819 label, pressing @key{SPC} will show the label definition point in
822 In order to reference a label, move to cursor to the correct label and
823 press @key{RET}. You can also reference several labels with a single
824 call to @code{reftex-reference} by marking entries with the @kbd{m}
828 Here is a list of special commands in the selection buffer. A summary
829 of this information is always available from the selection process by
835 @tablesubheading{General}
837 Show a summary of available commands.
842 @tablesubheading{Moving around}
847 Go to previous label.
850 Jump back to the position where you last left the selection buffer.
851 Normally this should get you back to the last referenced label.
854 Goto next section heading.
857 Goto previous section heading.
860 Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to
863 @tablesubheading{Displaying Context}
865 Show the surroundings of the definition of the current label in another
866 window. See also the @kbd{f} key.
869 @vindex reftex-revisit-to-follow
870 Toggle follow mode. When follow mode is active, the other window will
871 always display the full context of the current label. This is similar
872 to pressing @key{SPC} after each cursor motion. Note that only context
873 in files already visited is shown. @b{RefTeX} will not visit a file
874 just for follow mode. See, however, the variable
875 @code{reftex-revisit-to-follow}.
878 Show insertion point in another window. This is the point from where you
879 called @code{reftex-reference}.
881 @tablesubheading{Selecting a label and creating the reference}
883 Insert a reference to the label at point into the buffer from which the
884 selection process was started. When entries have been marked, @key{RET}
885 references all marked labels.
888 @vindex reftex-highlight-selection
889 Clicking with mouse button 2 on a label will accept it like @key{RET}
890 would. See also variable @code{reftex-highlight-selection}, @ref{Options
893 @vindex reftex-multiref-punctuation
895 Mark the current entry. When several entries have been marked, pressing
896 @kbd{RET} will accept all of them and place them into several
897 @code{\ref} macros. The special markers @samp{,-+} also store a
898 separator to be inserted before the corresponding reference. So marking
899 six entries with the keys @samp{m , , - , +} will give a reference list
900 like this (see the variable @code{reftex-multiref-punctuation})
902 In eqs. (1), (2), (3)--(4), (5) and (6)
906 Unmark a marked entry.
908 @c FIXME: Do we need `A' as well for consistency?
909 @cindex LaTeX packages, @code{saferef}
910 @cindex @code{saferef}, LaTeX package
912 Accept the marked entries and put all labels as a comma-separated list
913 into one @emph{single} @code{\ref} macro. Some packages like
914 @file{saferef.sty} support multiple references in this way.
917 Use the last referenced label(s) again. This is equivalent to moving to
918 that label and pressing @key{RET}.
921 Enter a label with completion. This may also be a label which does not
922 yet exist in the document.
925 @cindex @code{varioref}, LaTeX package
927 @cindex LaTeX packages, @code{varioref}
928 Toggle between @code{\ref} and @code{\vref} macro for references. The
929 @code{\vref} macro is defined in the @code{varioref} LaTeX package.
930 With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
931 macro. The current state of this flag is displayed by the @samp{S<>}
932 indicator in the mode line of the selection buffer.
935 @cindex @code{fancyref}, LaTeX package
938 @cindex LaTeX packages, @code{fancyref}
939 Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The
940 @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
941 LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a
942 @code{\fref} or @code{\Fref} macro. The current state of this flag is
943 displayed by the @samp{S<>} indicator in the mode line of the
946 @tablesubheading{Exiting}
949 Exit the selection process without inserting any reference into the
952 @tablesubheading{Controlling what gets displayed}
953 @vindex reftex-label-menu-flags
954 The defaults for the following flags can be configured with the variable
955 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
958 Toggle the display of the one-line label definition context in the
962 Toggle the display of the file borders of a multifile document in the
966 Toggle the display of the table of contents in the selection buffer.
967 With prefix @var{arg}, change the maximum level of toc entries displayed
968 to @var{arg}. Chapters are level 1, section are level 2.
971 Toggle the display of a label counter in the selection buffer.
974 Toggle the display of labels hidden in comments in the selection
975 buffers. Sometimes, you may have commented out parts of your document.
976 If these parts contain label definitions, @b{Ref@TeX{}} can still display
977 and reference these labels.
979 @tablesubheading{Updating the buffer}
981 Update the menu. This will rebuilt the menu from the internal label
982 list, but not reparse the document (see @kbd{r}).
985 @vindex reftex-enable-partial-scans
986 Reparse the document to update the information on all labels and rebuild
987 the menu. If the variable @code{reftex-enable-partial-scans} is
988 non-@code{nil} and your document is a multifile document, this will
989 reparse only a part of the document (the file in which the label at
993 Reparse the @emph{entire} document.
996 Switch the label category. After prompting for another label category,
997 a menu for that category will be shown.
1000 Reference a label from an external document. With the LaTeX package
1001 @code{xr} it is possible to reference labels defined in another
1002 document. This key will switch to the label menu of an external
1003 document and let you select a label from there (@pxref{xr (LaTeX
1008 @vindex reftex-select-label-map
1009 In order to define additional commands for the selection process, the
1010 keymap @code{reftex-select-label-map} may be used.
1012 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
1013 @section Builtin Label Environments
1014 @cindex Builtin label environments
1015 @cindex Label environments, builtin
1016 @cindex Environments, builtin
1017 @vindex reftex-label-alist
1018 @vindex reftex-label-alist-builtin
1020 @b{Ref@TeX{}} needs to be aware of the environments which can be referenced
1021 with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}
1022 recognizes all labeled environments and macros discussed in @cite{The
1023 LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
1028 @cindex @code{figure}, LaTeX environment
1029 @cindex @code{figure*}, LaTeX environment
1030 @cindex @code{table}, LaTeX environment
1031 @cindex @code{table*}, LaTeX environment
1032 @cindex @code{equation}, LaTeX environment
1033 @cindex @code{eqnarray}, LaTeX environment
1034 @cindex @code{enumerate}, LaTeX environment
1035 @cindex @code{\footnote}, LaTeX macro
1036 @cindex LaTeX macro @code{footnote}
1038 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
1039 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
1040 the LaTeX core stuff)
1043 @cindex @code{amsmath}, LaTeX package
1044 @cindex LaTeX packages, @code{amsmath}
1045 @cindex @code{align}, AMS-LaTeX environment
1046 @cindex @code{gather}, AMS-LaTeX environment
1047 @cindex @code{multline}, AMS-LaTeX environment
1048 @cindex @code{flalign}, AMS-LaTeX environment
1049 @cindex @code{alignat}, AMS-LaTeX environment
1050 @cindex @code{xalignat}, AMS-LaTeX environment
1051 @cindex @code{xxalignat}, AMS-LaTeX environment
1052 @cindex @code{subequations}, AMS-LaTeX environment
1053 @code{align}, @code{gather}, @code{multline}, @code{flalign},
1054 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
1055 (from AMS-LaTeX's @file{amsmath.sty} package)
1057 @cindex @code{endnote}, LaTeX package
1058 @cindex LaTeX packages, @code{endnote}
1059 @cindex @code{\endnote}, LaTeX macro
1060 the @code{\endnote} macro (from @file{endnotes.sty})
1062 @cindex @code{fancybox}, LaTeX package
1063 @cindex LaTeX packages, @code{fancybox}
1064 @cindex @code{Beqnarray}, LaTeX environment
1065 @code{Beqnarray} (@file{fancybox.sty})
1067 @cindex @code{floatfig}, LaTeX package
1068 @cindex LaTeX packages, @code{floatfig}
1069 @cindex @code{floatingfig}, LaTeX environment
1070 @code{floatingfig} (@file{floatfig.sty})
1072 @cindex @code{longtable}, LaTeX package
1073 @cindex LaTeX packages, @code{longtable}
1074 @cindex @code{longtable}, LaTeX environment
1075 @code{longtable} (@file{longtable.sty})
1077 @cindex @code{picinpar}, LaTeX package
1078 @cindex LaTeX packages, @code{picinpar}
1079 @cindex @code{figwindow}, LaTeX environment
1080 @cindex @code{tabwindow}, LaTeX environment
1081 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1083 @cindex @code{sidecap}, LaTeX package
1084 @cindex LaTeX packages, @code{sidecap}
1085 @cindex @code{SCfigure}, LaTeX environment
1086 @cindex @code{SCtable}, LaTeX environment
1087 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1089 @cindex @code{rotating}, LaTeX package
1090 @cindex LaTeX packages, @code{rotating}
1091 @cindex @code{sidewaysfigure}, LaTeX environment
1092 @cindex @code{sidewaystable}, LaTeX environment
1093 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1095 @cindex @code{subfig}, LaTeX package
1096 @cindex LaTeX packages, @code{subfigure}
1097 @cindex @code{subfigure}, LaTeX environment
1098 @cindex @code{subfigure*}, LaTeX environment
1099 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1100 (@file{subfigure.sty})
1102 @cindex @code{supertab}, LaTeX package
1103 @cindex LaTeX packages, @code{supertab}
1104 @cindex @code{supertabular}, LaTeX environment
1105 @code{supertabular} (@file{supertab.sty})
1107 @cindex @code{wrapfig}, LaTeX package
1108 @cindex LaTeX packages, @code{wrapfig}
1109 @cindex @code{wrapfigure}, LaTeX environment
1110 @code{wrapfigure} (@file{wrapfig.sty})
1113 If you want to use other labeled environments, defined with
1114 @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
1115 them (@pxref{Defining Label Environments}).
1117 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1118 @section Defining Label Environments
1119 @cindex Label environments, defining
1121 @vindex reftex-label-alist
1122 @b{Ref@TeX{}} can be configured to recognize additional labeled
1123 environments and macros. This is done with the variable
1124 @code{reftex-label-alist} (@pxref{Options (Defining Label
1125 Environments)}). If you are not familiar with Lisp, you can use the
1126 @code{custom} library to configure this rather complex variable. To do
1130 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1133 @vindex reftex-label-alist-builtin
1134 Here we will discuss a few examples, in order to make things clearer.
1135 It can also be instructive to look at the constant
1136 @code{reftex-label-alist-builtin} which contains the entries for
1137 all the builtin environments and macros (@pxref{Builtin Label
1141 * Theorem and Axiom:: Defined with @code{\newenvironment}.
1142 * Quick Equation:: When a macro sets the label type.
1143 * Figure Wrapper:: When a macro argument is a label.
1144 * Adding Magic Words:: Other words for other languages.
1145 * Using \eqref:: How to switch to this AMS-LaTeX macro.
1146 * Non-Standard Environments:: Environments without \begin and \end
1147 * Putting it Together:: How to combine many entries.
1150 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1151 @subsection Theorem and Axiom Environments
1152 @cindex @code{theorem}, newtheorem
1153 @cindex @code{axiom}, newtheorem
1154 @cindex @code{\newtheorem}
1156 Suppose you are using @code{\newtheorem} in LaTeX in order to define two
1157 new environments, @code{theorem} and @code{axiom}
1160 \newtheorem@{axiom@}@{Axiom@}
1161 \newtheorem@{theorem@}@{Theorem@}
1165 to be used like this:
1174 So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
1175 labeled environments which define their own label categories. We can
1176 either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
1177 library. With Lisp it would look like this
1180 (setq reftex-label-alist
1181 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1182 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3)))
1185 The type indicator characters @code{?a} and @code{?h} are used for
1186 prompts when @b{Ref@TeX{}} queries for a label type. @code{?h}
1187 was chosen for @code{theorem} since @code{?t} is already taken by
1188 @code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
1189 @code{?i}, @code{?n} are already used for standard environments.
1192 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1193 @samp{thr:}, respectively. @xref{AUCTeX}, for information on how
1194 AUCTeX can use RefTeX to automatically create labels when a new environment
1195 is inserted into a buffer. Additionally, the following needs to be
1196 added to one's .emacs file before AUCTeX will automatically create
1197 labels for the new environments.
1200 (add-hook 'LaTeX-mode-hook
1202 (LaTeX-add-environments
1203 '("axiom" LaTeX-env-label)
1204 '("theorem" LaTeX-env-label))))
1209 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1210 references to these labels.
1213 The next item indicates how to grab context of the label definition.
1216 @code{t} means to get it from a default location (from the beginning of
1217 a @code{\macro} or after the @code{\begin} statement). @code{t} is
1218 @emph{not} a good choice for eqnarray and similar environments.
1220 @code{nil} means to use the text right after the label definition.
1222 For more complex ways of getting context, see the variable
1223 @code{reftex-label-alist} (@ref{Options (Defining Label
1227 The following list of strings is used to guess the correct label type
1228 from the word before point when creating a reference. E.g. if you
1229 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1230 @b{Ref@TeX{}} will know that you are looking for a theorem label and
1231 restrict the menu to only these labels without even asking.
1233 The final item in each entry is the level at which the environment
1234 should produce entries in the table of context buffer. If the number is
1235 positive, the environment will produce numbered entries (like
1236 @code{\section}), if it is negative the entries will be unnumbered (like
1237 @code{\section*}). Use this only for environments which structure the
1238 document similar to sectioning commands. For everything else, omit the
1241 To do the same configuration with @code{customize}, you need to click on
1242 the @code{[INS]} button twice to create two templates and fill them in
1246 Reftex Label Alist: [Hide]
1247 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1248 Environment or \macro : [Value Menu] String: axiom
1249 Type specification : [Value Menu] Char : a
1250 Label prefix string : [Value Menu] String: ax:
1251 Label reference format: [Value Menu] String: ~\ref@{%s@}
1252 Context method : [Value Menu] After label
1254 [INS] [DEL] String: axiom
1255 [INS] [DEL] String: ax.
1257 [X] Make TOC entry : [Value Menu] Level: -2
1258 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1259 Environment or \macro : [Value Menu] String: theorem
1260 Type specification : [Value Menu] Char : h
1261 Label prefix string : [Value Menu] String: thr:
1262 Label reference format: [Value Menu] String: ~\ref@{%s@}
1263 Context method : [Value Menu] Default position
1265 [INS] [DEL] String: theorem
1266 [INS] [DEL] String: theor.
1267 [INS] [DEL] String: th.
1269 [X] Make TOC entry : [Value Menu] Level: -3
1272 @vindex reftex-insert-label-flags
1273 @vindex reftex-label-menu-flags
1274 Depending on how you would like the label insertion and selection for
1275 the new environments to work, you might want to add the letters @samp{a}
1276 and @samp{h} to some of the flags in the variables
1277 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1278 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1282 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1283 @subsection Quick Equation Macro
1284 @cindex Quick equation macro
1285 @cindex Macros as environment wrappers
1287 Suppose you would like to have a macro for quick equations. It
1288 could be defined like this:
1291 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1298 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1301 We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
1302 @code{\quickeq} is an equation label. Here is how to do this with lisp:
1305 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1308 The first element in this list is now the macro with empty braces as an
1309 @emph{image} of the macro arguments. @code{?e} indicates that this is
1310 an equation label, the different @code{nil} elements indicate to use the
1311 default values for equations. The @samp{1} as the fifth element
1312 indicates that the context of the label definition should be the 1st
1313 argument of the macro.
1315 Here is again how this would look in the customization buffer:
1318 Reftex Label Alist: [Hide]
1319 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1320 Environment or \macro : [Value Menu] String: \quickeq@{@}
1321 Type specification : [Value Menu] Char : e
1322 Label prefix string : [Value Menu] Default
1323 Label reference format: [Value Menu] Default
1324 Context method : [Value Menu] Macro arg nr: 1
1327 [ ] Make TOC entry : [Value Menu] No entry
1330 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1331 @subsection Figure Wrapping Macro
1332 @cindex Macros as environment wrappers
1333 @cindex Figure wrapping macro
1335 Suppose you want to make figures not directly with the figure
1336 environment, but with a macro like
1339 \newcommand@{\myfig@}[5][tbp]@{%
1340 \begin@{figure@}[#1]
1348 which would be called like
1351 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1354 Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
1355 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1359 (setq reftex-label-alist
1360 '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1363 The empty pairs of brackets indicate the different arguments of the
1364 @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
1365 indicates that this is a figure label which will be listed together with
1366 labels from normal figure environments. The @code{nil} entries for
1367 prefix and reference format mean to use the defaults for figure labels.
1368 The @samp{3} for the context method means to grab the 3rd macro argument
1371 As a side effect of this configuration, @code{reftex-label} will now
1372 insert the required naked label (without the @code{\label} macro) when
1373 point is directly after the opening parenthesis of a @code{\myfig} macro
1376 Again, here the configuration in the customization buffer:
1379 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1380 Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1381 Type specification : [Value Menu] Char : f
1382 Label prefix string : [Value Menu] Default
1383 Label reference format: [Value Menu] Default
1384 Context method : [Value Menu] Macro arg nr: 3
1387 [ ] Make TOC entry : [Value Menu] No entry
1390 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1391 @subsection Adding Magic Words
1393 @cindex German magic words
1394 @cindex Label category
1396 Sometimes you don't want to define a new label environment or macro, but
1397 just change the information associated with a label category. Maybe you
1398 want to add some magic words, for another language. Changing only the
1399 information associated with a label category is done by giving
1400 @code{nil} for the environment name and then specify the items you want
1401 to define. Here is an example which adds German magic words to all
1402 predefined label categories.
1405 (setq reftex-label-alist
1406 '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1407 (nil ?e nil nil nil ("Gleichung" "Gl."))
1408 (nil ?t nil nil nil ("Tabelle"))
1409 (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1410 (nil ?n nil nil nil ("Anmerkung" "Anm."))
1411 (nil ?i nil nil nil ("Punkt"))))
1414 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1415 @subsection Using @code{\eqref}
1416 @cindex @code{\eqref}, AMS-LaTeX macro
1418 @cindex Label category
1420 Another case where one only wants to change the information associated
1421 with the label category is to change the macro which is used for
1422 referencing the label. When working with the AMS-LaTeX stuff, you might
1423 prefer @code{\eqref} for doing equation references. Here is how to
1427 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1430 @b{Ref@TeX{}} has also a predefined symbol for this special purpose. The
1431 following is equivalent to the line above.
1434 (setq reftex-label-alist '(AMSTeX))
1437 Note that this is automatically done by the @file{amsmath.el} style file
1438 of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
1439 this configuration will not be necessary.
1441 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1442 @subsection Non-standard Environments
1443 @cindex Non-standard environments
1444 @cindex Environments without @code{\begin}
1445 @cindex Special parser functions
1446 @cindex Parser functions, for special environments
1448 Some LaTeX packages define environment-like structures without using the
1449 standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse
1450 these directly, but you can write your own special-purpose parser and
1451 use it instead of the name of an environment in an entry for
1452 @code{reftex-label-alist}. The function should check if point is
1453 currently in the special environment it was written to detect. If so,
1454 it must return a buffer position indicating the start of this
1455 environment. The return value must be @code{nil} on failure to detect
1456 the environment. The function is called with one argument @var{bound}.
1457 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1458 which should be observed. We will discuss two examples.
1460 @cindex LaTeX commands, abbreviated
1462 Some people define abbreviations for
1463 environments, like @code{\be} for @code{\begin@{equation@}}, and
1464 @code{\ee} for @code{\end@{equation@}}. The parser function would have
1465 to search backward for these macros. When the first match is
1466 @code{\ee}, point is not in this environment. When the first match is
1467 @code{\be}, point is in this environment and the function must return
1468 the beginning of the match. To avoid scanning too far, we can also look
1469 for empty lines which cannot occur inside an equation environment.
1473 ;; Setup entry in reftex-label-alist, using all defaults for equations
1474 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1476 (defun detect-be-ee (bound)
1477 ;; Search backward for the macros or an empty line
1478 (if (re-search-backward
1479 "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1480 (if (match-beginning 2)
1481 (match-beginning 2) ; Return start of environment
1482 nil) ; Return nil because env is closed
1483 nil)) ; Return nil for not found
1486 @cindex @code{linguex}, LaTeX package
1487 @cindex LaTeX packages, @code{linguex}
1488 A more complex example is the @file{linguex.sty} package which defines
1489 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1490 terminated by @samp{\z.} or by an empty line.
1493 \ex. \label@{ex:12@} Some text in an exotic language ...
1494 \a. \label@{ex:13@} more stuff
1495 \b. \label@{ex:14@} still more stuff
1496 \a. List on a deeper level
1498 \b. and the third one
1500 \b. Third item on this level.
1502 ... text after the empty line terminating all lists
1505 The difficulty is that the @samp{\a.} lists can nest and that an empty
1506 line terminates all list levels in one go. So we have to count nesting
1507 levels between @samp{\a.} and @samp{\z.}. Here is the implementation
1511 (setq reftex-label-alist
1512 '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1514 (defun detect-linguex (bound)
1518 ;; Search backward for all possible delimiters
1520 (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1521 "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1523 ;; Check which delimiter was matched.
1525 ((match-beginning 1)
1526 ;; empty line terminates all - return nil
1528 ((match-beginning 2)
1529 ;; \z. terminates one list level - decrease nesting count
1531 ((match-beginning 3)
1532 ;; \ex. : return match unless there was a \z. on this level
1533 (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1534 ((match-beginning 4)
1535 ;; \a. : return match when on level 0, otherwise
1536 ;; increment nesting count
1538 (throw 'exit (match-beginning 4))
1542 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1543 @subsection Putting it all together
1545 When you have to put several entries into @code{reftex-label-alist}, just
1546 put them after each other in a list, or create that many templates in
1547 the customization buffer. Here is a lisp example which uses several of
1548 the entries described above:
1551 (setq reftex-label-alist
1552 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1553 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3)
1554 ("\\quickeq@{@}" ?e nil nil 1 nil)
1556 ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1557 (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1560 @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
1561 @section Reference Info
1562 @findex reftex-view-crossref
1563 @findex reftex-mouse-view-crossref
1564 @cindex Cross-references, displaying
1565 @cindex Reference info
1566 @cindex Displaying cross-references
1567 @cindex Viewing cross-references
1571 When point is idle for more than @code{reftex-idle-time} seconds on the
1572 argument of a @code{\ref} macro, the echo area will display some
1573 information about the label referenced there. Note that the information
1574 is only displayed if the echo area is not occupied by a different
1577 @b{Ref@TeX{}} can also display the label definition corresponding to a
1578 @code{\ref} macro, or all reference locations corresponding to a
1579 @code{\label} macro. @xref{Viewing Cross-References}, for more
1582 @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
1583 @section @code{xr}: Cross-Document References
1584 @cindex @code{xr}, LaTeX package
1585 @cindex LaTeX packages, @code{xr}
1586 @cindex @code{\externaldocument}
1587 @cindex External documents
1588 @cindex References to external documents
1589 @cindex Cross-document references
1591 The LaTeX package @code{xr} makes it possible to create references to
1592 labels defined in external documents. The preamble of a document using
1593 @code{xr} will contain something like this:
1597 \externaldocument[V1-]@{volume1@}
1598 \externaldocument[V3-]@{volume3@}
1602 and we can make references to any labels defined in these
1603 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1606 @b{Ref@TeX{}} can be used to create such references as well. Start the
1607 referencing process normally, by pressing @kbd{C-c )}. Select a label
1608 type if necessary. When you see the label selection buffer, pressing
1609 @kbd{x} will switch to the label selection buffer of one of the external
1610 documents. You may then select a label as before and @b{Ref@TeX{}} will
1611 insert it along with the required prefix.
1613 For this kind of inter-document cross-references, saving of parsing
1614 information and the use of multiple selection buffers can mean a large
1615 speed-up (@pxref{Optimizations}).
1617 @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
1618 @section @code{varioref}: Variable Page References
1619 @cindex @code{varioref}, LaTeX package
1620 @cindex @code{\vref}
1621 @cindex LaTeX packages, @code{varioref}
1622 @vindex reftex-vref-is-default
1623 @code{varioref} is a frequently used LaTeX package to create
1624 cross--references with page information. When you want to make a
1625 reference with the @code{\vref} macro, just press the @kbd{v} key in the
1626 selection buffer to toggle between @code{\ref} and @code{\vref}
1627 (@pxref{Referencing Labels}). The mode line of the selection buffer
1628 shows the current status of this switch. If you find that you almost
1629 always use @code{\vref}, you may want to make it the default by
1630 customizing the variable @code{reftex-vref-is-default}. If this
1631 toggling seems too inconvenient, you can also use the command
1632 @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
1633 Or use AUCTeX to create your macros (@pxref{AUCTeX}).
1635 @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
1636 @section @code{fancyref}: Fancy Cross References
1637 @cindex @code{fancyref}, LaTeX package
1638 @cindex @code{\fref}
1639 @cindex @code{\Fref}
1640 @cindex LaTeX packages, @code{fancyref}
1641 @vindex reftex-fref-is-default
1642 @code{fancyref} is a LaTeX package where a macro call like
1643 @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
1644 the referenced counter but also the complete text around it, like
1645 @samp{Figure 3 on the preceding page}. In order to make it work you
1646 need to use label prefixes like @samp{fig:} consistently - something
1647 @b{Ref@TeX{}} does automatically. When you want to make a reference
1648 with the @code{\fref} macro, just press the @kbd{V} key in the selection
1649 buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
1650 (@pxref{Referencing Labels}). The mode line of the selection buffer
1651 shows the current status of this switch. If this cycling seems
1652 inconvenient, you can also use the commands @code{reftex-fancyref-fref}
1653 and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
1654 f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros
1657 @node Citations, Index Support, Labels and References, Top
1660 @cindex @code{\cite}
1662 Citations in LaTeX are done with the @code{\cite} macro or variations of
1663 it. The argument of the macro is a citation key which identifies an
1664 article or book in either a BibTeX database file or in an explicit
1665 @code{thebibliography} environment in the document. @b{Ref@TeX{}}'s
1666 support for citations helps to select the correct key quickly.
1669 * Creating Citations:: How to create them.
1670 * Citation Styles:: Natbib, Harvard, Chicago and Co.
1671 * Citation Info:: View the corresponding database entry.
1672 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
1673 * Citations Outside LaTeX:: How to make citations in Emails etc.
1674 * BibTeX Database Subsets:: Extract parts of a big database.
1677 @node Creating Citations, Citation Styles, , Citations
1678 @section Creating Citations
1679 @cindex Creating citations
1680 @cindex Citations, creating
1681 @findex reftex-citation
1683 @cindex Selection buffer, citations
1684 @cindex Selection process
1686 In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then
1687 prompts for a regular expression which will be used to search through
1688 the database and present the list of matches to choose from in a
1689 selection process similar to that for selecting labels
1690 (@pxref{Referencing Labels}).
1692 The regular expression uses an extended syntax: @samp{&&} defines a
1693 logic @code{and} for regular expressions. For example
1694 @samp{Einstein&&Bose} will match all articles which mention
1695 Bose-Einstein condensation, or which are co-authored by Bose and
1696 Einstein. When entering the regular expression, you can complete on
1697 known citation keys. RefTeX also offers a default when prompting for a
1698 regular expression. This default is the word before the cursor or the
1699 word before the current @samp{\cite} command. Sometimes this may be a
1702 @cindex @code{\bibliography}
1703 @cindex @code{thebibliography}, LaTeX environment
1704 @cindex @code{BIBINPUTS}, environment variable
1705 @cindex @code{TEXBIB}, environment variable
1706 @b{Ref@TeX{}} prefers to use BibTeX database files specified with a
1707 @code{\bibliography} macro to collect its information. Just like
1708 BibTeX, it will search for the specified files in the current directory
1709 and along the path given in the environment variable @code{BIBINPUTS}.
1710 If you do not use BibTeX, but the document contains an explicit
1711 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
1712 information from there. Note that in this case the information
1713 presented in the selection buffer will just be a copy of relevant
1714 @code{\bibitem} entries, not the structured listing available with
1715 BibTeX database files.
1718 In the selection buffer, the following keys provide special commands. A
1719 summary of this information is always available from the selection
1720 process by pressing @kbd{?}.
1723 @tablesubheading{General}
1725 Show a summary of available commands.
1730 @tablesubheading{Moving around}
1735 Go to previous article.
1737 @tablesubheading{Access to full database entries}
1739 Show the database entry corresponding to the article at point, in
1740 another window. See also the @kbd{f} key.
1743 Toggle follow mode. When follow mode is active, the other window will
1744 always display the full database entry of the current article. This is
1745 equivalent to pressing @key{SPC} after each cursor motion. With BibTeX
1746 entries, follow mode can be rather slow.
1748 @tablesubheading{Selecting entries and creating the citation}
1750 Insert a citation referencing the article at point into the buffer from
1751 which the selection process was started.
1754 @vindex reftex-highlight-selection
1755 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1756 would. See also variable @code{reftex-highlight-selection}, @ref{Options
1760 Mark the current entry. When one or several entries are marked,
1761 pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
1762 @key{RET} behaves like the @kbd{a} key.
1765 Unmark a marked entry.
1768 Accept all (marked) entries in the selection buffer and create a single
1769 @code{\cite} macro referring to them.
1772 Accept all (marked) entries in the selection buffer and create a
1773 separate @code{\cite} macro for each of it.
1776 Create a new BibTeX database file which contains all @i{marked} entries
1777 in the selection buffer. If no entries are marked, all entries are
1781 Create a new BibTeX database file which contains all @i{unmarked}
1782 entries in the selection buffer. If no entries are marked, all entries
1786 Enter a citation key with completion. This may also be a key which does
1790 Show insertion point in another window. This is the point from where you
1791 called @code{reftex-citation}.
1793 @tablesubheading{Exiting}
1795 Exit the selection process without inserting a citation into the
1798 @tablesubheading{Updating the buffer}
1801 Start over with a new regular expression. The full database will be
1802 rescanned with the new expression (see also @kbd{r}).
1804 @c FIXME: Should we use something else here? r is usually rescan!
1806 Refine the current selection with another regular expression. This will
1807 @emph{not} rescan the entire database, but just the already selected
1812 @vindex reftex-select-bib-map
1813 In order to define additional commands for this selection process, the
1814 keymap @code{reftex-select-bib-map} may be used.
1816 @node Citation Styles, Citation Info, Creating Citations, Citations
1817 @section Citation Styles
1818 @cindex Citation styles
1819 @cindex Citation styles, @code{natbib}
1820 @cindex Citation styles, @code{harvard}
1821 @cindex Citation styles, @code{chicago}
1822 @cindex Citation styles, @code{jurabib}
1823 @cindex @code{natbib}, citation style
1824 @cindex @code{harvard}, citation style
1825 @cindex @code{chicago}, citation style
1826 @cindex @code{jurabib}, citation style
1828 @vindex reftex-cite-format
1829 The standard LaTeX macro @code{\cite} works well with numeric or simple
1830 key citations. To deal with the more complex task of author-year
1831 citations as used in many natural sciences, a variety of packages has
1832 been developed which define derived forms of the @code{\cite} macro.
1833 @b{Ref@TeX{}} can be configured to produce these citation macros as well
1834 by setting the variable @code{reftex-cite-format}. For the most
1835 commonly used packages (@code{natbib}, @code{harvard}, @code{chicago},
1836 @code{jurabib}) this may be done from the menu, under
1837 @code{Ref->Citation Styles}. Since there are usually several macros to
1838 create the citations, executing @code{reftex-citation} (@kbd{C-c [})
1839 starts by prompting for the correct macro. For the Natbib style, this
1843 SELECT A CITATION FORMAT
1850 [e] \citep[e.g.][]@{%l@}
1851 [s] \citep[see][]@{%l@}
1852 [a] \citeauthor@{%l@}
1853 [A] \citeauthor*@{%l@}
1857 @vindex reftex-cite-prompt-optional-args
1858 If cite formats contain empty paris of square brackets, RefTeX can
1859 will prompt for values of these optional arguments if you call the
1860 @code{reftex-citation} command with a @kbd{C-u} prefix.
1861 Following the most generic of these packages, @code{natbib}, the builtin
1862 citation packages always accept the @kbd{t} key for a @emph{textual}
1863 citation (like: @code{Jones et al. (1997) have shown...}) as well as
1864 the @kbd{p} key for a parenthetical citation (like: @code{As shown
1865 earlier (Jones et al, 1997)}).
1867 To make one of these styles the default, customize the variable
1868 @code{reftex-cite-format} or put into @file{.emacs}:
1871 (setq reftex-cite-format 'natbib)
1874 You can also use AUCTeX style files to automatically set the
1875 citation style based on the @code{usepackage} commands in a given
1876 document. @xref{Style Files}, for information on how to set up the style
1879 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
1880 @section Citation Info
1881 @cindex Displaying citations
1882 @cindex Citations, displaying
1883 @cindex Citation info
1884 @cindex Viewing citations
1887 @findex reftex-view-crossref
1888 @findex reftex-mouse-view-crossref
1890 When point is idle for more than @code{reftex-idle-time} seconds on the
1891 argument of a @code{\cite} macro, the echo area will display some
1892 information about the article cited there. Note that the information is
1893 only displayed if the echo area is not occupied by a different message.
1895 @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
1896 entry corresponding to a @code{\cite} macro, or all citation locations
1897 corresponding to a @code{\bibitem} or BibTeX database entry.
1898 @xref{Viewing Cross-References}.
1900 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
1901 @section Chapterbib and Bibunits
1902 @cindex @code{chapterbib}, LaTeX package
1903 @cindex @code{bibunits}, LaTeX package
1904 @cindex Bibliographies, multiple
1906 @code{chapterbib} and @code{bibunits} are two LaTeX packages which
1907 produce multiple bibliographies in a document. This is no problem for
1908 @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
1909 files. If they do not, it is best to have each document part in a
1910 separate file (as it is required for @code{chapterbib} anyway). Then
1911 @b{Ref@TeX{}} will still scan the locally relevant databases correctly. If
1912 you have multiple bibliographies within a @emph{single file}, this may
1913 or may not be the case.
1915 @node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations
1916 @section Citations outside LaTeX
1917 @cindex Citations outside LaTeX
1918 @vindex reftex-default-bibliography
1920 The command @code{reftex-citation} can also be executed outside a LaTeX
1921 buffer. This can be useful to reference articles in the mail buffer and
1922 other documents. You should @emph{not} enter @code{reftex-mode} for
1923 this, just execute the command. The list of BibTeX files will in this
1924 case be taken from the variable @code{reftex-default-bibliography}.
1925 Setting the variable @code{reftex-cite-format} to the symbol
1926 @code{locally} does a decent job of putting all relevant information
1927 about a citation directly into the buffer. Here is the lisp code to add
1928 the @kbd{C-c [} binding to the mail buffer. It also provides a local
1929 binding for @code{reftex-cite-format}.
1932 (add-hook 'mail-setup-hook
1933 (lambda () (define-key mail-mode-map "\C-c["
1936 (let ((reftex-cite-format 'locally))
1937 (reftex-citation))))))
1940 @node BibTeX Database Subsets, , Citations Outside LaTeX, Citations
1941 @section Database Subsets
1942 @cindex BibTeX database subsets
1943 @findex reftex-create-bibtex-file
1945 @b{Ref@TeX{}} offers two ways to create a new BibTeX database file.
1947 The first option produces a file which contains only the entries
1948 actually referenced in the current document. This can be useful if
1949 the database in only meant for a single document and you want to clean
1950 it of old and unused ballast. It can also be useful while writing a
1951 document together with collaborators, in order to avoid sending around
1952 the entire (possibly very large) database. To create the file, use
1953 @kbd{M-x reftex-create-bibtex-file}, also available from the menu
1954 under @code{Ref->Global Actions->Create Bibtex File}. The command will
1955 prompt for a BibTeX file name and write the extracted entries to that
1958 The second option makes use of the selection process started by the
1959 command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a
1960 regular expression to select entries, and lists them in a formatted
1961 selection buffer. After pressing the @kbd{e} key (mnemonics: Export),
1962 the command will prompt for the name of a new BibTeX file and write
1963 the selected entries to that file. You can also first mark some
1964 entries in the selection buffer with the @kbd{m} key and then export
1965 either the @i{marked} entries (with the @kbd{e} key) or the
1966 @i{unmarked} entries (with the @kbd{E} key).
1968 @node Index Support, Viewing Cross-References, Citations, Top
1969 @chapter Index Support
1970 @cindex Index Support
1971 @cindex @code{\index}
1973 LaTeX has builtin support for creating an Index. The LaTeX core
1974 supports two different indices, the standard index and a glossary. With
1975 the help of special LaTeX packages (@file{multind.sty} or
1976 @file{index.sty}), any number of indices can be supported.
1978 Index entries are created with the @code{\index@{@var{entry}@}} macro.
1979 All entries defined in a document are written out to the @file{.aux}
1980 file. A separate tool must be used to convert this information into a
1981 nicely formatted index. Tools used with LaTeX include @code{MakeIndex}
1984 Indexing is a very difficult task. It must follow strict conventions to
1985 make the index consistent and complete. There are basically two
1986 approaches one can follow, and both have their merits.
1990 Part of the indexing should already be done with the markup. The
1991 document structure should be reflected in the index, so when starting
1992 new sections, the basic topics of the section should be indexed. If the
1993 document contains definitions, theorems or the like, these should all
1994 correspond to appropriate index entries. This part of the index can
1995 very well be developed along with the document. Often it is worthwhile
1996 to define special purpose macros which define an item and at the same
1997 time make an index entry, possibly with special formatting to make the
1998 reference page in the index bold or underlined. To make @b{Ref@TeX{}}
1999 support for indexing possible, these special macros must be added to
2000 @b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}).
2003 The rest of the index is often just a collection of where in the
2004 document certain words or phrases are being used. This part is
2005 difficult to develop along with the document, because consistent entries
2006 for each occurrence are needed and are best selected when the document
2007 is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file}
2008 which collects phrases and helps indexing the phrases globally.
2011 Before you start, you need to make sure that @b{Ref@TeX{}} knows about
2012 the index style being used in the current document. @b{Ref@TeX{}} has
2013 builtin support for the default @code{\index} and @code{\glossary}
2014 macros. Other LaTeX packages, like the @file{multind} or @file{index}
2015 package, redefine the @code{\index} macro to have an additional
2016 argument, and @b{Ref@TeX{}} needs to be configured for those. A
2017 sufficiently new version of AUCTeX (9.10c or later) will do this
2018 automatically. If you really don't use AUCTeX (you should!), this
2019 configuration needs to be done by hand with the menu (@code{Ref->Index
2020 Style}), or globally for all your documents with
2023 (setq reftex-index-macros '(multind)) @r{or}
2024 (setq reftex-index-macros '(index))
2028 * Creating Index Entries:: Macros and completion of entries.
2029 * The Index Phrases File:: A special file for global indexing.
2030 * Displaying and Editing the Index:: The index editor.
2031 * Builtin Index Macros:: The index macros RefTeX knows about.
2032 * Defining Index Macros:: ... and macros it doesn't.
2035 @node Creating Index Entries, The Index Phrases File, , Index Support
2036 @section Creating Index Entries
2037 @cindex Creating index entries
2038 @cindex Index entries, creating
2040 @findex reftex-index
2042 @findex reftex-index-selection-or-word
2044 In order to index the current selection or the word at the cursor press
2045 @kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
2046 selection or word @samp{@var{word}} to be replaced with
2047 @samp{\index@{@var{word}@}@var{word}}. The macro which is used
2048 (@code{\index} by default) can be configured with the variable
2049 @code{reftex-index-default-macro}. When the command is called with a
2050 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
2051 generated index entry. Use this to change the case of the word or to
2052 make the entry a subentry, for example by entering
2053 @samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
2054 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
2055 When there is nothing selected and no word at point, this command will
2056 just call @code{reftex-index}, described below.
2058 In order to create a general index entry, press @kbd{C-c <}
2059 (@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the
2060 available index macros and for its arguments. Completion will be
2061 available for the index entry and, if applicable, the index tag. The
2062 index tag is a string identifying one of multiple indices. With the
2063 @file{multind} and @file{index} packages, this tag is the first argument
2064 to the redefined @code{\index} macro.
2066 @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
2067 @section The Index Phrases File
2068 @cindex Index phrase file
2071 @findex reftex-index-visit-phrases-buffer
2072 @cindex Macro definition lines, in phrase buffer
2074 @b{Ref@TeX{}} maintains a file in which phrases can be collected for
2075 later indexing. The file is located in the same directory as the master
2076 file of the document and has the extension @file{.rip} (@b{R}eftex
2077 @b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c
2078 |} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it
2079 is initialized by inserting a file header which contains the definition
2080 of the available index macros. This list is initialized from
2081 @code{reftex-index-macros} (@pxref{Defining Index Macros}). You can
2082 edit the header as needed, but if you define new LaTeX indexing macros,
2083 don't forget to add them to @code{reftex-index-macros} as well. Here is
2084 a phrase file header example:
2087 % -*- mode: reftex-index-phrases -*-
2088 % Key Macro Format Repeat
2089 %----------------------------------------------------------
2090 >>>INDEX_MACRO_DEFINITION: i \index@{%s@} t
2091 >>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil
2092 >>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t
2093 >>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil
2094 %----------------------------------------------------------
2097 The macro definition lines consist of a unique letter identifying a
2098 macro, a format string and the @var{repeat} flag, all separated by
2099 @key{TAB}. The format string shows how the macro is to be applied, the
2100 @samp{%s} will be replaced with the index entry. The repeat flag
2101 indicates if @var{word} is indexed by the macro as
2102 @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
2103 @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the
2104 above example it is assumed that the macro @code{\index*@{@var{word}@}}
2105 already typesets its argument in the text, so that it is unnecessary to
2106 repeat @var{word} outside the macro.
2109 * Collecting Phrases:: Collecting from document or external.
2110 * Consistency Checks:: Check for duplicates etc.
2111 * Global Indexing:: The interactive indexing process.
2114 @node Collecting Phrases, Consistency Checks, , The Index Phrases File
2115 @subsection Collecting Phrases
2116 @cindex Collecting index phrases
2117 @cindex Index phrases, collection
2118 @cindex Phrases, collecting
2120 Phrases for indexing can be collected while writing the document. The
2121 command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2122 copies the current selection (if active) or the word near point into the
2123 phrases buffer. It then selects this buffer, so that the phrase line
2124 can be edited. To return to the LaTeX document, press @kbd{C-c C-c}
2125 (@code{reftex-index-phrases-save-and-return}).
2127 You can also prepare the list of index phrases in a different way and
2128 copy it into the phrases file. For example you might want to start from
2129 a word list of the document and remove all words which should not be
2132 The phrase lines in the phrase buffer must have a specific format.
2133 @b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
2134 format. A phrase line looks like this:
2137 [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
2140 @code{<TABs>} stands for white space containing at least one @key{TAB}.
2141 @var{key} must be at the start of the line and is the character
2142 identifying one of the macros defined in the file header. It is
2143 optional - when omitted, the first macro definition line in the file
2144 will be used for this phrase. The @var{phrase} is the phrase to be
2145 searched for when indexing. It may contain several words separated by
2146 spaces. By default the search phrase is also the text entered as
2147 argument of the index macro. If you want the index entry to be
2148 different from the search phrase, enter another @key{TAB} and the index
2149 argument @var{arg}. If you want to have each match produce several
2150 index entries, separate the different index arguments with @samp{ &&
2151 }@footnote{@samp{&&} with optional spaces, see
2152 @code{reftex-index-phrases-logical-and-regexp}.}. If you want to be
2153 able to choose at each match between several different index arguments,
2154 separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2155 see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an
2159 %--------------------------------------------------------------------
2163 Jupiter Planets!Jupiter
2164 i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2165 i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto
2169 So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2170 @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2171 @samp{Vega} will be indexed as a subitem of @samp{Stars}. The
2172 @samp{Jupiter} line will also use the @samp{i} macro as it was the first
2173 macro definition in the file header (see above example). At each
2174 occurrence of @samp{Mars} you will be able choose between indexing it as
2175 a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2176 Finally, every occurrence of @samp{Pluto} will be indexed as
2177 @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2178 and will therefore create two different index entries.
2180 @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
2181 @subsection Consistency Checks
2182 @cindex Index phrases, consistency checks
2183 @cindex Phrases, consistency checks
2184 @cindex Consistency check for index phrases
2187 Before indexing the phrases in the phrases buffer, they should be
2188 checked carefully for consistency. A first step is to sort the phrases
2189 alphabetically - this is done with the command @kbd{C-c C-s}
2190 (@code{reftex-index-sort-phrases}). It will sort all phrases in the
2191 buffer alphabetically by search phrase. If you want to group certain
2192 phrases and only sort within the groups, insert empty lines between the
2193 groups. Sorting will only change the sequence of phrases within each
2194 group (see the variable @code{reftex-index-phrases-sort-in-blocks}).
2197 A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2198 which lists information about the phrase at point, including an example
2199 of how the index entry will look like and the number of expected matches
2203 Another important check is to find out if there are double or
2204 overlapping entries in the buffer. For example if you are first
2205 searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2206 second phrase will not match because of the index macro inserted before
2207 @samp{Mars} earlier. The command @kbd{C-c C-t}
2208 (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2209 the buffer which is either duplicate or a subphrase of another phrase.
2210 In order to check the whole buffer like this, start at the beginning and
2211 execute this command repeatedly.
2213 @node Global Indexing, , Consistency Checks, The Index Phrases File
2214 @subsection Global Indexing
2215 @cindex Global indexing
2216 @cindex Indexing, global
2217 @cindex Indexing, from @file{phrases} buffer
2219 Once the index phrases have been collected and organized, you are set
2220 for global indexing. I recommend to do this only on an otherwise
2221 finished document. Global indexing starts from the phrases buffer.
2222 There are several commands which start indexing: @kbd{C-c C-x} acts on
2223 the current phrase line, @kbd{C-c C-r} on all lines in the current
2224 region and @kbd{C-c C-a} on all phrase lines in the buffer. It is
2225 probably good to do indexing in small chunks since your concentration
2226 may not last long enough to do everything in one go.
2228 @b{Ref@TeX{}} will start at the first phrase line and search the phrase
2229 globally in the whole document. At each match it will stop, compute the
2230 replacement string and offer you the following choices@footnote{Windows
2231 users: Restrict yourself to the described keys during indexing. Pressing
2232 @key{Help} at the indexing prompt can apparently hang Emacs.}:
2236 Replace this match with the proposed string.
2240 Replace this and all further matches in this file.
2242 Skip this match, start with next file.
2244 Skip this match, start with next phrase.
2246 Select a different indexing macro for this match.
2248 Select one of multiple index keys (those separated with @samp{||}).
2250 Edit the replacement text.
2252 Recursive edit. Use @kbd{C-M-c} to return to the indexing process.
2254 Save this buffer and ask again about the current match.
2256 Save all document buffers and ask again about the current match.
2258 Abort the indexing process.
2261 The @samp{Find and Index in Document} menu in the phrases buffer also
2262 lists a few options for the indexing process. The options have
2263 associated customization variables to set the defaults (@pxref{Options
2264 (Index Support)}). Here is a short explanation of what the options do:
2267 @item Match Whole Words
2268 When searching for index phrases, make sure whole words are matched.
2269 This should probably always be on.
2270 @item Case Sensitive Search
2271 Search case sensitively for phrases. I recommend to have this setting
2272 off, in order to match the capitalized words at the beginning of a
2273 sentence, and even typos. You can always say @emph{no} at a match you
2275 @item Wrap Long Lines
2276 Inserting index macros increases the line length. Turn this option on
2277 to allow @b{Ref@TeX{}} to wrap long lines.
2278 @item Skip Indexed Matches
2279 When this is on, @b{Ref@TeX{}} will at each match try to figure out if
2280 this match is already indexed. A match is considered indexed if it is
2281 either the argument of an index macro, or if an index macro is directly
2282 (without whitespace separation) before or after the match. Index macros
2283 are those configured in @code{reftex-index-macros}. Intended for
2284 re-indexing a documents after changes have been made.
2287 Even though indexing should be the last thing you do to a document, you
2288 are bound to make changes afterwards. Indexing then has to be applied
2289 to the changed regions. The command
2290 @code{reftex-index-phrases-apply-to-region} is designed for this
2291 purpose. When called from a LaTeX document with active region, it will
2292 apply @code{reftex-index-all-phrases} to the current region.
2294 @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
2295 @section Displaying and Editing the Index
2296 @cindex Displaying the Index
2297 @cindex Editing the Index
2298 @cindex Index entries, creating
2299 @cindex Index, displaying
2300 @cindex Index, editing
2302 @findex reftex-display-index
2304 In order to compile and display the index, press @kbd{C-c >}. If the
2305 document uses multiple indices, @b{Ref@TeX{}} will ask you to select
2306 one. Then, all index entries will be sorted alphabetically and
2307 displayed in a special buffer, the @file{*Index*} buffer. From that
2308 buffer you can check and edit each entry.
2310 The index can be restricted to the current section or the region. Then
2311 only entries in that part of the document will go into the compiled
2312 index. To restrict to the current section, use a numeric prefix
2313 @samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
2314 region, make the region active and use a numeric prefix @samp{3} (press
2315 @kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
2316 restriction can be moved from one section to the next by pressing the
2317 @kbd{<} and @kbd{>} keys.
2319 One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
2320 by searching near the buffer position where it had found to macro during
2321 scanning. If you have several identical index entries in the same
2322 buffer and significant changes have shifted the entries around, you must
2323 rescan the buffer to ensure the correspondence between the
2324 @file{*Index*} buffer and the definition locations. It is therefore
2325 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2326 frequently while editing the index from the @file{*Index*}
2330 Here is a list of special commands available in the @file{*Index*} buffer. A
2331 summary of this information is always available by pressing
2335 @tablesubheading{General}
2337 Display a summary of commands.
2342 @tablesubheading{Moving around}
2344 Pressing any capital letter will jump to the corresponding section in
2345 the @file{*Index*} buffer. The exclamation mark is special and jumps to
2346 the first entries alphabetically sorted below @samp{A}. These are
2347 usually non-alphanumeric characters.
2351 Go to previous entry.
2353 @tablesubheading{Access to document locations}
2355 Show the place in the document where this index entry is defined.
2358 Go to the definition of the current index entry in another
2362 Go to the definition of the current index entry and hide the
2363 @file{*Index*} buffer window.
2366 @vindex reftex-index-follow-mode
2367 @vindex reftex-revisit-to-follow
2368 Toggle follow mode. When follow mode is active, the other window will
2369 always show the location corresponding to the line in the @file{*Index*}
2370 buffer at point. This is similar to pressing @key{SPC} after each
2371 cursor motion. The default for this flag can be set with the variable
2372 @code{reftex-index-follow-mode}. Note that only context in files
2373 already visited is shown. @b{Ref@TeX{}} will not visit a file just for
2374 follow mode. See, however, the variable
2375 @code{reftex-revisit-to-follow}.
2377 @tablesubheading{Entry editing}
2379 Edit the current index entry. In the minibuffer, you can edit the
2380 index macro which defines this entry.
2383 Kill the index entry. Currently not implemented because I don't know
2384 how to implement an @code{undo} function for this.
2387 Edit the @var{key} part of the entry. This is the initial part of the
2388 entry which determines the location of the entry in the index.
2391 Edit the @var{attribute} part of the entry. This is the part after the
2392 vertical bar. With @code{MakeIndex}, this part is an encapsulating
2393 macro. With @code{xindy}, it is called @emph{attribute} and is a
2394 property of the index entry that can lead to special formatting. When
2395 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2399 Edit the @var{visual} part of the entry. This is the part after the
2400 @samp{@@} which is used by @code{MakeIndex} to change the visual
2401 appearance of the entry in the index. When called with @kbd{C-u}
2402 prefix, kill the entire @var{visual} part.
2405 Toggle the beginning of page range property @samp{|(} of the
2409 Toggle the end of page range property @samp{|)} of the entry.
2412 Make the current entry a subentry. This command will prompt for the
2413 superordinate entry and insert it.
2416 Remove the highest superordinate entry. If the current entry is a
2417 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2420 @tablesubheading{Exiting}
2422 Hide the @file{*Index*} buffer.
2425 Kill the @file{*Index*} buffer.
2428 Switch to the Table of Contents buffer of this document.
2430 @tablesubheading{Controlling what gets displayed}
2432 @vindex reftex-index-include-context
2433 Toggle the display of short context in the @file{*Index*} buffer. The
2434 default for this flag can be set with the variable
2435 @code{reftex-index-include-context}.
2438 Restrict the index to a single document section. The corresponding
2439 section number will be displayed in the @code{R<>} indicator in the
2440 mode line and in the header of the @file{*Index*} buffer.
2443 Widen the index to contain all entries of the document.
2446 When the index is currently restricted, move the restriction to the
2450 When the index is currently restricted, move the restriction to the
2453 @tablesubheading{Updating the buffer}
2455 Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
2456 document. However, it sorts the entries again, so that edited entries
2457 will move to the correct position.
2460 @vindex reftex-enable-partial-scans
2461 Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When
2462 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
2463 location is defined in, not the entire document.
2466 Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
2470 Switch to a different index (for documents with multiple
2475 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2476 @section Builtin Index Macros
2477 @cindex Builtin index macros
2478 @cindex Index macros, builtin
2479 @vindex reftex-index-macros
2480 @cindex @code{multind}, LaTeX package
2481 @cindex @code{index}, LaTeX package
2482 @cindex LaTeX packages, @code{multind}
2483 @cindex LaTeX packages, @code{index}
2485 @b{Ref@TeX{}} by default recognizes the @code{\index} and
2486 @code{\glossary} macros which are defined in the LaTeX core. It has
2487 also builtin support for the re-implementations of @code{\index}
2488 in the @file{multind} and @file{index} packages. However, since
2489 the different definitions of the @code{\index} macro are incompatible,
2490 you will have to explicitly specify the index style used.
2491 @xref{Creating Index Entries}, for information on how to do that.
2493 @node Defining Index Macros, , Builtin Index Macros, Index Support
2494 @section Defining Index Macros
2495 @cindex Defining Index Macros
2496 @cindex Index macros, defining
2497 @vindex reftex-index-macros
2499 When writing a document with an index you will probably define
2500 additional macros which make entries into the index.
2501 Let's look at an example.
2504 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2505 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2506 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2509 The first macro @code{\ix} typesets its argument in the text and places
2510 it into the index. The second macro @code{\nindex} typesets its
2511 argument in the text and places it into a separate index with the tag
2512 @samp{name}@footnote{We are using the syntax of the @file{index} package
2513 here.}. The last macro also places its argument into the index, but as
2514 subitems under the main index entry @samp{Astronomical Objects}. Here
2515 is how to make @b{Ref@TeX{}} recognize and correctly interpret these
2516 macros, first with Emacs Lisp.
2519 (setq reftex-index-macros
2520 '(("\\ix@{*@}" "idx" ?x "" nil nil)
2521 ("\\nindex@{*@}" "name" ?n "" nil nil)
2522 ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2525 Note that the index tag is @samp{idx} for the main index, and
2526 @samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
2527 for the default index and for the glossary.
2529 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2530 quick identification of these macros when @b{Ref@TeX{}} inserts new
2531 index entries with @code{reftex-index}. These codes need to be
2532 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2533 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2536 The following string is empty unless your macro adds a superordinate
2537 entry to the index key - this is the case for the @code{\astobj} macro.
2539 The next entry can be a hook function to exclude certain matches, it
2540 almost always can be @code{nil}.
2542 The final element in the list indicates if the text being indexed needs
2543 to be repeated outside the macro. For the normal index macros, this
2544 should be @code{t}. Only if the macro typesets the entry in the text
2545 (like @code{\ix} and @code{\nindex} in the example do), this should be
2548 To do the same thing with customize, you need to fill in the templates
2554 Macro with args: \ix@{*@}
2555 Index Tag : [Value Menu] String: idx
2558 Exclusion hook : nil
2559 Repeat Outside : [Toggle] off (nil)
2561 Macro with args: \nindex@{*@}
2562 Index Tag : [Value Menu] String: name
2565 Exclusion hook : nil
2566 Repeat Outside : [Toggle] off (nil)
2568 Macro with args: \astobj@{*@}
2569 Index Tag : [Value Menu] String: idx
2571 Key Prefix : Astronomical Objects!
2572 Exclusion hook : nil
2573 Repeat Outside : [Toggle] on (non-nil)
2577 With the macro @code{\ix} defined, you may want to change the default
2578 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2579 This would be done like this
2582 (setq reftex-index-default-macro '(?x "idx"))
2585 which specifies that the macro identified with the character @code{?x} (the
2586 @code{\ix} macro) should be used for indexing phrases and words already
2587 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2588 The index tag is "idx".
2590 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2591 @chapter Viewing Cross--References
2592 @findex reftex-view-crossref
2593 @findex reftex-mouse-view-crossref
2597 @b{Ref@TeX{}} can display cross--referencing information. This means,
2598 if two document locations are linked, @b{Ref@TeX{}} can display the
2599 matching location(s) in another window. The @code{\label} and @code{\ref}
2600 macros are one way of establishing such a link. Also, a @code{\cite}
2601 macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
2604 The feature is invoked by pressing @kbd{C-c &}
2605 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2606 of a macro involved in cross--referencing. You can also click with
2607 @kbd{S-mouse-2} on the macro argument. Here is what will happen for
2608 individual classes of macros:
2614 Display the corresponding label definition. All usual
2615 variants@footnote{all macros that start with @samp{ref} or end with
2616 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2617 cross--reference display. This works also for labels defined in an
2618 external document when the current document refers to them through the
2619 @code{xr} interface (@pxref{xr (LaTeX package)}).
2622 @cindex @code{\label}
2623 @vindex reftex-label-alist
2624 Display a document location which references this label. Pressing
2625 @kbd{C-c &} several times moves through the entire document and finds
2626 all locations. Not only the @code{\label} macro but also other macros
2627 with label arguments (as configured with @code{reftex-label-alist}) are
2628 active for cross--reference display.
2631 @cindex @code{\cite}
2632 Display the corresponding BibTeX database entry or @code{\bibitem}.
2633 All usual variants@footnote{all macros that either start or end with
2634 @samp{cite}} of the @code{\cite} macro are active for cross--reference
2637 @item @code{\bibitem}
2638 @cindex @code{\bibitem}
2639 Display a document location which cites this article. Pressing
2640 @kbd{C-c &} several times moves through the entire document and finds
2644 @cindex BibTeX buffer, viewing cite locations from
2645 @cindex Viewing cite locations from BibTeX buffer
2646 @kbd{C-c &} is also active in BibTeX buffers. All locations in a
2647 document where the database entry at point is cited will be displayed.
2648 On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
2649 the document you want to search. Subsequent calls will use the same
2650 document, until you break this link with a prefix argument to @kbd{C-c
2654 @cindex @code{\index}
2655 Display other locations in the document which are marked by an index
2656 macro with the same key argument. Along with the standard @code{\index}
2657 and @code{\glossary} macros, all macros configured in
2658 @code{reftex-index-macros} will be recognized.
2661 @vindex reftex-view-crossref-extra
2662 While the display of cross referencing information for the above
2663 mentioned macros is hard--coded, you can configure additional relations
2664 in the variable @code{reftex-view-crossref-extra}.
2667 @chapter All the Rest
2670 @node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
2671 @section @b{Ref@TeX{}}'s Menu
2672 @cindex RefTeXs Menu
2673 @cindex Menu, in the menu bar
2675 @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
2676 which support this. From this menu you can access all of
2677 @b{Ref@TeX{}}'s commands and a few of its options. There is also a
2678 @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
2679 entire set of options.
2681 @node Key Bindings, Faces, RefTeXs Menu, Top
2682 @section Default Key Bindings
2683 @cindex Key Bindings, summary
2685 Here is a summary of the available key bindings.
2700 @kbd{C-c =} @code{reftex-toc}
2701 @kbd{C-c -} @code{reftex-toc-recenter}
2702 @kbd{C-c (} @code{reftex-label}
2703 @kbd{C-c )} @code{reftex-reference}
2704 @kbd{C-c [} @code{reftex-citation}
2705 @kbd{C-c &} @code{reftex-view-crossref}
2706 @kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
2707 @kbd{C-c /} @code{reftex-index-selection-or-word}
2708 @kbd{C-c \} @code{reftex-index-phrase-selection-or-word}
2709 @kbd{C-c |} @code{reftex-index-visit-phrases-buffer}
2710 @kbd{C-c <} @code{reftex-index}
2711 @kbd{C-c >} @code{reftex-display-index}
2714 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2715 not already used by some other package. @b{Ref@TeX{}} will not override an
2716 existing binding to @kbd{S-mouse-2}.
2718 Personally, I also bind some functions in the users @kbd{C-c} map for
2721 @c FIXME: Do we need bindings for the Index macros here as well?
2722 @c C-c i C-c I or so????
2723 @c How about key bindings for reftex-reset-mode and reftex-parse-document?
2732 @kbd{C-c t} @code{reftex-toc}
2733 @kbd{C-c l} @code{reftex-label}
2734 @kbd{C-c r} @code{reftex-reference}
2735 @kbd{C-c c} @code{reftex-citation}
2736 @kbd{C-c v} @code{reftex-view-crossref}
2737 @kbd{C-c s} @code{reftex-search-document}
2738 @kbd{C-c g} @code{reftex-grep-document}
2741 @noindent These keys are reserved for the user, so I cannot bind them by
2742 default. If you want to have these key bindings available, set in your
2745 @vindex reftex-extra-bindings
2747 (setq reftex-extra-bindings t)
2750 @vindex reftex-load-hook
2751 Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook
2752 @code{reftex-load-hook}. For information on the keymaps
2753 which should be used to add keys, see @ref{Keymaps and Hooks}.
2755 @node Faces, AUCTeX, Key Bindings, Top
2759 @b{Ref@TeX{}} uses faces when available to structure the selection and
2760 table of contents buffers. It does not create its own faces, but uses
2761 the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will
2762 use faces only when @code{font-lock} is loaded. This seems to be
2763 reasonable because people who like faces will very likely have it
2764 loaded. If you wish to turn off fontification or change the involved
2765 faces, see @ref{Options (Fontification)}.
2767 @node Multifile Documents, Language Support, AUCTeX, Top
2768 @section Multifile Documents
2769 @cindex Multifile documents
2770 @cindex Documents, spread over files
2772 The following is relevant when working with documents spread over many
2777 @b{Ref@TeX{}} has full support for multifile documents. You can edit parts of
2778 several (multifile) documents at the same time without conflicts.
2779 @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
2780 @code{query-replace} on all files which are part of a multifile
2784 @vindex tex-main-file
2786 All files belonging to a multifile document should define a File
2787 Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
2788 standard Emacs LaTeX mode) containing the name of the master file. For
2789 example, to set the file variable @code{TeX-master}, include something
2790 like the following at the end of each TeX file:
2793 %%% Local Variables: ***
2795 %%% TeX-master: "thesis.tex" ***
2799 AUCTeX with the setting
2802 (setq-default TeX-master nil)
2805 will actually ask you for each new file about the master file and insert
2806 this comment automatically. For more details see the documentation of
2807 the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
2808 documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2809 The GNU Emacs Manual}) and the Emacs documentation on File Variables
2810 (@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
2813 The context of a label definition must be found in the same file as the
2814 label itself in order to be processed correctly by @b{Ref@TeX{}}. The only
2815 exception is that section labels referring to a section statement
2816 outside the current file can still use that section title as
2820 @node Language Support, Finding Files, Multifile Documents, Top
2821 @section Language Support
2822 @cindex Language support
2824 Some parts of @b{Ref@TeX{}} are language dependent. The default
2825 settings work well for English. If you are writing in a different
2826 language, the following hints may be useful:
2830 @vindex reftex-derive-label-parameters
2831 @vindex reftex-abbrev-parameters
2832 The mechanism to derive a label from context includes the abbreviation
2833 of words and omission of unimportant words. These mechanisms may have
2834 to be changed for other languages. See the variables
2835 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2838 @vindex reftex-translate-to-ascii-function
2839 @vindex reftex-label-illegal-re
2840 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
2841 context string from non-ASCII characters in order to make a valid label.
2842 If there should ever be a version of @TeX{} which allows extended
2843 characters @emph{in labels}, then we will have to look at the
2844 variables @code{reftex-translate-to-ascii-function} and
2845 @code{reftex-label-illegal-re}.
2848 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
2849 to guess which label type is required. These @emph{magic words} are
2850 different in every language. For an example of how to add magic words,
2851 see @ref{Adding Magic Words}.
2853 @vindex reftex-multiref-punctuation
2854 @vindex reftex-cite-punctuation
2856 @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
2857 for the author list in citations. Some of this may be language
2858 dependent. See the variables @code{reftex-multiref-punctuation} and
2859 @code{reftex-cite-punctuation}.
2862 @node Finding Files, Optimizations, Language Support, Top
2863 @section Finding Files
2864 @cindex Finding files
2866 In order to find files included in a document via @code{\input} or
2867 @code{\include}, @b{Ref@TeX{}} searches all directories specified in the
2868 environment variable @code{TEXINPUTS}. Similarly, it will search the
2869 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
2870 BibTeX database files.
2872 When searching, @b{Ref@TeX{}} will also expand recursive path
2873 definitions (directories ending in @samp{//} or @samp{!!}). But it will
2874 only search and expand directories @emph{explicitly} given in these
2875 variables. This may cause problems under the following circumstances:
2879 Most TeX system have a default search path for both TeX files and BibTeX
2880 files which is defined in some setup file. Usually this default path is
2881 for system files which @b{Ref@TeX{}} does not need to see. But if your
2882 document needs TeX files or BibTeX database files in a directory only
2883 given in the default search path, @b{Ref@TeX{}} will fail to find them.
2885 Some TeX systems do not use environment variables at all in order to
2886 specify the search path. Both default and user search path are then
2887 defined in setup files.
2891 There are three ways to solve this problem:
2895 Specify all relevant directories explicitly in the environment
2896 variables. If for some reason you don't want to mess with the default
2897 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
2898 variables and configure @b{Ref@TeX{}} to use them instead:
2901 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
2902 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
2906 Specify the full search path directly in @b{Ref@TeX{}}'s variables.
2909 (setq reftex-texpath-environment-variables
2910 '("./inp:/home/cd/tex//:/usr/local/tex//"))
2911 (setq reftex-bibpath-environment-variables
2912 '("/home/cd/tex/lit/"))
2916 Some TeX systems provide stand--alone programs to do the file search just
2917 like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the
2918 @code{kpathsearch} library which provides the command @code{kpsewhich}
2919 to search for files. @b{Ref@TeX{}} can be configured to use this
2920 program. Note that the exact syntax of the @code{kpsewhich}
2921 command depends upon the version of that program.
2924 (setq reftex-use-external-file-finders t)
2925 (setq reftex-external-file-finders
2926 '(("tex" . "kpsewhich -format=.tex %f")
2927 ("bib" . "kpsewhich -format=.bib %f")))
2932 @vindex reftex-file-extensions
2933 @vindex TeX-file-extensions
2934 Some people like to use RefTeX with noweb files, which usually have the
2935 extension @file{.nw}. In order to deal with such files, the new
2936 extension must be added to the list of valid extensions in the variable
2937 @code{reftex-file-extensions}. When working with AUCTeX as major mode,
2938 the new extension must also be known to AUCTeX via the variable
2939 @code{TeX-file-extension}. For example:
2942 (setq reftex-file-extensions
2943 '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
2944 (setq TeX-file-extensions
2945 '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
2948 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
2949 @section Optimizations
2950 @cindex Optimizations
2952 @b{Note added 2002. Computers have gotten a lot faster, so most of the
2953 optimizations discussed below will not be necessary on new machines. I
2954 am leaving this stuff in the manual for people who want to write thick
2955 books, where some of it still might be useful.}
2957 Implementing the principle of least surprises, the default settings of
2958 @b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
2959 when using @b{Ref@TeX{}} for a large project and/or on a small computer,
2960 there are ways to improve speed or memory usage.
2964 @b{Removing Lookup Buffers}@*
2965 @cindex Removing lookup buffers
2966 @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
2967 database files for lookup purposes. These buffers are kept, so that
2968 subsequent use of the same files is fast. If you can't afford keeping
2969 these buffers around, and if you can live with a speed penalty, try
2971 @vindex reftex-keep-temporary-buffers
2973 (setq reftex-keep-temporary-buffers nil)
2977 @b{Partial Document Scans}@*
2978 @cindex Partial documents scans
2979 @cindex Document scanning, partial
2980 A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
2981 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
2982 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
2983 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
2984 re-parsing of the entire document in order to update the parsing
2985 information. For a large document this can be unnecessary, in
2986 particular if only one file has changed. @b{Ref@TeX{}} can be configured
2987 to do partial scans instead of full ones. @kbd{C-u} re-parsing then
2988 does apply only to the current buffer and files included from it.
2989 Likewise, the @kbd{r} key in both the label selection buffer and the
2990 table-of-contents buffer will only prompt scanning of the file in which
2991 the label or section macro near the cursor was defined. Re-parsing of
2992 the entire document is still available by using @kbd{C-u C-u} as a
2993 prefix, or the capital @kbd{R} key in the menus. To use this feature,
2996 @vindex reftex-enable-partial-scans
2998 (setq reftex-enable-partial-scans t)
3002 @b{Saving Parser Information}@*
3003 @cindex Saving parser information
3004 @cindex Parse information, saving to a file
3005 @vindex reftex-parse-file-extension
3006 Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
3007 scan, when you start working with a document. To avoid this, parsing
3008 information can be stored in a file. The file @file{MASTER.rel} is used
3009 for storing information about a document with master file
3010 @file{MASTER.tex}. It is written automatically when you kill a buffer
3011 in @code{reftex-mode} or when you exit Emacs. The information is
3012 restored when you begin working with a document in a new editing
3013 session. To use this feature, put into @file{.emacs}:
3015 @vindex reftex-save-parse-info
3017 (setq reftex-save-parse-info t)
3021 @b{Identifying label types by prefix}@*
3022 @cindex Parse information, saving to a file
3023 @vindex reftex-trust-label-prefix
3024 @b{Ref@TeX{}} normally parses around each label to check in which
3025 environment this label is located, in order to assign a label type to
3026 the label. If your document contains thousands of labels, document
3027 parsing will take considerable time. If you have been using label prefixes
3028 like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the
3029 label type directly from the prefix, without additional parsing. This
3030 will be faster and also allow labels to end up in the correct category
3031 if for some reason it is not possible to derive the correct type from
3032 context. For example, to enable this feature for footnote and
3033 equation labels, use
3036 (setq reftex-trust-label-prefix '("fn:" "eq:"))
3040 @b{Automatic Document Scans}@*
3041 @cindex Automatic document scans
3042 @cindex Document scanning, automatic
3043 At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
3044 document. If this gets into your way, it can be turned off with
3046 @vindex reftex-allow-automatic-rescan
3048 (setq reftex-allow-automatic-rescan nil)
3051 @b{Ref@TeX{}} will then occasionally annotate new labels in the selection
3052 buffer, saying that their position in the label list in uncertain. A
3053 manual document scan will fix this.
3056 @b{Multiple Selection Buffers}@*
3057 @cindex Multiple selection buffers
3058 @cindex Selection buffers, multiple
3059 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
3060 every selection process. In documents with very many labels this can
3061 take several seconds. @b{Ref@TeX{}} provides an option to create a
3062 separate selection buffer for each label type and to keep this buffer
3063 from one selection to the next. These buffers are updated automatically
3064 only when a new label has been added in the buffers category with
3065 @code{reftex-label}. Updating the buffer takes as long as recreating it
3066 - so the time saving is limited to cases where no new labels of that
3067 category have been added. To turn on this feature, use
3069 @vindex reftex-use-multiple-selection-buffers
3071 (setq reftex-use-multiple-selection-buffers t)
3075 @cindex Selection buffers, updating
3076 You can also inhibit the automatic updating entirely. Then the
3077 selection buffer will always pop up very fast, but may not contain the
3078 most recently defined labels. You can always update the buffer by hand,
3079 with the @kbd{g} key. To get this behavior, use instead
3081 @vindex reftex-auto-update-selection-buffers
3083 (setq reftex-use-multiple-selection-buffers t
3084 reftex-auto-update-selection-buffers nil)
3090 @b{As a summary}, here are the settings I recommend for heavy use of
3091 @b{Ref@TeX{}} with large documents:
3095 (setq reftex-enable-partial-scans t
3096 reftex-save-parse-info t
3097 reftex-use-multiple-selection-buffers t)
3101 @node AUCTeX, Multifile Documents, Faces, Top
3103 @cindex @code{AUCTeX}, Emacs package
3104 @cindex Emacs packages, @code{AUCTeX}
3106 AUCTeX is without doubt the best major mode for editing TeX and LaTeX
3107 files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
3108 If AUCTeX is not part of your Emacs distribution, you can get
3109 it@footnote{XEmacs 21.x users may want to install the corresponding
3110 XEmacs package.} by ftp from the @value{AUCTEXSITE}.
3113 * AUCTeX-RefTeX Interface:: How both packages work together
3114 * Style Files:: AUCTeX's style files can support RefTeX
3115 * Bib-Cite:: Hypertext reading of a document
3118 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
3119 @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
3121 @b{Ref@TeX{}} contains code to interface with AUCTeX. When this
3122 interface is turned on, both packages will interact closely. Instead of
3123 using @b{Ref@TeX{}}'s commands directly, you can then also use them
3124 indirectly as part of the AUCTeX
3125 environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
3126 needed for all of this to work. Parts of it work also with earlier
3127 versions.}. The interface is turned on with
3130 (setq reftex-plug-into-AUCTeX t)
3133 If you need finer control about which parts of the interface are used
3134 and which not, read the docstring of the variable
3135 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
3136 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
3138 The following list describes the individual parts of the interface.
3142 @findex reftex-label
3143 @vindex LaTeX-label-function, @r{AUCTeX}
3146 @findex LaTeX-section, @r{AUCTeX}
3147 @findex TeX-insert-macro, @r{AUCTeX}
3148 @b{AUCTeX calls @code{reftex-label} to insert labels}@*
3149 When a new section is created with @kbd{C-c C-s}, or a new environment
3150 is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
3151 go with it. With the interface, @code{reftex-label} is called instead.
3152 For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
3153 @b{Ref@TeX{}} will insert
3163 without further prompts.
3165 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
3166 will offer its default label which is derived from the section title.
3169 @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
3170 When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
3171 have to rescan the buffer in order to see it.
3174 @findex reftex-arg-label
3175 @findex TeX-arg-label, @r{AUCTeX function}
3176 @findex reftex-arg-ref
3177 @findex TeX-arg-ref, @r{AUCTeX function}
3178 @findex reftex-arg-cite
3179 @findex TeX-arg-cite, @r{AUCTeX function}
3180 @findex reftex-arg-index
3181 @findex TeX-arg-index, @r{AUCTeX function}
3182 @findex TeX-insert-macro, @r{AUCTeX function}
3183 @kindex C-c @key{RET}
3184 @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
3185 interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
3186 macro arguments. Internally, it uses the functions
3187 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3188 prompt for arguments which are labels, citation keys and index entries.
3189 The interface takes over these functions@footnote{@code{fset} is used to
3190 do this, which is not reversible. However, @b{Ref@TeX{}} implements the
3191 old functionality when you later decide to turn off the interface.} and
3192 supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For
3193 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
3194 will supply its label selection process (@pxref{Referencing
3198 @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
3199 @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
3202 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
3203 @subsection Style Files
3204 @cindex Style files, AUCTeX
3205 @findex TeX-add-style-hook, @r{AUCTeX}
3206 Style files are Emacs Lisp files which are evaluated by AUCTeX in
3207 association with the @code{\documentclass} and @code{\usepackage}
3208 commands of a document (@pxref{Style Files,,,auctex}). Support for
3209 @b{Ref@TeX{}} in such a style file is useful when the LaTeX style
3210 defines macros or environments connected with labels, citations, or the
3211 index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el})
3212 distributed with AUCTeX already support @b{Ref@TeX{}} in this
3215 Before calling a @b{Ref@TeX{}} function, the style hook should always
3216 test for the availability of the function, so that the style file will
3217 also work for people who do not use @b{Ref@TeX{}}.
3219 Additions made with style files in the way described below remain local
3220 to the current document. For example, if one package uses AMSTeX, the
3221 style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
3222 this will not affect other documents.
3224 @findex reftex-add-label-environments
3225 @findex reftex-add-to-label-alist
3226 A style hook may contain calls to
3227 @code{reftex-add-label-environments}@footnote{This used to be the
3228 function @code{reftex-add-to-label-alist} which is still available as an
3229 alias for compatibility.} which defines additions to
3230 @code{reftex-label-alist}. The argument taken by this function must have
3231 the same format as @code{reftex-label-alist}. The @file{amsmath.el}
3232 style file of AUCTeX for example contains the following:
3236 (TeX-add-style-hook "amsmath"
3238 (if (fboundp 'reftex-add-label-environments)
3239 (reftex-add-label-environments '(AMSTeX)))))
3244 @findex LaTeX-add-environments, @r{AUCTeX}
3245 while a package @code{myprop} defining a @code{proposition} environment
3246 with @code{\newtheorem} might use
3250 (TeX-add-style-hook "myprop"
3252 (LaTeX-add-environments '("proposition" LaTeX-env-label))
3253 (if (fboundp 'reftex-add-label-environments)
3254 (reftex-add-label-environments
3255 '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3256 ("Proposition" "Prop.") -3))))))
3260 @findex reftex-set-cite-format
3261 Similarly, a style hook may contain a call to
3262 @code{reftex-set-cite-format} to set the citation format. The style
3263 file @file{natbib.el} for the Natbib citation style does switch
3264 @b{Ref@TeX{}}'s citation format like this:
3267 (TeX-add-style-hook "natbib"
3269 (if (fboundp 'reftex-set-cite-format)
3270 (reftex-set-cite-format 'natbib))))
3273 @findex reftex-add-index-macros
3274 The hook may contain a call to @code{reftex-add-index-macros} to
3275 define additional @code{\index}-like macros. The argument must have
3276 the same format as @code{reftex-index-macros}. It may be a symbol, to
3277 trigger support for one of the builtin index packages. For example,
3278 the style @file{multind.el} contains
3281 (TeX-add-style-hook "multind"
3283 (and (fboundp 'reftex-add-index-macros)
3284 (reftex-add-index-macros '(multind)))))
3287 If you have your own package @file{myindex} which defines the
3288 following macros to be used with the LaTeX @file{index.sty} file
3290 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3291 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3294 you could write this in the style file @file{myindex.el}:
3297 (TeX-add-style-hook "myindex"
3300 '("molec" TeX-arg-index)
3301 '("aindex" TeX-arg-index))
3302 (if (fboundp 'reftex-add-index-macros)
3303 (reftex-add-index-macros
3304 '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3305 ("aindex@{*@}" "author" ?a "" nil nil))))))
3308 @findex reftex-add-section-levels
3309 Finally the hook may contain a call to @code{reftex-add-section-levels}
3310 to define additional section statements. For example, the FoilTeX class
3311 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
3312 is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
3315 (TeX-add-style-hook "foils"
3317 (if (fboundp 'reftex-add-section-levels)
3318 (reftex-add-section-levels '(("foilhead" . 3)
3319 ("rotatefoilhead" . 3))))))
3322 @node Bib-Cite, , Style Files, AUCTeX
3323 @subsection Bib-Cite
3324 @cindex @code{bib-cite}, Emacs package
3325 @cindex Emacs packages, @code{bib-cite}
3327 Once you have written a document with labels, references and citations,
3328 it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has
3329 support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3330 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3331 @code{reftex-search-document}. A somewhat fancier interface with mouse
3332 highlighting is provided (among other things) by Peter S. Galbraith's
3333 @file{bib-cite.el}. There is some overlap in the functionalities of
3334 Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with
3337 Bib-cite version 3.06 and later can be configured so that bib-cite's
3338 mouse functions use @b{Ref@TeX{}} for displaying references and citations.
3339 This can be useful in particular when working with the LaTeX @code{xr}
3340 package or with an explicit @code{thebibliography} environment (rather
3341 than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To
3342 make use of this feature, try
3344 @vindex bib-cite-use-reftex-view-crossref
3346 (setq bib-cite-use-reftex-view-crossref t)
3350 @node Problems and Work-Arounds, Imprint, Optimizations, Top
3351 @section Problems and Work-arounds
3352 @cindex Problems and work-arounds
3356 @b{LaTeX commands}@*
3357 @cindex LaTeX commands, not found
3358 @code{\input}, @code{\include}, and @code{\section} (etc.) statements
3359 have to be first on a line (except for white space).
3362 @b{Commented regions}@*
3363 @cindex Labels, commented out
3364 @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
3365 make duplicates of such labels. This is considered to be a feature.
3368 @b{Wrong section numbers}@*
3369 @cindex Section numbers, wrong
3370 @vindex reftex-enable-partial-scans
3371 When using partial scans (@code{reftex-enable-partial-scans}), the section
3372 numbers in the table of contents may eventually become wrong. A full
3376 @b{Local settings}@*
3377 @cindex Settings, local
3378 @findex reftex-add-label-environments
3379 @findex reftex-set-cite-format
3380 @findex reftex-add-section-levels
3381 The label environment definitions in @code{reftex-label-alist} are
3382 global and apply to all documents. If you need to make definitions
3383 local to a document, because they would interfere with settings in other
3384 documents, you should use AUCTeX and set up style files with calls to
3385 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3386 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3387 Settings made with these functions remain local to the current
3388 document. @xref{AUCTeX}.
3391 @b{Funny display in selection buffer}@*
3392 @cindex @code{x-symbol}, Emacs package
3393 @cindex Emacs packages, @code{x-symbol}
3394 @cindex @code{isotex}, Emacs package
3395 @cindex Emacs packages, @code{isotex}
3396 @cindex @code{iso-cvt}, Emacs package
3397 @cindex Emacs packages, @code{iso-cvt}
3398 When using packages which make the buffer representation of a file
3399 different from its disk representation (e.g. x-symbol, isotex,
3400 iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
3401 reflects the disk state of a file. This happens only in @emph{unvisited}
3402 parts of a multifile document, because @b{Ref@TeX{}} visits these files
3403 literally for speed reasons. Then both short context and section
3404 headings may look different from what you usually see on your screen.
3405 In rare cases @code{reftex-toc} may have problems to jump to an affected
3406 section heading. There are three possible ways to deal with
3410 @vindex reftex-keep-temporary-buffers
3411 @code{(setq reftex-keep-temporary-buffers t)}@*
3412 This implies that @b{Ref@TeX{}} will load all parts of a multifile
3413 document into Emacs (i.e. there won't be any temporary buffers).
3415 @vindex reftex-initialize-temporary-buffers
3416 @code{(setq reftex-initialize-temporary-buffers t)}@*
3417 This means full initialization of temporary buffers. It involves
3418 a penalty when the same unvisited file is used for lookup often.
3420 Set @code{reftex-initialize-temporary-buffers} to a list of hook
3421 functions doing a minimal initialization.
3423 @vindex reftex-refontify-context
3424 See also the variable @code{reftex-refontify-context}.
3427 @b{Labels as arguments to \begin}@*
3428 @cindex @code{pf}, LaTeX package
3429 @cindex LaTeX packages, @code{pf}
3430 Some packages use an additional argument to a @code{\begin} macro
3431 to specify a label. E.g. Lamport's @file{pf.sty} uses both
3433 \step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
3439 We need to trick @b{Ref@TeX{}} into swallowing this:
3443 ;; Configuration for Lamport's pf.sty
3444 (setq reftex-label-alist
3445 '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3446 ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3451 The first line is just a normal configuration for a macro. For the
3452 @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
3453 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3454 argument (which really is a second argument to the macro @code{\begin})
3455 as a label of type @code{?p}. Argument count for this macro starts only
3456 after the @samp{@{step+@}}, also when specifying how to get
3460 @b{Idle timers in XEmacs}@*
3461 @cindex Idle timer restart
3462 @vindex reftex-use-itimer-in-xemacs
3463 In XEmacs, idle timer restart does not work reliably after fast
3464 keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command
3465 hook to start the timer used for automatic crossref information. When
3466 this bug gets fixed, a real idle timer can be requested with
3468 (setq reftex-use-itimer-in-xemacs t)
3474 @cindex Key bindings, problems with Viper mode
3475 @findex viper-harness-minor-mode
3476 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3477 @b{Ref@TeX{}}'s keymaps with
3480 (viper-harness-minor-mode "reftex")
3486 @node Imprint, Commands, Problems and Work-Arounds, Top
3490 @cindex Acknowledgments
3493 @cindex @code{http}, @b{Ref@TeX{}} home page
3494 @cindex @code{ftp}, @b{Ref@TeX{}} site
3496 Ref@TeX{} was written by @i{Carsten Dominik}
3497 @email{dominik@@science.uva.nl}, with contributions by @i{Stephen
3498 Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see
3499 the @value{MAINTAINERSITE} for detailed information.
3501 If you have questions about Ref@TeX{}, you can send email to the
3502 @value{SUPPORTADDRESS}. If you want to contribute code or ideas, write
3503 to the @value{DEVELADDRESS}. And in the rare case of finding a bug,
3504 please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a
3505 bug report with useful information about your setup. Remember to add
3506 essential information like a recipe for reproducing the bug, what you
3507 expected to happen, and what actually happened. Send the bug report to
3508 the @value{BUGADDRESS}.
3510 There are also several Usenet groups which have competent readers who
3511 might be able to help: @code{comp.emacs}, @code{gnu.emacs.help},
3512 @code{comp.emacs.xemacs}, and @code{comp.text.tex}.
3514 @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
3515 It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
3516 21.x users want to install the corresponding plugin package which is
3517 available from the @value{XEMACSFTP}. See the XEmacs 21.x
3518 documentation on package installation for details.
3520 Users of earlier Emacs distributions (including Emacs 19) can get a
3521 @b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that
3522 the Emacs 19 version supports many but not all features described in
3525 Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
3526 developing it with their reports. In particular thanks to @i{Ralf
3527 Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton,
3528 Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai
3529 Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan
3530 Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz,
3531 Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan
3532 Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha,
3533 Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan
3534 Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}.
3537 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3540 Finally thanks to @i{Uwe Bolick} who first got me interested in
3541 supporting LaTeX labels and references with an editor (which was
3542 MicroEmacs at the time).
3544 @node Commands, Options, Imprint, Top
3546 @cindex Commands, list of
3548 Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
3549 LaTeX files. Command which are executed from the special buffers are
3550 not described here. All commands are available from the @code{Ref}
3551 menu. See @xref{Key Bindings}.
3553 @deffn Command reftex-toc
3554 Show the table of contents for the current document. When called with
3555 one ore two @kbd{C-u} prefixes, rescan the document first.
3558 @deffn Command reftex-label
3559 Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
3560 document rescan first.
3563 @deffn Command reftex-reference
3564 Start a selection process to select a label, and insert a reference to
3565 it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
3568 @deffn Command reftex-citation
3569 Make a citation using BibTeX database files. After prompting for a regular
3570 expression, scans the buffers with BibTeX entries (taken from the
3571 @code{\bibliography} command or a @code{thebibliography} environment)
3572 and offers the matching entries for selection. The selected entry is
3573 formatted according to @code{reftex-cite-format} and inserted into the
3575 When called with a @kbd{C-u} prefix, prompt for optional arguments in
3576 cite macros. When called with a numeric prefix, make that many citations.
3577 When called with point inside the braces of a @code{\cite} command, it
3578 will add another key, ignoring the value of
3579 @code{reftex-cite-format}. @*
3580 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3581 as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
3582 both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
3583 on knows citation keys is possible. @samp{=} is a good regular
3584 expression to match all entries in all files.
3587 @deffn Command reftex-index
3588 Query for an index macro and insert it along with its arguments. The
3589 index macros available are those defined in @code{reftex-index-macro} or
3590 by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
3591 style file. @b{Ref@TeX{}} provides completion for the index tag and the
3592 index key, and will prompt for other arguments.
3595 @deffn Command reftex-index-selection-or-word
3596 Put current selection or the word near point into the default index
3597 macro. This uses the information in @code{reftex-index-default-macro}
3598 to make an index entry. The phrase indexed is the current selection or
3599 the word near point. When called with one @kbd{C-u} prefix, let the
3600 user have a chance to edit the index entry. When called with 2
3601 @kbd{C-u} as prefix, also ask for the index macro and other stuff. When
3602 called inside TeX math mode as determined by the @file{texmathp.el}
3603 library which is part of AUCTeX, the string is first processed with the
3604 @code{reftex-index-math-format}, which see.
3607 @deffn Command reftex-index-phrase-selection-or-word
3608 Add current selection or the word at point to the phrases buffer.
3609 When you are in transient-mark-mode and the region is active, the
3610 selection will be used - otherwise the word at point.
3611 You get a chance to edit the entry in the phrases buffer - to save the
3612 buffer and return to the LaTeX document, finish with @kbd{C-c C-c}.
3615 @deffn Command reftex-index-visit-phrases-buffer
3616 Switch to the phrases buffer, initialize if empty.
3619 @deffn Command reftex-index-phrases-apply-to-region
3620 Index all index phrases in the current region.
3621 This works exactly like global indexing from the index phrases buffer,
3622 but operation is restricted to the current region.
3625 @deffn Command reftex-display-index
3626 Display a buffer with an index compiled from the current document.
3627 When the document has multiple indices, first prompts for the correct one.
3628 When index support is turned off, offer to turn it on.
3629 With one or two @kbd{C-u} prefixes, rescan document first.
3630 With prefix 2, restrict index to current document section.
3631 With prefix 3, restrict index to active region.
3634 @deffn Command reftex-view-crossref
3635 View cross reference of macro at point. Point must be on the @var{key}
3636 argument. Works with the macros @code{\label}, @code{\ref},
3637 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3638 these. Where it makes sense, subsequent calls show additional
3639 locations. See also the variable @code{reftex-view-crossref-extra} and
3640 the command @code{reftex-view-crossref-from-bibtex}. With one or two
3641 @kbd{C-u} prefixes, enforce rescanning of the document. With argument
3642 2, select the window showing the cross reference.
3645 @deffn Command reftex-view-crossref-from-bibtex
3646 View location in a LaTeX document which cites the BibTeX entry at point.
3647 Since BibTeX files can be used by many LaTeX documents, this function
3648 prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
3649 link to a document, call the function with a prefix arg. Calling
3650 this function several times find successive citation locations.
3653 @deffn Command reftex-create-tags-file
3654 Create TAGS file by running @code{etags} on the current document. The
3655 TAGS file is also immediately visited with
3656 @code{visit-tags-table}.
3659 @deffn Command reftex-grep-document
3660 Run grep query through all files related to this document.
3661 With prefix arg, force to rescan document.
3662 No active TAGS table is required.
3665 @deffn Command reftex-search-document
3666 Regexp search through all files of the current document.
3667 Starts always in the master file. Stops when a match is found.
3668 No active TAGS table is required.
3671 @deffn Command reftex-query-replace-document
3672 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3673 document. With prefix arg, replace only word-delimited matches. No
3674 active TAGS table is required.
3677 @deffn Command reftex-isearch-minor-mode
3678 Toggle a minor mode which enables incremental search to work globally
3679 on the entire multifile document. Files will be searched in th
3680 sequence they appear in the document.
3683 @deffn Command reftex-goto-label
3684 Prompt for a label (with completion) and jump to the location of this
3685 label. Optional prefix argument @var{other-window} goes to the label in
3690 @deffn Command reftex-change-label
3691 Query replace @var{from} with @var{to} in all @code{\label} and
3692 @code{\ref} commands. Works on the entire multifile document. No
3693 active TAGS table is required.
3696 @deffn Command reftex-renumber-simple-labels
3697 Renumber all simple labels in the document to make them sequentially.
3698 Simple labels are the ones created by RefTeX, consisting only of the
3699 prefix and a number. After the command completes, all these labels will
3700 have sequential numbers throughout the document. Any references to the
3701 labels will be changed as well. For this, @b{Ref@TeX{}} looks at the
3702 arguments of any macros which either start or end with the string
3703 @samp{ref}. This command should be used with care, in particular in
3704 multifile documents. You should not use it if another document refers
3705 to this one with the @code{xr} package.
3708 @deffn Command reftex-find-duplicate-labels
3709 Produce a list of all duplicate labels in the document.
3712 @deffn Command reftex-create-bibtex-file
3713 Create a new BibTeX database file with all entries referenced in document.
3714 The command prompts for a filename and writes the collected entries to
3715 that file. Only entries referenced in the current document with
3716 any @code{\cite}-like macros are used.
3717 The sequence in the new file is the same as it was in the old database.
3720 @deffn Command reftex-customize
3721 Run the customize browser on the @b{Ref@TeX{}} group.
3723 @deffn Command reftex-show-commentary
3724 Show the commentary section from @file{reftex.el}.
3726 @deffn Command reftex-info
3727 Run info on the top @b{Ref@TeX{}} node.
3729 @deffn Command reftex-parse-document
3730 Parse the entire document in order to update the parsing information.
3732 @deffn Command reftex-reset-mode
3733 Enforce rebuilding of several internal lists and variables. Also
3734 removes the parse file associated with the current document.
3737 @node Options, Keymaps and Hooks, Commands, Top
3738 @chapter Options, Keymaps, Hooks
3739 @cindex Options, list of
3741 Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All
3742 variables have customize support - so if you are not familiar with Emacs
3743 Lisp (and even if you are) you might find it more comfortable to use
3744 @code{customize} to look at and change these variables. @kbd{M-x
3745 reftex-customize} will get you there.
3748 * Options (Table of Contents)::
3749 * Options (Defining Label Environments)::
3750 * Options (Creating Labels)::
3751 * Options (Referencing Labels)::
3752 * Options (Creating Citations)::
3753 * Options (Index Support)::
3754 * Options (Viewing Cross-References)::
3755 * Options (Finding Files)::
3756 * Options (Optimizations)::
3757 * Options (Fontification)::
3761 @node Options (Table of Contents), Options (Defining Label Environments), , Options
3762 @section Table of Contents
3763 @cindex Options, table of contents
3764 @cindex Table of contents, options
3766 @defopt reftex-include-file-commands
3767 List of LaTeX commands which input another file.
3768 The file name is expected after the command, either in braces or separated
3772 @defopt reftex-max-section-depth
3773 Maximum depth of section levels in document structure.
3774 Standard LaTeX needs 7, default is 12.
3777 @defopt reftex-section-levels
3778 Commands and levels used for defining sections in the document. The
3779 @code{car} of each cons cell is the name of the section macro. The
3780 @code{cdr} is a number indicating its level. A negative level means the
3781 same as the positive value, but the section will never get a number.
3782 The @code{cdr} may also be a function which then has to return the
3783 level. This list is also used for promotion and demotion of sectioning
3784 commands. If you are using a document class which has several sets of
3785 sectioning commands, promotion only works correctly if this list is
3786 sorted first by set, then within each set by level. The promotion
3787 commands always select the nearest entry with the correct new level.
3791 @defopt reftex-toc-max-level
3792 The maximum level of toc entries which will be included in the TOC.
3793 Section headings with a bigger level will be ignored. In RefTeX,
3794 chapters are level 1, sections level 2 etc. This variable can be
3795 changed from within the @file{*toc*} buffer with the @kbd{t} key.
3798 @defopt reftex-part-resets-chapter
3799 Non-@code{nil} means, @code{\part} is like any other sectioning command.
3800 This means, part numbers will be included in the numbering of chapters, and
3801 chapter counters will be reset for each part.
3802 When @code{nil} (the default), parts are special, do not reset the
3803 chapter counter and also do not show up in chapter numbers.
3806 @defopt reftex-auto-recenter-toc
3807 Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
3808 When active, the @file{*TOC*} window will always show the section you
3809 are currently working in. Recentering happens whenever Emacs is idle for
3810 more than @code{reftex-idle-time} seconds.
3812 Value @code{t} means, turn on immediately when RefTeX gets started. Then,
3813 recentering will work for any toc window created during the session.
3815 Value @code{frame} (the default) means, turn automatic recentering on
3816 only while the dedicated TOC frame does exist, and do the recentering
3817 only in that frame. So when creating that frame (with @kbd{d} key in an
3818 ordinary TOC window), the automatic recentering is turned on. When the
3819 frame gets destroyed, automatic recentering is turned off again.
3821 This feature can be turned on and off from the menu
3825 @defopt reftex-toc-split-windows-horizontally
3826 Non-@code{nil} means, create TOC window by splitting window
3827 horizontally. The default is to split vertically.
3830 @defopt reftex-toc-split-windows-fraction
3831 Fraction of the width or height of the frame to be used for TOC window.
3834 @defopt reftex-toc-keep-other-windows
3835 Non-@code{nil} means, split the selected window to display the
3836 @file{*toc*} buffer. This helps to keep the window configuration, but
3837 makes the @file{*toc*} small. When @code{nil}, all other windows except
3838 the selected one will be deleted, so that the @file{*toc*} window fills
3842 @defopt reftex-toc-include-file-boundaries
3843 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3844 This flag can be toggled from within the @file{*toc*} buffer with the
3848 @defopt reftex-toc-include-labels
3849 Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
3850 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3854 @defopt reftex-toc-include-index-entries
3855 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3856 This flag can be toggled from within the @file{*toc*} buffer with the
3860 @defopt reftex-toc-include-context
3861 Non-@code{nil} means, include context with labels in the @file{*toc*}
3862 buffer. Context will only be shown if the labels are visible as well.
3863 This flag can be toggled from within the @file{*toc*} buffer with the
3867 @defopt reftex-toc-follow-mode
3868 Non-@code{nil} means, point in @file{*toc*} buffer (the
3869 table-of-contents buffer) will cause other window to follow. The other
3870 window will show the corresponding part of the document. This flag can
3871 be toggled from within the @file{*toc*} buffer with the @kbd{f}
3875 @deffn {Normal Hook} reftex-toc-mode-hook
3876 Normal hook which is run when a @file{*toc*} buffer is
3880 @deffn Keymap reftex-toc-map
3881 The keymap which is active in the @file{*toc*} buffer.
3882 (@pxref{Table of Contents}).
3885 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
3886 @section Defining Label Environments
3887 @cindex Options, defining label environments
3888 @cindex Defining label environments, options
3890 @defopt reftex-default-label-alist-entries
3891 Default label alist specifications. It is a list of symbols with
3892 associations in the constant @code{reftex-label-alist-builtin}.
3893 @code{LaTeX} should always be the last entry.
3896 @defopt reftex-label-alist
3897 Set this variable to define additions and changes to the defaults in
3898 @code{reftex-default-label-alist-entries}. The only things you
3899 @emph{must not} change is that @code{?s} is the type indicator for
3900 section labels, and @key{SPC} for the @code{any} label type. These are
3901 hard-coded at other places in the code.
3903 The value of the variable must be a list of items. Each item is a list
3904 itself and has the following structure:
3907 (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
3908 @var{context-method} (@var{magic-word} ... ) @var{toc-level})
3911 Each list entry describes either an environment carrying a counter for
3912 use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
3913 label as (or inside) one of its arguments. The elements of each list
3917 @item @var{env-or-macro}
3918 Name of the environment (like @samp{table}) or macro (like
3919 @samp{\myfig}). For macros, indicate the arguments, as in
3920 @samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
3921 arguments, a star to mark the label argument, if any. The macro does
3922 not have to have a label argument - you could also use
3923 @samp{\label@{...@}} inside one of its arguments.
3925 Special names: @code{section} for section labels, @code{any} to define a
3926 group which contains all labels.
3928 This may also be a function to do local parsing and identify point to be
3929 in a non-standard label environment. The function must take an
3930 argument @var{bound} and limit backward searches to this value. It
3931 should return either nil or a cons cell @code{(@var{function}
3932 . @var{position})} with the function symbol and the position where the
3933 special environment starts. See the Info documentation for an
3936 Finally this may also be @code{nil} if the entry is only meant to change
3937 some settings associated with the type indicator character (see
3940 @item @var{type-key}
3941 Type indicator character, like @code{?t}, must be a printable ASCII
3942 character. The type indicator is a single character which defines a
3943 label type. Any label inside the environment or macro is assumed to
3944 belong to this type. The same character may occur several times in this
3945 list, to cover cases in which different environments carry the same
3946 label type (like @code{equation} and @code{eqnarray}). If the type
3947 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
3948 the macro defines neutral labels just like @code{\label}. In this case
3949 the reminder of this entry is ignored.
3951 @item @var{label-prefix}
3952 Label prefix string, like @samp{tab:}. The prefix is a short string
3953 used as the start of a label. It may be the empty string. The prefix
3954 may contain the following @samp{%} escapes:
3957 %f Current file name, directory and extension stripped.
3958 %F Current file name relative to master file directory.
3959 %m Master file name, directory and extension stripped.
3960 %M Directory name (without path) where master file is located.
3961 %u User login name, on systems which support this.
3962 %S A section prefix derived with variable @code{reftex-section-prefixes}.
3966 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
3969 @item @var{reference-format}
3970 Format string for reference insert in buffer. @samp{%s} will be
3971 replaced by the label. When the format starts with @samp{~}, this
3972 @samp{~} will only be inserted when the character before point is
3973 @emph{not} a whitespace.
3975 @item @var{context-method}
3976 Indication on how to find the short context.
3979 If @code{nil}, use the text following the @samp{\label@{...@}} macro.
3984 the section heading for section labels.
3986 text following the @samp{\begin@{...@}} statement of environments (not
3987 a good choice for environments like eqnarray or enumerate, where one has
3988 several labels in a single environment).
3990 text after the macro name (starting with the first arg) for
3994 If an integer, use the nth argument of the macro. As a special case,
3995 1000 means to get text after the last macro argument.
3997 If a string, use as regexp to search @emph{backward} from the label.
3998 Context is then the text following the end of the match. E.g. putting
3999 this to @samp{\\caption[[@{]} will use the caption in a figure or table
4000 environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
4003 If any of @code{caption}, @code{item}, @code{eqnarray-like},
4004 @code{alignat-like}, this symbol will internally be translated into an
4005 appropriate regexp (see also the variable
4006 @code{reftex-default-context-regexps}).
4008 If a function, call this function with the name of the environment/macro
4009 as argument. On call, point will be just after the @code{\label} macro.
4010 The function is expected to return a suitable context string. It should
4011 throw an exception (error) when failing to find context. As an example,
4012 here is a function returning the 10 chars following the label macro as
4016 (defun my-context-function (env-or-mac)
4017 (if (> (point-max) (+ 10 (point)))
4018 (buffer-substring (point) (+ 10 (point)))
4019 (error "Buffer too small")))
4023 Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
4024 menu, and to derive a label string. If you want to use a different
4025 method for each of these, specify them as a dotted pair.
4026 E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
4027 display, and text from the default position (@code{t}) to derive a label
4028 string. This is actually used for section labels.
4030 @item @var{magic-word-list}
4031 List of magic words which identify a reference to be of this type. If
4032 the word before point is equal to one of these words when calling
4033 @code{reftex-reference}, the label list offered will be automatically
4034 restricted to labels of the correct type. If the first element of this
4035 word--list is the symbol `regexp', the strings are interpreted as regular
4038 @item @var{toc-level}
4039 The integer level at which this environment should be added to the table
4040 of contents. See also @code{reftex-section-levels}. A positive value
4041 will number the entries mixed with the sectioning commands of the same
4042 level. A negative value will make unnumbered entries. Useful only for
4043 theorem-like environments which structure the document. Will be ignored
4044 for macros. When omitted or @code{nil}, no TOC entries will be
4048 If the type indicator characters of two or more entries are the same,
4049 @b{Ref@TeX{}} will use
4052 the first non-@code{nil} format and prefix
4054 the magic words of all involved entries.
4057 Any list entry may also be a symbol. If that has an association in
4058 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
4059 spliced into the list. However, builtin defaults should normally be set
4060 with the variable @code{reftex-default-label-alist-entries}.
4063 @defopt reftex-section-prefixes
4064 Prefixes for section labels. When the label prefix given in an entry in
4065 @code{reftex-label-alist} contains @samp{%S}, this list is used to
4066 determine the correct prefix string depending on the current section
4067 level. The list is an alist, with each entry of the form
4068 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
4069 names like @samp{chapter}, integer section levels (as given in
4070 @code{reftex-section-levels}), and @code{t} for the default.
4073 @defopt reftex-default-context-regexps
4074 Alist with default regular expressions for finding context. The emacs
4075 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
4076 to calculate the final regular expression - so @samp{%s} will be
4077 replaced with the environment or macro.
4080 @defopt reftex-trust-label-prefix
4081 Non-@code{nil} means, trust the label prefix when determining label type.
4082 It is customary to use special label prefixes to distinguish different label
4083 types. The label prefixes have no syntactic meaning in LaTeX (unless
4084 special packages like fancyref) are being used. RefTeX can and by
4085 default does parse around each label to detect the correct label type,
4086 but this process can be slow when a document contains thousands of
4087 labels. If you use label prefixes consistently, you may speed up
4088 document parsing by setting this variable to a non-nil value. RefTeX
4089 will then compare the label prefix with the prefixes found in
4090 `reftex-label-alist' and derive the correct label type in this way.
4091 Possible values for this option are:
4094 t @r{This means to trust any label prefixes found.}
4095 regexp @r{If a regexp, only prefixes matched by the regexp are trusted.}
4096 list @r{List of accepted prefixes, as strings. The colon is part of}
4097 @r{the prefix, e.g. ("fn:" "eqn:" "item:").}
4098 nil @r{Never trust a label prefix.}
4100 The only disadvantage of using this feature is that the label context
4101 displayed in the label selection buffer along with each label is
4102 simply some text after the label definition. This is no problem if you
4103 place labels keeping this in mind (e.g. @i{before} the equation, @i{at
4104 the beginning} of a fig/tab caption ...). Anyway, it is probably best
4105 to use the regexp or the list value types to fine-tune this feature.
4106 For example, if your document contains thousands of footnotes with
4107 labels fn:xxx, you may want to set this variable to the value "^fn:$" or
4108 ("fn:"). Then RefTeX will still do extensive parsing for any
4109 non-footnote labels.
4112 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
4113 @section Creating Labels
4114 @cindex Options, creating labels
4115 @cindex Creating labels, options
4117 @defopt reftex-insert-label-flags
4118 Flags governing label insertion. The value has the form
4121 (@var{derive} @var{prompt})
4124 If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
4125 label from context. A section label for example will be derived from
4126 the section heading. The conversion of the context to a valid label is
4127 governed by the specifications given in
4128 @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
4129 the default label will consist of the prefix and a unique number, like
4132 If @var{prompt} is @code{t}, the user will be prompted for a label
4133 string. When @var{prompt} is @code{nil}, the default label will be
4134 inserted without query.
4136 So the combination of @var{derive} and @var{prompt} controls label
4137 insertion. Here is a table describing all four possibilities:
4141 @var{derive} @var{prompt} @var{action}
4142 -----------------------------------------------------------
4143 nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
4144 nil t @r{Prompt for label.}
4145 t nil @r{Derive a label from context and insert. No query.}
4146 t t @r{Derive a label from context, prompt for confirmation.}
4150 Each flag may be set to @code{t}, @code{nil}, or a string of label type
4151 letters indicating the label types for which it should be true. Thus,
4152 the combination may be set differently for each label type. The default
4153 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
4154 headings (with confirmation). Prompt for figure and table labels. Use
4155 simple labels without confirmation for everything else.
4157 The available label types are: @code{s} (section), @code{f} (figure),
4158 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4159 (footnote), @code{N} (endnote) plus any definitions in
4160 @code{reftex-label-alist}.
4163 @deffn Hook reftex-format-label-function
4164 If non-@code{nil}, should be a function which produces the string to
4165 insert as a label definition. The function will be called with two
4166 arguments, the @var{label} and the @var{default-format} (usually
4167 @samp{\label@{%s@}}). It should return the string to insert into the
4171 @deffn Hook reftex-string-to-label-function
4172 Function to turn an arbitrary string into a valid label.
4173 @b{Ref@TeX{}}'s default function uses the variable
4174 @code{reftex-derive-label-parameters}.
4177 @deffn Hook reftex-translate-to-ascii-function
4178 Filter function which will process a context string before it is used to
4179 derive a label from it. The intended application is to convert ISO or
4180 Mule characters into something valid in labels. The default function
4181 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
4182 characters. X-Symbol (>=2.6) sets this variable to the much more
4183 general @code{x-symbol-translate-to-ascii}.
4186 @defopt reftex-derive-label-parameters
4187 Parameters for converting a string into a label. This variable is a
4188 list of the following items:
4191 Number of words to use.
4193 Maximum number of characters in a label string.
4195 @code{nil}: Throw away any words containing characters invalid in labels.@*
4196 @code{t}: Throw away only the invalid characters, not the whole word.
4198 @code{nil}: Never abbreviate words.@*
4199 @code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
4200 @code{1}: Abbreviate words if necessary to shorten label string.
4201 @item @var{separator}
4202 String separating different words in the label.
4203 @item @var{ignorewords}
4204 List of words which should not be part of labels.
4205 @item @var{downcase}
4206 @code{t}: Downcase words before putting them into the label.@*
4210 @defopt reftex-label-illegal-re
4211 Regexp matching characters not valid in labels.
4214 @defopt reftex-abbrev-parameters
4215 Parameters for abbreviation of words. A list of four parameters.
4217 @item @var{min-chars}
4218 Minimum number of characters remaining after abbreviation.
4219 @item @var{min-kill}
4220 Minimum number of characters to remove when abbreviating words.
4222 Character class before abbrev point in word.
4224 Character class after abbrev point in word.
4228 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
4229 @section Referencing Labels
4230 @cindex Options, referencing labels
4231 @cindex Referencing labels, options
4233 @defopt reftex-label-menu-flags
4234 List of flags governing the label menu makeup. The flags are:
4236 @item @var{table-of-contents}
4237 Show the labels embedded in a table of context.
4238 @item @var{section-numbers}
4239 Include section numbers (like 4.1.3) in table of contents.
4240 @item @var{counters}
4241 Show counters. This just numbers the labels in the menu.
4242 @item @var{no-context}
4243 Non-@code{nil} means do @emph{not} show the short context.
4245 Follow full context in other window.
4246 @item @var{show-commented}
4247 Show labels from regions which are commented out.
4248 @item @var{match-everywhere}
4250 @item @var{show-files}
4251 Show begin and end of included files.
4254 Each of these flags can be set to @code{t} or @code{nil}, or to a string
4255 of type letters indicating the label types for which it should be true.
4256 These strings work like character classes in regular expressions. Thus,
4257 setting one of the flags to @samp{"sf"} makes the flag true for section
4258 and figure labels, @code{nil} for everything else. Setting it to
4259 @samp{"^sf"} makes it the other way round.
4261 The available label types are: @code{s} (section), @code{f} (figure),
4262 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4263 (footnote), plus any definitions in @code{reftex-label-alist}.
4265 Most options can also be switched from the label menu itself - so if you
4266 decide here to not have a table of contents in the label menu, you can
4267 still get one interactively during selection from the label menu.
4270 @defopt reftex-multiref-punctuation
4271 Punctuation strings for multiple references. When marking is used in
4272 the selection buffer to select several references, this variable
4273 associates the 3 marking characters @samp{,-+} with prefix strings to be
4274 inserted into the buffer before the corresponding @code{\ref} macro.
4275 This is used to string together whole reference sets, like
4276 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
4277 @code{reftex-reference}.
4280 @defopt reftex-vref-is-default
4281 Non-@code{nil} means, the varioref macro @code{\vref} is used as
4282 default. In the selection buffer, the @kbd{v} key toggles the reference
4283 macro between @code{\ref} and @code{\vref}. The value of this variable
4284 determines the default which is active when entering the selection
4285 process. Instead of @code{nil} or @code{t}, this may also be a string
4286 of type letters indicating the label types for which it should be
4290 @defopt reftex-fref-is-default
4291 Non-@code{nil} means, the fancyref macro @code{\fref} is used as
4292 default. In the selection buffer, the @kbd{V} key toggles the reference
4293 macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of
4294 this variable determines the default which is active when entering the
4295 selection process. Instead of @code{nil} or @code{t}, this may also be
4296 a string of type letters indicating the label types for which it should
4300 @deffn Hook reftex-format-ref-function
4301 If non-@code{nil}, should be a function which produces the string to
4302 insert as a reference. Note that the insertion format can also be
4303 changed with @code{reftex-label-alist}. This hook also is used by the
4304 special commands to insert @code{\vref} and @code{\fref} references, so
4305 even if you set this, your setting will be ignored by the special
4306 commands. The function will be called with two arguments, the
4307 @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
4308 It should return the string to insert into the buffer.
4311 @defopt reftex-level-indent
4312 Number of spaces to be used for indentation per section level.
4315 @defopt reftex-guess-label-type
4316 Non-@code{nil} means, @code{reftex-reference} will try to guess the
4317 label type. To do that, @b{Ref@TeX{}} will look at the word before the
4318 cursor and compare it with the magic words given in
4319 @code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will
4320 immediately offer the correct label menu - otherwise it will prompt you
4321 for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}
4322 will always prompt for a label type.
4325 @deffn {Normal Hook} reftex-display-copied-context-hook
4326 Normal Hook which is run before context is displayed anywhere. Designed
4327 for @w{@code{X-Symbol}}, but may have other uses as well.
4330 @deffn Hook reftex-pre-refontification-functions
4331 @code{X-Symbol} specific hook. Probably not useful for other purposes.
4332 The functions get two arguments, the buffer from where the command
4333 started and a symbol indicating in what context the hook is
4337 @deffn {Normal Hook} reftex-select-label-mode-hook
4338 Normal hook which is run when a selection buffer enters
4339 @code{reftex-select-label-mode}.
4342 @deffn Keymap reftex-select-label-map
4343 The keymap which is active in the labels selection process
4344 (@pxref{Referencing Labels}).
4347 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
4348 @section Creating Citations
4349 @cindex Options, creating citations
4350 @cindex Creating citations, options
4352 @defopt reftex-bibliography-commands
4353 LaTeX commands which specify the BibTeX databases to use with the document.
4356 @defopt reftex-bibfile-ignore-regexps
4357 List of regular expressions to exclude files in
4358 @code{\\bibliography@{..@}}. File names matched by any of these regexps
4359 will not be parsed. Intended for files which contain only
4360 @code{@@string} macro definitions and the like, which are ignored by
4361 @b{Ref@TeX{}} anyway.
4364 @defopt reftex-default-bibliography
4365 List of BibTeX database files which should be used if none are specified.
4366 When @code{reftex-citation} is called from a document with neither
4367 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4368 environment, @b{Ref@TeX{}} will scan these files instead. Intended for
4369 using @code{reftex-citation} in non-LaTeX files. The files will be
4370 searched along the BIBINPUTS or TEXBIB path.
4373 @defopt reftex-sort-bibtex-matches
4374 Sorting of the entries found in BibTeX databases by reftex-citation.
4377 nil @r{Do not sort entries.}
4378 author @r{Sort entries by author name.}
4379 year @r{Sort entries by increasing year.}
4380 reverse-year @r{Sort entries by decreasing year.}
4384 @defopt reftex-cite-format
4385 The format of citations to be inserted into the buffer. It can be a
4386 string, an alist or a symbol. In the simplest case this is just the string
4387 @samp{\cite@{%l@}}, which is also the default. See the definition of
4388 @code{reftex-cite-format-builtin} for more complex examples.
4390 If @code{reftex-cite-format} is a string, it will be used as the format.
4391 In the format, the following percent escapes will be expanded.
4395 The BibTeX label of the citation.
4397 List of author names, see also @code{reftex-cite-punctuation}.
4399 Like %a, but abbreviate more than 2 authors like Jones et al.
4401 First author name only.
4403 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4404 @samp{%E} work a well).
4407 It is also possible to access all other BibTeX database fields:
4410 %b booktitle %c chapter %d edition %h howpublished
4411 %i institution %j journal %k key %m month
4412 %n number %o organization %p pages %P first page
4413 %r address %s school %u publisher %t title
4415 %B booktitle, abbreviated %T title, abbreviated
4419 Usually, only @samp{%l} is needed. The other stuff is mainly for the
4420 echo area display, and for @code{(setq reftex-comment-citations t)}.
4422 @samp{%<} as a special operator kills punctuation and space around it
4423 after the string has been formatted.
4425 A pair of square brackets indicates an optional argument, and RefTeX
4426 will prompt for the values of these arguments.
4428 Beware that all this only works with BibTeX database files. When
4429 citations are made from the @code{\bibitems} in an explicit
4430 @code{thebibliography} environment, only @samp{%l} is available.
4432 If @code{reftex-cite-format} is an alist of characters and strings, the
4433 user will be prompted for a character to select one of the possible
4436 In order to configure this variable, you can either set
4437 @code{reftex-cite-format} directly yourself or set it to the
4438 @emph{symbol} of one of the predefined styles. The predefined symbols
4439 are those which have an association in the constant
4440 @code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
4444 @deffn Hook reftex-format-cite-function
4445 If non-@code{nil}, should be a function which produces the string to
4446 insert as a citation. Note that the citation format can also be changed
4447 with the variable @code{reftex-cite-format}. The function will be
4448 called with two arguments, the @var{citation-key} and the
4449 @var{default-format} (taken from @code{reftex-cite-format}). It should
4450 return the string to insert into the buffer.
4453 @defopt reftex-cite-prompt-optional-args
4454 Non-@code{nil} means, prompt for empty optional arguments in cite macros.
4455 When an entry in @code{reftex-cite-format} ist given with square brackets to
4456 indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
4457 prompt for values. Possible values are:
4459 nil @r{Never prompt for optional arguments}
4461 maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example
4462 Unnecessary empty optional arguments are removed before insertion into
4463 the buffer. See @code{reftex-cite-cleanup-optional-args}.
4466 @defopt reftex-cite-cleanup-optional-args
4467 Non-@code{nil} means, remove empty optional arguments from cite macros
4471 @defopt reftex-comment-citations
4472 Non-@code{nil} means add a comment for each citation describing the full
4473 entry. The comment is formatted according to
4474 @code{reftex-cite-comment-format}.
4477 @defopt reftex-cite-comment-format
4478 Citation format used for commented citations. Must @emph{not} contain
4479 @samp{%l}. See the variable @code{reftex-cite-format} for possible
4483 @defopt reftex-cite-punctuation
4484 Punctuation for formatting of name lists in citations. This is a list
4488 normal names separator, like @samp{, } in Jones, Brown and Miller
4490 final names separator, like @samp{ and } in Jones, Brown and Miller
4492 The @samp{et al.} string, like @samp{ @{\it et al.@}} in
4493 Jones @{\it et al.@}
4497 @deffn {Normal Hook} reftex-select-bib-mode-hook
4498 Normal hook which is run when a selection buffer enters
4499 @code{reftex-select-bib-mode}.
4502 @deffn Keymap reftex-select-bib-map
4503 The keymap which is active in the citation-key selection process
4504 (@pxref{Creating Citations}).
4507 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options
4508 @section Index Support
4509 @cindex Options, Index support
4510 @cindex Index support, options
4512 @defopt reftex-support-index
4513 Non-@code{nil} means, index entries are parsed as well. Index support
4514 is resource intensive and the internal structure holding the parsed
4515 information can become quite big. Therefore it can be turned off. When
4516 this is @code{nil} and you execute a command which requires index
4517 support, you will be asked for confirmation to turn it on and rescan the
4521 @defopt reftex-index-special-chars
4522 List of special characters in index entries, given as strings. These
4523 correspond to the @code{MakeIndex} keywords
4524 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4527 @defopt reftex-index-macros
4528 List of macros which define index entries. The structure of each entry
4531 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4534 @var{macro} is the macro. Arguments should be denoted by empty braces,
4535 as for example in @samp{\index[]@{*@}}. Use square brackets to denote
4536 optional arguments. The star marks where the index key is.
4538 @var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
4539 are reserved for the default index and the glossary. Other indices can
4540 be defined as well. If this is an integer, the Nth argument of the
4541 macro holds the index tag.
4543 @var{key} is a character which is used to identify the macro for input
4544 with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
4545 reserved for default index and glossary.
4547 @var{prefix} can be a prefix which is added to the @var{key} part of the
4548 index entry. If you have a macro
4549 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4550 should be @samp{Molecules!}.
4552 @var{exclude} can be a function. If this function exists and returns a
4553 non-@code{nil} value, the index entry at point is ignored. This was
4554 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4555 in the LaTeX2e @code{index} package.
4557 @var{repeat}, if non-@code{nil}, means the index macro does not typeset
4558 the entry in the text, so that the text has to be repeated outside the
4559 index macro. Needed for @code{reftex-index-selection-or-word} and for
4560 indexing from the phrase buffer.
4562 The final entry may also be a symbol. It must have an association in
4563 the variable @code{reftex-index-macros-builtin} to specify the main
4564 indexing package you are using. Valid values are currently
4566 default @r{The LaTeX default - unnecessary to specify this one}
4567 multind @r{The multind.sty package}
4568 index @r{The index.sty package}
4569 index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
4570 @r{Should not be used - only for old documents}
4572 Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
4573 so with a sufficiently new version of AUCTeX, you should not set the
4577 @defopt reftex-index-default-macro
4578 The default index macro for @code{reftex-index-selection-or-word}.
4579 This is a list with @code{(@var{macro-key} @var{default-tag})}.
4581 @var{macro-key} is a character identifying an index macro - see
4582 @code{reftex-index-macros}.
4584 @var{default-tag} is the tag to be used if the macro requires a
4585 @var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
4586 @b{Ref@TeX{}} will ask for it. When this is the empty string and the
4587 TAG argument of the index macro is optional, the TAG argument will be
4591 @defopt reftex-index-default-tag
4592 Default index tag. When working with multiple indexes, RefTeX queries
4593 for an index tag when creating index entries or displaying a specific
4594 index. This variable controls the default offered for these queries.
4595 The default can be selected with @key{RET} during selection or
4596 completion. Valid values of this variable are:
4598 nil @r{Do not provide a default index}
4599 "tag" @r{The default index tag given as a string, e.g. "idx"}
4600 last @r{The last used index tag will be offered as default}
4604 @defopt reftex-index-math-format
4605 Format of index entries when copied from inside math mode. When
4606 @code{reftex-index-selection-or-word} is executed inside TeX math mode,
4607 the index key copied from the buffer is processed with this format
4608 string through the @code{format} function. This can be used to add the
4609 math delimiters (e.g. @samp{$}) to the string. Requires the
4610 @file{texmathp.el} library which is part of AUCTeX.
4613 @defopt reftex-index-phrase-file-extension
4614 File extension for the index phrase file. This extension will be added
4615 to the base name of the master file.
4618 @defopt reftex-index-phrases-logical-and-regexp
4619 Regexp matching the @samp{and} operator for index arguments in phrases
4620 file. When several index arguments in a phrase line are separated by
4621 this operator, each part will generate an index macro. So each match of
4622 the search phrase will produce @emph{several} different index entries.
4623 Make sure this does no match things which are not separators. This
4624 logical @samp{and} has higher priority than the logical @samp{or}
4625 specified in @code{reftex-index-phrases-logical-or-regexp}.
4628 @defopt reftex-index-phrases-logical-or-regexp
4629 Regexp matching the @samp{or} operator for index arguments in phrases
4630 file. When several index arguments in a phrase line are separated by
4631 this operator, the user will be asked to select one of them at each
4632 match of the search phrase. The first index arg will be the default. A
4633 number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make
4634 sure this does no match things which are not separators. The logical
4635 @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4636 has higher priority than this logical @samp{or}.
4639 @defopt reftex-index-phrases-search-whole-words
4640 Non-@code{nil} means phrases search will look for whole words, not subwords.
4641 This works by requiring word boundaries at the beginning and end of
4642 the search string. When the search phrase already has a non-word-char
4643 at one of these points, no word boundary is required there.
4646 @defopt reftex-index-phrases-case-fold-search
4647 Non-@code{nil} means, searching for index phrases will ignore
4651 @defopt reftex-index-verify-function
4652 A function which is called at each match during global indexing.
4653 If the function returns nil, the current match is skipped.
4656 @defopt reftex-index-phrases-skip-indexed-matches
4657 Non-@code{nil} means, skip matches which appear to be indexed already.
4658 When doing global indexing from the phrases buffer, searches for some
4659 phrases may match at places where that phrase was already indexed. In
4660 particular when indexing an already processed document again, this
4661 will even be the norm. When this variable is non-@code{nil},
4662 @b{Ref@TeX{}} checks if the match is an index macro argument, or if an
4663 index macro is directly before or after the phrase. If that is the
4664 case, that match will be ignored.
4667 @defopt reftex-index-phrases-wrap-long-lines
4668 Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
4669 Inserting indexing commands in a line makes the line longer - often
4670 so long that it does not fit onto the screen. When this variable is
4671 non-@code{nil}, newlines will be added as necessary before and/or after the
4672 indexing command to keep lines short. However, the matched text
4673 phrase and its index command will always end up on a single line.
4676 @defopt reftex-index-phrases-sort-prefers-entry
4677 Non-@code{nil} means when sorting phrase lines, the explicit index entry
4678 is used. Phrase lines in the phrases buffer contain a search phrase, and
4679 sorting is normally based on these. Some phrase lines also have
4680 an explicit index argument specified. When this variable is
4681 non-@code{nil}, the index argument will be used for sorting.
4684 @defopt reftex-index-phrases-sort-in-blocks
4685 Non-@code{nil} means, empty and comment lines separate phrase buffer
4686 into blocks. Sorting will then preserve blocks, so that lines are
4687 re-arranged only within blocks.
4690 @defopt reftex-index-phrases-map
4691 Keymap for the Index Phrases buffer.
4694 @defopt reftex-index-phrases-mode-hook
4695 Normal hook which is run when a buffer is put into
4696 @code{reftex-index-phrases-mode}.
4699 @defopt reftex-index-section-letters
4700 The letters which denote sections in the index. Usually these are all
4701 capital letters. Don't use any downcase letters. Order is not
4702 significant, the index will be sorted by whatever the sort function
4703 thinks is correct. In addition to these letters, @b{Ref@TeX{}} will
4704 create a group @samp{!} which contains all entries sorted below the
4705 lowest specified letter. In the @file{*Index*} buffer, pressing any of
4706 these capital letters or @kbd{!} will jump to that section.
4709 @defopt reftex-index-include-context
4710 Non-@code{nil} means, display the index definition context in the
4711 @file{*Index*} buffer. This flag may also be toggled from the
4712 @file{*Index*} buffer with the @kbd{c} key.
4715 @defopt reftex-index-follow-mode
4716 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4717 window to follow. The other window will show the corresponding part of
4718 the document. This flag can be toggled from within the @file{*Index*}
4719 buffer with the @kbd{f} key.
4722 @deffn Keymap reftex-index-map
4723 The keymap which is active in the @file{*Index*} buffer
4724 (@pxref{Index Support}).
4727 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options
4728 @section Viewing Cross-References
4729 @cindex Options, viewing cross-references
4730 @cindex Viewing cross-references, options
4732 @defopt reftex-view-crossref-extra
4733 Macros which can be used for the display of cross references.
4734 This is used when `reftex-view-crossref' is called with point in an
4735 argument of a macro. Note that crossref viewing for citations,
4736 references (both ways) and index entries is hard-coded. This variable
4737 is only to configure additional structures for which crossreference
4738 viewing can be useful. Each entry has the structure
4740 (@var{macro-re} @var{search-re} @var{highlight}).
4742 @var{macro-re} is matched against the macro. @var{search-re} is the
4743 regexp used to search for cross references. @samp{%s} in this regexp is
4744 replaced with the macro argument at point. @var{highlight} is an
4745 integer indicating which subgroup of the match should be highlighted.
4748 @defopt reftex-auto-view-crossref
4749 Non-@code{nil} means, initially turn automatic viewing of crossref info
4750 on. Automatic viewing of crossref info normally uses the echo area.
4751 Whenever point is idle for more than @code{reftex-idle-time} seconds on
4752 the argument of a @code{\ref} or @code{\cite} macro, and no other
4753 message is being displayed, the echo area will display information about
4754 that cross reference. You can also set the variable to the symbol
4755 @code{window}. In this case a small temporary window is used for the
4756 display. This feature can be turned on and off from the menu
4760 @defopt reftex-idle-time
4761 Time (secs) Emacs has to be idle before automatic crossref display
4762 or toc recentering is done.
4765 @defopt reftex-cite-view-format
4766 Citation format used to display citation info in the message area. See
4767 the variable @code{reftex-cite-format} for possible percent
4771 @defopt reftex-revisit-to-echo
4772 Non-@code{nil} means, automatic citation display will revisit files if
4773 necessary. When nil, citation display in echo area will only be active
4774 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4775 BibTeX database files which are already visited by a live associated
4779 @defopt reftex-cache-cite-echo
4780 Non-@code{nil} means, the information displayed in the echo area for
4781 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4782 saved along with the parsing information. The cache survives document
4783 scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
4786 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options
4787 @section Finding Files
4788 @cindex Options, Finding Files
4789 @cindex Finding files, options
4791 @defopt reftex-texpath-environment-variables
4792 List of specifications how to retrieve the search path for TeX files.
4793 Several entries are possible.
4796 If an element is the name of an environment variable, its content is
4799 If an element starts with an exclamation mark, it is used as a command
4800 to retrieve the path. A typical command with the kpathsearch library
4801 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4803 Otherwise the element itself is interpreted as a path.
4805 Multiple directories can be separated by the system dependent
4806 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4807 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4810 @defopt reftex-bibpath-environment-variables
4811 List of specifications how to retrieve the search path for BibTeX
4812 files. Several entries are possible.
4815 If an element is the name of an environment variable, its content is
4818 If an element starts with an exclamation mark, it is used as a command
4819 to retrieve the path. A typical command with the kpathsearch library
4820 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4822 Otherwise the element itself is interpreted as a path.
4824 Multiple directories can be separated by the system dependent
4825 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4826 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4829 @defopt reftex-file-extensions
4830 Association list with file extensions for different file types.
4831 This is a list of items, each item is like:
4832 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4834 @var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
4835 @var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
4836 @var{other-ext}: @r{Any number of other valid extensions for this file type.}
4838 When a files is searched and it does not have any of the valid extensions,
4839 we try the default extension first, and then the naked file name.
4842 @defopt reftex-search-unrecursed-path-first
4843 Non-@code{nil} means, search all specified directories before trying
4844 recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
4845 then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
4846 option is @code{nil}, the subdirectories of @samp{./} are searched
4847 before @samp{/tex/}. This is mainly for speed - most of the time the
4848 recursive path is for the system files and not for the user files. Set
4849 this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
4850 equal names in wrong sequence.
4853 @defopt reftex-use-external-file-finders
4854 Non-@code{nil} means, use external programs to find files. Normally,
4855 @b{Ref@TeX{}} searches the paths given in the environment variables
4856 @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
4857 database files. With this option turned on, it calls an external
4858 program specified in the option @code{reftex-external-file-finders}
4859 instead. As a side effect, the variables
4860 @code{reftex-texpath-environment-variables} and
4861 @code{reftex-bibpath-environment-variables} will be ignored.
4864 @defopt reftex-external-file-finders
4865 Association list with external programs to call for finding files. Each
4866 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
4867 @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
4868 string containing the external program to use with any arguments.
4869 @code{%f} will be replaced by the name of the file to be found. Note
4870 that these commands will be executed directly, not via a shell. Only
4871 relevant when @code{reftex-use-external-file-finders} is
4876 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
4877 @section Optimizations
4878 @cindex Options, optimizations
4879 @cindex Optimizations, options
4881 @defopt reftex-keep-temporary-buffers
4882 Non-@code{nil} means, keep buffers created for parsing and lookup.
4883 @b{Ref@TeX{}} sometimes needs to visit files related to the current
4884 document. We distinguish files visited for
4887 Parts of a multifile document loaded when (re)-parsing the
4890 BibTeX database files and TeX files loaded to find a reference, to
4891 display label context, etc.
4893 The created buffers can be kept for later use, or be thrown away
4894 immediately after use, depending on the value of this variable:
4898 Throw away as much as possible.
4902 Throw away buffers created for parsing, but keep the ones created for
4906 If a buffer is to be kept, the file is visited normally (which is
4907 potentially slow but will happen only once). If a buffer is to be thrown
4908 away, the initialization of the buffer depends upon the variable
4909 @code{reftex-initialize-temporary-buffers}.
4912 @defopt reftex-initialize-temporary-buffers
4913 Non-@code{nil} means do initializations even when visiting file
4914 temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
4915 other stuff to briefly visit a file. When @code{t}, the full default
4916 initializations are done (@code{find-file-hook} etc.). Instead of
4917 @code{t} or @code{nil}, this variable may also be a list of hook
4918 functions to do a minimal initialization.
4921 @defopt reftex-no-include-regexps
4922 List of regular expressions to exclude certain input files from parsing.
4923 If the name of a file included via @code{\include} or @code{\input} is
4924 matched by any of the regular expressions in this list, that file is not
4925 parsed by @b{Ref@TeX{}}.
4928 @defopt reftex-enable-partial-scans
4929 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4930 Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
4931 commands, or with the @kbd{r} key in menus. When this option is
4932 @code{t} in a multifile document, we will only parse the current buffer,
4933 or the file associated with the label or section heading near point in a
4934 menu. Requesting re-parsing of an entire multifile document then
4935 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
4939 @defopt reftex-save-parse-info
4940 Non-@code{nil} means, save information gathered with parsing in files.
4941 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
4942 used to save the information. When this variable is @code{t},
4945 accessing the parsing information for the first time in an editing
4946 session will read that file (if available) instead of parsing the
4949 exiting Emacs or killing a buffer in reftex-mode will cause a new
4950 version of the file to be written.
4954 @defopt reftex-parse-file-extension
4955 File extension for the file in which parser information is stored.
4956 This extension is added to the base name of the master file.
4959 @defopt reftex-allow-automatic-rescan
4960 Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
4961 necessary. Applies (currently) only in rare cases, when a new label
4962 cannot be placed with certainty into the internal label list.
4965 @defopt reftex-use-multiple-selection-buffers
4966 Non-@code{nil} means use a separate selection buffer for each label
4967 type. These buffers are kept from one selection to the next and need
4968 not to be created for each use - so the menu generally comes up faster.
4969 The selection buffers will be erased (and therefore updated)
4970 automatically when new labels in its category are added. See the
4971 variable @code{reftex-auto-update-selection-buffers}.
4974 @defopt reftex-auto-update-selection-buffers
4975 Non-@code{nil} means, selection buffers will be updated automatically.
4976 When a new label is defined with @code{reftex-label}, all selection
4977 buffers associated with that label category are emptied, in order to
4978 force an update upon next use. When @code{nil}, the buffers are left
4979 alone and have to be updated by hand, with the @kbd{g} key from the
4980 label selection process. The value of this variable will only have any
4981 effect when @code{reftex-use-multiple-selection-buffers} is
4985 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
4986 @section Fontification
4987 @cindex Options, fontification
4988 @cindex Fontification, options
4990 @defopt reftex-use-fonts
4991 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
4992 Font-lock must be loaded as well to actually get fontified
4993 display. After changing this option, a rescan may be necessary to
4997 @defopt reftex-refontify-context
4998 Non-@code{nil} means, re-fontify the context in the label menu with
4999 font-lock. This slightly slows down the creation of the label menu. It
5000 is only necessary when you definitely want the context fontified.
5002 This option may have 3 different values:
5009 Refontify when necessary, e.g. with old versions of the x-symbol
5012 The option is ignored when @code{reftex-use-fonts} is @code{nil}.
5015 @defopt reftex-highlight-selection
5016 Non-@code{nil} means, highlight selected text in selection and
5017 @file{*toc*} buffers. Normally, the text near the cursor is the
5018 @emph{selected} text, and it is highlighted. This is the entry most
5019 keys in the selection and @file{*toc*} buffers act on. However, if you
5020 mainly use the mouse to select an item, you may find it nice to have
5021 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
5022 variable may have one of these values:
5025 nil @r{No highlighting.}
5026 cursor @r{Highlighting is cursor driven.}
5027 mouse @r{Highlighting is mouse driven.}
5028 both @r{Both cursor and mouse trigger highlighting.}
5031 Changing this variable requires to rebuild the selection and *toc*
5032 buffers to become effective (keys @kbd{g} or @kbd{r}).
5035 @defopt reftex-cursor-selected-face
5036 Face name to highlight cursor selected item in toc and selection buffers.
5037 See also the variable @code{reftex-highlight-selection}.
5039 @defopt reftex-mouse-selected-face
5040 Face name to highlight mouse selected item in toc and selection buffers.
5041 See also the variable @code{reftex-highlight-selection}.
5043 @defopt reftex-file-boundary-face
5044 Face name for file boundaries in selection buffer.
5046 @defopt reftex-label-face
5047 Face name for labels in selection buffer.
5049 @defopt reftex-section-heading-face
5050 Face name for section headings in toc and selection buffers.
5052 @defopt reftex-toc-header-face
5053 Face name for the header of a toc buffer.
5055 @defopt reftex-bib-author-face
5056 Face name for author names in bib selection buffer.
5058 @defopt reftex-bib-year-face
5059 Face name for year in bib selection buffer.
5061 @defopt reftex-bib-title-face
5062 Face name for article title in bib selection buffer.
5064 @defopt reftex-bib-extra-face
5065 Face name for bibliographic information in bib selection buffer.
5067 @defopt reftex-select-mark-face
5068 Face name for marked entries in the selection buffers.
5070 @defopt reftex-index-header-face
5071 Face name for the header of an index buffer.
5073 @defopt reftex-index-section-face
5074 Face name for the start of a new letter section in the index.
5076 @defopt reftex-index-tag-face
5077 Face name for index names (for multiple indices).
5079 @defopt reftex-index-face
5080 Face name for index entries.
5083 @node Options (Misc), , Options (Fontification), Options
5084 @section Miscellaneous
5085 @cindex Options, misc
5087 @defopt reftex-extra-bindings
5088 Non-@code{nil} means, make additional key bindings on startup. These
5089 extra bindings are located in the users @samp{C-c letter}
5090 map. @xref{Key Bindings}.
5093 @defopt reftex-plug-into-AUCTeX
5094 Plug-in flags for AUCTeX interface. This variable is a list of
5095 5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}
5099 - supply labels in new sections and environments (flag 1)
5100 - supply arguments for macros like @code{\label} (flag 2)
5101 - supply arguments for macros like @code{\ref} (flag 3)
5102 - supply arguments for macros like @code{\cite} (flag 4)
5103 - supply arguments for macros like @code{\index} (flag 5)
5106 You may also set the variable itself to t or nil in order to turn all
5107 options on or off, respectively.@*
5108 Supplying labels in new sections and environments applies when creating
5109 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
5110 Supplying macro arguments applies when you insert such a macro
5111 interactively with @kbd{C-c @key{RET}}.@*
5112 See the AUCTeX documentation for more information.
5115 @defopt reftex-revisit-to-follow
5116 Non-@code{nil} means, follow-mode will revisit files if necessary.
5117 When nil, follow-mode will be suspended for stuff in unvisited files.
5120 @defopt reftex-allow-detached-macro-args
5121 Non-@code{nil} means, allow arguments of macros to be detached by
5122 whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
5123 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
5124 this will be the case even if @code{\bb} is defined with zero or one
5128 @node Keymaps and Hooks, Changes, Options, Top
5129 @section Keymaps and Hooks
5132 @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
5134 @deffn Keymap reftex-mode-map
5135 The keymap for @b{Ref@TeX{}} mode.
5138 @deffn {Normal Hook} reftex-load-hook
5139 Normal hook which is being run when loading @file{reftex.el}.
5142 @deffn {Normal Hook} reftex-mode-hook
5143 Normal hook which is being run when turning on @b{Ref@TeX{}} mode.
5146 Furthermore, the 4 modes used for referencing labels, creating
5147 citations, the table of contents buffer and the phrases buffer have
5148 their own keymaps and mode hooks. See the respective sections. There
5149 are many more hooks which are described in the relevant sections about
5150 options for a specific part of @b{Ref@TeX{}}.
5152 @node Changes, , Keymaps and Hooks, Top
5156 Here is a list of recent changes to @b{Ref@TeX{}}.
5158 @noindent @b{Version 4.28}
5160 @item Support for the Jurabib package.
5161 @item Improvements when selecting several items in a selection buffer.
5164 @noindent @b{Version 4.26}
5167 Support for global incremental search.
5169 Some improvements for XEmacs compatibility.
5172 @noindent @b{Version 4.25}
5175 Fixed bug with @samp{%F} in a label prefix. Added new escapes
5176 @samp{%m} and @samp{%M} for mater file name and master directory.
5179 @noindent @b{Version 4.24}
5182 Inserting citation commands now prompts for optional arguments
5183 when called with a prefix argument. Related new options are
5184 @code{reftex-cite-prompt-optional-args} and
5185 @code{reftex-cite-cleanup-optional-args}.
5187 New option @code{reftex-trust-label-prefix}. Configure this variable
5188 if you'd like RefTeX to base its classification of labels on prefixes.
5189 This can speed-up document parsing, but may in some cases reduce the
5190 quality of the context used by RefTeX to describe a label.
5192 Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
5195 Fixed bugs in indexing: Case-sensitive search, quotes before and/or
5196 after words. Disabled indexing in comment lines.
5199 @noindent @b{Version 4.22}
5202 New command @code{reftex-create-bibtex-file} to create a new database
5203 with all entries referenced in the current document.
5205 New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
5206 from entries marked in a citation selection buffer.
5209 @noindent @b{Version 4.21}
5212 Renaming labels from the toc buffer with key @kbd{M-%}.
5215 @noindent @b{Version 4.20}
5218 Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in
5219 the TOC buffer promote/demote the section at point or all sections in
5222 New option @code{reftex-toc-split-windows-fraction} to set the size of
5223 the window used by the TOC. This makes the old variable
5224 @code{reftex-toc-split-windows-horizontally-fraction} obsolete.
5226 A dedicated frame can show the TOC with the current section
5227 always automatically highlighted. The frame is created and
5228 deleted from the toc buffer with the @kbd{d} key.
5231 @noindent @b{Version 4.19}
5234 New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
5235 section in the TOC buffer without selecting the TOC window.
5237 Recentering happens automatically in idle time when the option
5238 @code{reftex-auto-recenter-toc} is turned on.
5240 Fixed several bugs related to automatic cursor positioning in the TOC
5243 The highlight in the TOC buffer stays when the focus moves to a
5246 New command `reftex-goto-label'.
5248 Part numbers are no longer included in chapter numbers, and a new
5249 part does not reset the chapter counter. See new option
5250 @code{reftex-part-resets-chapter}.
5253 @noindent @b{Version 4.18}
5256 @code{reftex-citation} uses the word before the cursor as a default
5259 Simplified several regular expressions for speed.
5261 Better support for chapterbib.
5264 @noindent @b{Version 4.17}
5267 The toc window can be split off horizontally. See new options
5268 @code{reftex-toc-split-windows-horizontally},
5269 @code{reftex-toc-split-windows-horizontally-fraction}.
5271 It is possible to specify a function which verifies an index match
5272 during global indexing. See new option @code{reftex-index-verify-function}.
5274 The macros which input a file in LaTeX (like \input, \include) can
5275 be configured. See new option @code{reftex-include-file-commands}.
5277 The macros which specify the bibliography file (like \bibliography) can
5278 be configured. See new option @code{reftex-bibliography-commands}.
5280 The regular expression used to search for the \bibliography macro has
5281 been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
5287 @noindent @b{Version 4.15}
5290 Fixed bug with parsing of BibTeX files, when fields contain quotes or
5291 unmatched parenthesis.
5295 Improved interaction with Emacs LaTeX mode.
5298 @noindent @b{Version 4.12}
5301 Support for @file{bibentry} citation style.
5304 @noindent @b{Version 4.11}
5307 Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5310 @noindent @b{Version 4.10}
5313 Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5314 with @file{reftex-vars.el} on DOS machines.
5316 New options @code{reftex-parse-file-extension} and
5317 @code{reftex-index-phrase-file-extension}.
5322 @noindent @b{Version 4.09}
5325 New option @code{reftex-toc-max-level} to limit the depth of the toc.
5326 New key binding @kbd{t} in the @file{*toc*} buffer to change this
5329 RefTeX maintains an @file{Index Phrases} file in which phrases can be
5330 collected. When the document is ready, RefTeX can search all
5331 these phrases and assist indexing all matches.
5333 The variables @code{reftex-index-macros} and
5334 @code{reftex-index-default-macro} have changed their syntax slightly.
5335 The @var{repeat} parameter has move from the latter to the former.
5336 Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5339 The variable @code{reftex-section-levels} no longer contains the
5340 default stuff which has been moved to a constant.
5342 Environments like theorems can be placed into the TOC by putting
5343 entries for @samp{"begin@{theorem@}"} in
5344 @code{reftex-setion-levels}.
5347 @noindent @b{Version 4.06}
5350 @code{reftex-section-levels} can contain a function to compute the level
5351 of a sectioning command.
5353 Multiple @code{thebibliography} environments recognized.
5356 @noindent @b{Version 4.04}
5359 New option @code{reftex-index-default-tag} implements a default for queries.
5362 @noindent @b{Version 4.02}
5365 macros ending in @samp{refrange} are considered to contain references.
5367 Index entries made with @code{reftex-index-selection-or-word} in TeX
5368 math mode automatically get enclosing @samp{$} to preserve math mode. See
5369 new option @code{reftex-index-math-format}. Requires AUCTeX.
5372 @noindent @b{Version 4.01}
5375 New command @code{reftex-index-globally} to index a word in many
5376 places in the document. Also available from the index buffer with
5379 The first item in a @code{reftex-label-alist} entry may now also be a parser
5380 function to do non-standard parsing.
5382 @code{reftex-auto-view-crossref} no longer interferes with
5383 @code{pop-up-frames} (patch from Stefan Monnier).
5386 @noindent @b{Version 4.00}
5389 RefTeX has been split into several smaller files which are autoloaded on
5392 Index support, along with many new options.
5394 The selection of keys for @code{\ref} and @code{\cite} now allows to
5395 select multiple items by marking entries with the @kbd{m} key.
5400 @noindent @b{Version 3.43}
5403 Viewing cross-references generalized. Now works on @code{\label},
5404 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5405 these, and from BibTeX buffers.
5407 New option @code{reftex-view-crossref-extra}.
5409 Support for the additional sectioning commands @code{\addchap} and
5410 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.
5412 Files in @code{reftex-default-bibliography} will be searched along
5413 @code{BIBINPUTS} path.
5415 Reading a parse file now checks consistency.
5418 @noindent @b{Version 3.42}
5421 File search further refined. New option @code{reftex-file-extensions}.
5423 @file{*toc*} buffer can show the file boundaries of a multifile
5424 document, all labels and associated context. New keys @kbd{i}, @kbd{l},
5425 and @kbd{c}. New options @code{reftex-toc-include-labels},
5426 @code{reftex-toc-include-context},
5427 @code{reftex-toc-include-file-boundaries}.
5430 @noindent @b{Version 3.41}
5433 New options @code{reftex-texpath-environment-variables},
5434 @code{reftex-use-external-file-finders},
5435 @code{reftex-external-file-finders},
5436 @code{reftex-search-unrecursed-path-first}.
5438 @emph{kpathsearch} support. See new options and
5439 @code{reftex-bibpath-environment-variables}.
5442 @noindent @b{Version 3.38}
5445 @code{reftex-view-crossref} no longer moves to find a macro. Point has
5446 to be on the macro argument.
5449 @noindent @b{Version 3.36}
5452 New value @code{window} for option @code{reftex-auto-view-crossref}.
5455 @noindent @b{Version 3.35}
5458 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5459 This takes back the related changes in 3.34 for safety reasons.
5462 @noindent @b{Version 3.34}
5465 Additional flag in @code{reftex-derive-label-parameters} do make only
5466 lowercase labels (default @code{t}).
5468 All @file{.rel} files have a final newline to avoid queries.
5470 Single byte representations of accented European letters (ISO-8859-1)
5471 are now valid in labels.
5474 @noindent @b{Version 3.33}
5477 Multiple selection buffers are now hidden buffers (they start with a
5480 Fixed bug with file search when TEXINPUTS environment variable is empty.
5483 @noindent @b{Version 3.30}
5486 In @code{reftex-citation}, the regular expression used to scan BibTeX
5487 files can be specified using completion on known citation keys.
5489 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5492 New command @code{reftex-renumber-simple-labels} to renumber simple
5493 labels like @samp{eq:13} sequentially through a document.
5496 @noindent @b{Version 3.28}
5499 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5500 timer, since itimer restart is not reliable.
5502 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5504 Expansion of recursive tex and bib path rewritten.
5506 Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
5508 Fixed bug with section numbering after *-red sections.
5511 @noindent @b{Version 3.27}
5514 Macros can define @emph{neutral} labels, just like @code{\label}
5517 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5520 @noindent @b{Version 3.26}
5523 [X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
5525 New hooks @code{reftex-translate-to-ascii-function},
5526 @code{reftex-string-to-label-function}.
5528 Made sure automatic crossref display will not visit/scan files.
5531 @noindent @b{Version 3.25}
5534 Echoing of citation info caches the info for displayed entries.
5535 New option @code{reftex-cache-cite-echo}.
5537 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
5540 Default of @code{reftex-revisit-to-follow} changed to nil.
5543 @noindent @b{Version 3.24}
5546 New option @code{reftex-revisit-to-echo}.
5548 Interface with X-Symbol (>=2.6) is now complete and stable.
5550 Adapted to new outline, which uses overlays.
5552 File names in @code{\bibliography} may now have the @code{.bib}
5555 Fixed Bug with parsing "single file" from master file buffer.
5558 @noindent @b{Version 3.23}
5561 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5563 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
5566 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5567 automatic display of crossref information in the echo area. See
5568 variable @code{reftex-auto-view-crossref}.
5570 AUCTeX interface updates:
5573 AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
5575 @b{Ref@TeX{}} notifies AUCTeX about new labels.
5577 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
5579 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5581 Settings added to @b{Ref@TeX{}} via style files remain local.
5584 Fixed bug with @code{reftex-citation} in non-latex buffers.
5586 Fixed bug with syntax table and context refontification.
5588 Safety-net for name change of @code{font-lock-reference-face}.
5591 @noindent @b{Version 3.22}
5594 Fixed bug with empty context strings.
5596 @code{reftex-mouse-view-crossref} is now bound by default at
5600 @noindent @b{Version 3.21}
5603 New options for all faces used by @b{Ref@TeX{}}. They're in the
5604 customization group @code{reftex-fontification-configurations}.
5607 @noindent @b{Version 3.19}
5610 Fixed bug with AUCTeX @code{TeX-master}.
5613 @noindent @b{Version 3.18}
5616 The selection now uses a recursive edit, much like minibuffer input.
5617 This removes all restrictions during selection. E.g. you can now
5618 switch buffers at will, use the mouse etc.
5620 New option @code{reftex-highlight-selection}.
5622 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
5625 Fixed some problems regarding the interaction with VIPER mode.
5627 Follow-mode is now only used after point motion.
5629 @b{Ref@TeX{}} now finally does not fontify temporary files anymore.
5632 @noindent @b{Version 3.17}
5635 Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
5638 New command @code{reftex-save-all-document-buffers}.
5640 Magic word matching made more intelligent.
5642 Selection process can switch to completion (with @key{TAB}).
5644 @code{\appendix} is now recognized and influences section numbering.
5646 File commentary shortened considerably (use Info documentation).
5648 New option @code{reftex-no-include-regexps} to skip some include files.
5650 New option @code{reftex-revisit-to-follow}.
5653 @noindent @b{Version 3.16}
5656 New hooks @code{reftex-format-label-function},
5657 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
5659 TeXInfo documentation completed.
5661 Some restrictions in Label inserting and referencing removed.
5663 New variable @code{reftex-default-bibliography}.
5666 @noindent @b{Version 3.14}
5669 Selection buffers can be kept between selections: this is faster.
5670 See new variable @code{reftex-use-multiple-selection-buffers}.
5672 Prefix interpretation of reftex-view-crossref changed.
5674 Support for the @code{varioref} package (@kbd{v} key in selection
5678 @noindent @b{Version 3.12}
5681 There are 3 new keymaps for customization: @code{reftex-toc-map},
5682 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5684 Refontification uses more standard font-lock stuff.
5686 When no BibTeX database files are specified, citations can also use
5687 @code{\bibitem} entries from a @code{thebibliography} environment.
5690 @noindent @b{Version 3.11}
5693 Fixed bug which led to naked label in (e.g.) footnotes.
5695 Added scroll-other-window functions to RefTeX-Select.
5698 @noindent @b{Version 3.10}
5701 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5703 Removed unimportant code which caused OS/2 Emacs to crash.
5705 All customization variables now accessible from menu.
5708 @noindent @b{Version 3.07}
5711 @code{Ref} menu improved.
5714 @noindent @b{Version 3.05}
5717 Compatibility code now first checks for XEmacs feature.
5720 @noindent @b{Version 3.04}
5723 Fixed BUG in the @emph{xr} support.
5726 @noindent @b{Version 3.03}
5729 Support for the LaTeX package @code{xr}, for inter-document
5732 A few (minor) Mule-related changes.
5734 Fixed bug which could cause @emph{huge} @file{.rel} files.
5736 Search for input and @file{.bib} files with recursive path definitions.
5739 @noindent @b{Version 3.00}
5742 @b{Ref@TeX{}} should work better for very large projects:
5744 The new parser works without creating a master buffer.
5746 Rescanning can be limited to a part of a multifile document.
5748 Information from the parser can be stored in a file.
5750 @b{Ref@TeX{}} can deal with macros having a naked label as an argument.
5752 Macros may have white space and newlines between arguments.
5754 Multiple identical section headings no longer confuse
5757 @b{Ref@TeX{}} should work correctly in combination with buffer-altering
5758 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
5760 All labeled environments discussed in @emph{The LaTeX Companion} by
5761 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
5762 @b{Ref@TeX{}}'s defaults.
5765 @noindent @b{Version 2.17}
5768 Label prefix expands % escapes with current file name and other stuff.
5770 Citation format now with % escapes. This is not backward
5773 TEXINPUTS variable recognized when looking for input files.
5775 Context can be the nth argument of a macro.
5777 Searching in the select buffer is now possible (@kbd{C-s} and
5780 Display and derive-label can use two different context methods.
5782 AMSmath @code{xalignat} and @code{xxalignat} added.
5785 @noindent @b{Version 2.14}
5788 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
5792 @noindent @b{Version 2.11}
5795 Submitted for inclusion to Emacs and XEmacs.
5798 @noindent @b{Version 2.07}
5801 New functions @code{reftex-search-document},
5802 @code{reftex-query-replace-document}.
5805 @noindent @b{Version 2.05}
5808 Support for @file{custom.el}.
5810 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
5813 @noindent @b{Version 2.03}
5816 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
5817 default environments.
5819 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
5821 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
5822 @code{reftex-arg-cite}.
5824 Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
5827 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
5830 Finding context with a hook function.
5832 Sorting BibTeX entries (new variable:
5833 @code{reftex-sort-bibtex-matches}).
5836 @noindent @b{Version 2.00}
5839 Labels can be derived from context (default for sections).
5841 Configuration of label insertion and label referencing revised.
5843 Crossref fields in BibTeX database entries.
5845 @code{reftex-toc} introduced (thanks to Stephen Eglen).
5848 @noindent @b{Version 1.09}
5851 Support for @code{tex-main-file}, an analogue for
5857 @noindent @b{Version 1.07}
5860 @b{Ref@TeX{}} gets its own menu.
5863 @noindent @b{Version 1.05}
5869 @noindent @b{Version 1.04}
5872 Macros as wrappers, AMSTeX support, delayed context parsing for
5877 @noindent @b{Version 1.00}
5880 released on 7 Jan 1997.
5887 @node Index, , , Top
5896 arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43