1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/reftex
4 @settitle RefTeX User Manual
9 @c Version and Contact Info
13 @set AUCTEXSITE @uref{http://www.nongnu.org/auctex/,AUCTeX distribution site}
14 @set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/,maintainers webpage}
15 @set MAINTAINER Carsten Dominik
16 @set MAINTAINEREMAIL @email{dominik@@science.uva.nl}
17 @set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}
18 @set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}.
22 This file documents @b{Ref@TeX{}}, a package to do labels, references,
23 citations and indices for LaTeX documents with Emacs.
25 This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
26 @b{Ref@TeX{}} @value{VERSION}
28 Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2005
29 Free Software Foundation, Inc.
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.1 or
34 any later version published by the Free Software Foundation; with no
35 Invariant Sections, with the Front-Cover texts being ``A GNU
36 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
37 license is included in the section entitled ``GNU Free Documentation
38 License'' in the Emacs manual.
40 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
41 this GNU Manual, like GNU software. Copies published by the Free
42 Software Foundation raise funds for GNU development.''
44 This document is part of a collection distributed under the GNU Free
45 Documentation License. If you want to distribute this document
46 separately from the collection, you can do so by adding a copy of the
47 license to the document, as described in section 6 of the license.
53 * RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
60 @c Subheadings inside a table. Need a difference between info and the rest.
61 @macro tablesubheading{text}
71 @title Ref@TeX{} User Manual
72 @subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
73 @subtitle Edition @value{EDITION}, @value{DATE}
75 @author by Carsten Dominik
77 @vskip 0pt plus 1filll
84 @b{Ref@TeX{}} is a package for managing Labels, References,
85 Citations and index entries with GNU Emacs.
87 Don't be discouraged by the size of this manual, which covers
88 @b{Ref@TeX{}} in great depth. All you need to know to use
89 @b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
90 Nutshell}). You can go back later to other parts of this document when
94 * Introduction:: Quick-Start information.
96 * Table of Contents:: A Tool to move around quickly.
97 * Labels and References:: Creating and referencing labels.
98 * Citations:: Creating Citations.
99 * Index Support:: Creating and Checking Index Entries.
100 * Viewing Cross-References:: Who references or cites what?
102 * RefTeXs Menu:: The Ref menu in the menubar.
103 * Key Bindings:: The default key bindings.
104 * Faces:: Fontification of RefTeX's buffers.
105 * Multifile Documents:: Document spread over many files.
106 * Language Support:: How to support other languages.
107 * Finding Files:: Included TeX files and BibTeX .bib files.
108 * AUCTeX:: Cooperation with AUCTeX.
109 * Optimizations:: When RefTeX is too slow.
110 * Problems and Work-Arounds:: First Aid.
111 * Imprint:: Author, Web-site, Thanks
113 * Commands:: Which are the available commands.
114 * Options:: How to extend and configure RefTeX.
115 * Keymaps and Hooks:: For customization.
116 * Changes:: A List of recent changes to RefTeX.
120 * Index:: The full index.
126 * Installation:: How to install and activate RefTeX.
127 * RefTeX in a Nutshell:: A brief summary and quick guide.
129 Labels and References
132 * Referencing Labels::
133 * Builtin Label Environments:: The environments RefTeX knows about.
134 * Defining Label Environments:: ... and environments it doesn't.
135 * Reference Info:: View the label corresponding to a \ref.
136 * xr (LaTeX package):: References to external documents.
137 * varioref (LaTeX package):: How to create \vref instead of \ref.
138 * fancyref (LaTeX package):: How to create \fref instead of \ref.
140 Defining Label Environments
142 * Theorem and Axiom:: Defined with @code{\newenvironment}.
143 * Quick Equation:: When a macro sets the label type.
144 * Figure Wrapper:: When a macro argument is a label.
145 * Adding Magic Words:: Other words for other languages.
146 * Using \eqref:: How to switch to this AMS-LaTeX macro.
147 * Non-Standard Environments:: Environments without \begin and \end
148 * Putting it Together:: How to combine many entries.
152 * Creating Citations:: How to create them.
153 * Citation Styles:: Natbib, Harvard, Chicago and Co.
154 * Citation Info:: View the corresponding database entry.
155 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
156 * Citations Outside LaTeX:: How to make citations in Emails etc.
157 * BibTeX Database Subsets:: Extract parts of a big database.
161 * Creating Index Entries:: Macros and completion of entries.
162 * The Index Phrases File:: A special file for global indexing.
163 * Displaying and Editing the Index:: The index editor.
164 * Builtin Index Macros:: The index macros RefTeX knows about.
165 * Defining Index Macros:: ... and macros it doesn't.
167 The Index Phrases File
169 * Collecting Phrases:: Collecting from document or external.
170 * Consistency Checks:: Check for duplicates etc.
171 * Global Indexing:: The interactive indexing process.
175 * AUCTeX-RefTeX Interface:: How both packages work together
176 * Style Files:: AUCTeX's style files can support RefTeX
177 * Bib-Cite:: Hypertext reading of a document
179 Options, Keymaps, Hooks
181 * Options (Table of Contents)::
182 * Options (Defining Label Environments)::
183 * Options (Creating Labels)::
184 * Options (Referencing Labels)::
185 * Options (Creating Citations)::
186 * Options (Index Support)::
187 * Options (Viewing Cross-References)::
188 * Options (Finding Files)::
189 * Options (Optimizations)::
190 * Options (Fontification)::
198 @node Introduction, Table of Contents, , Top
199 @chapter Introduction
202 @b{Ref@TeX{}} is a specialized package for support of labels,
203 references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
204 itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
205 and @code{\index}. Using these macros usually requires looking up
206 different parts of the document and searching through BibTeX database
207 files. @b{Ref@TeX{}} automates these time--consuming tasks almost
208 entirely. It also provides functions to display the structure of a
209 document and to move around in this structure quickly.
212 Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
213 in great depth. All you need to know to use @b{Ref@TeX{}} can be
214 summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
215 back later to other parts of this document when needed.
218 @xref{Imprint}, for information about who to contact for help, bug
219 reports or suggestions.
222 * Installation:: How to install and activate RefTeX.
223 * RefTeX in a Nutshell:: A brief summary and quick guide.
226 @node Installation, RefTeX in a Nutshell, , Introduction
227 @section Installation
230 @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version
231 20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x.
232 XEmacs 21.x users want to install the corresponding plug-in package
233 which is available from the @value{XEMACSFTP}. See the XEmacs 21.x
234 documentation on package installation for details.
236 Users of earlier Emacs distributions (including Emacs 19) can get a copy
237 of the @b{Ref@TeX{}} distribution from the maintainers web-page.
238 @xref{Imprint}, for more information.
241 @cindex Finding files
242 @cindex BibTeX database files, not found
243 @cindex TeX files, not found
244 @cindex @code{TEXINPUTS}, environment variable
245 @cindex @code{BIBINPUTS}, environment variable
247 @b{Ref@TeX{}} needs to access all files which are part of a multifile
248 document, and the BibTeX database files requested by the
249 @code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
250 require a search path, i.e. a list of directories to check. Normally
251 this list is stored in the environment variables @code{TEXINPUTS} and
252 @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
253 systems these variables do not contain the full search path. If
254 @b{Ref@TeX{}} does not work for you because it cannot find some files,
255 read @ref{Finding Files}.
257 @section Entering @b{Ref@TeX{}} Mode
259 @findex turn-on-reftex
261 @vindex LaTeX-mode-hook
262 @vindex latex-mode-hook
263 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
264 @kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
265 files, add the following lines to your @file{.emacs} file:
268 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
269 (add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
273 @node RefTeX in a Nutshell, , Installation, Introduction
274 @section @b{Ref@TeX{}} in a Nutshell
276 @cindex Getting Started
277 @cindex RefTeX in a Nutshell
278 @cindex Nutshell, RefTeX in a
282 @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
283 a table of contents of the document. This buffer can display sections,
284 labels and index entries defined in the document. From the buffer, you
285 can jump quickly to every part of your document. Press @kbd{?} to get
289 @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
290 and to find the correct key for references quickly. It distinguishes
291 labels for different environments, knows about all standard
292 environments (and many others), and can be configured to recognize any
293 additional labeled environments you have defined yourself (variable
294 @code{reftex-label-alist}).
298 @b{Creating Labels}@*
299 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
300 @b{Ref@TeX{}} will either
303 derive a label from context (default for section labels)
305 prompt for a label string (default for figures and tables) or
307 insert a simple label made of a prefix and a number (all other
311 Which labels are created how is configurable with the variable
312 @code{reftex-insert-label-flags}.
315 @b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
316 (@code{reftex-reference}). This shows an outline of the document with
317 all labels of a certain type (figure, equation,...) and some label
318 context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
319 into the original buffer.
324 Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
325 regular expression to search in current BibTeX database files (as
326 specified in the @code{\bibliography} command) and pull out a list of
327 matches for you to choose from. The list is @emph{formatted} and
328 sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
329 (see the variable @code{reftex-cite-format} if you want to insert
334 @b{Ref@TeX{}} helps to enter index entries. It also compiles all
335 entries into an alphabetically sorted @file{*Index*} buffer which you
336 can use to check and edit the entries. @b{Ref@TeX{}} knows about the
337 standard index macros and can be configured to recognize any additional
338 macros you have defined (@code{reftex-index-macros}). Multiple indices
343 @b{Creating Index Entries}@*
344 To index the current selection or the word at point, type @kbd{C-c /}
345 (@code{reftex-index-selection-or-word}). The default macro
346 @code{reftex-index-default-macro} will be used. For a more complex entry
347 type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
348 and enter the arguments with completion.
351 @b{The Index Phrases File (Delayed Indexing)}@*
352 Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
353 the current word or selection to a special @emph{index phrase file}.
354 @b{Ref@TeX{}} can later search the document for occurrences of these
355 phrases and let you interactively index the matches.
358 @b{Displaying and Editing the Index}@*
359 To display the compiled index in a special buffer, type @kbd{C-c >}
360 (@code{reftex-display-index}). From that buffer you can check and edit
365 @item @b{Viewing Cross-References}@*
366 When point is on the @var{key} argument of a cross--referencing macro
367 (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
368 @code{\index}, and variations) or inside a BibTeX database entry, you
369 can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
370 corresponding locations in the document and associated BibTeX database
372 When the enclosing macro is @code{\cite} or @code{\ref} and no other
373 message occupies the echo area, information about the citation or label
374 will automatically be displayed in the echo area.
377 @b{Multifile Documents}@*
378 Multifile Documents are fully supported. The included files must have a
379 file variable @code{TeX-master} or @code{tex-main-file} pointing to the
380 master file. @b{Ref@TeX{}} provides cross-referencing information from
381 all parts of the document, and across document borders
385 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
386 order to find labels and other information. It does it automatically
387 once and updates its list internally when @code{reftex-label} and
388 @code{reftex-index} are used. To enforce reparsing, call any of the
389 commands described above with a raw @kbd{C-u} prefix, or press the
390 @kbd{r} key in the label selection buffer, the table of contents
391 buffer, or the index buffer.
394 @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
395 cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
396 contains style files which trigger appropriate settings in
397 @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
398 additional customizations will be necessary.
401 @b{Useful Settings}@*
402 To integrate RefTeX with AUCTeX, use
404 (setq reftex-plug-into-AUCTeX t)
407 To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
408 customize the variables
410 @code{reftex-label-alist} @r{(for label macros/environments)}
411 @code{reftex-section-levels} @r{(for sectioning commands)}
412 @code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
413 @code{reftex-index-macros} @r{(for @code{\index}-like macros)}
414 @code{reftex-index-default-macro} @r{(to set the default macro)}
416 If you have a large number of macros defined, you may want to write
417 an AUCTeX style file to support them with both AUCTeX and
420 @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
421 until you have picked up the key bindings. For an overview of what you
422 can do in each of the different special buffers, press @kbd{?}. Read
423 the manual if you get stuck, of if you are curious what else might be
424 available. The first part of the manual explains in
425 a tutorial way how to use and customize @b{Ref@TeX{}}. The second
426 part is a command and variable reference.
429 @node Table of Contents, Labels and References, Introduction, Top
430 @chapter Table of Contents
431 @cindex @file{*toc*} buffer
432 @cindex Structure editing
433 @cindex Table of contents buffer
437 Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
438 contents of the document. By default, this @file{*toc*} buffer shows
439 only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
440 can display all labels and index entries defined in the document as
443 With the cursor in any of the lines denoting a location in the
444 document, simple key strokes will display the corresponding part in
445 another window, jump to that location, or perform other actions.
448 Here is a list of special commands in the @file{*toc*} buffer. A
449 summary of this information is always available by pressing
454 @tablesubheading{General}
456 Display a summary of commands.
461 @tablesubheading{Moving around}
463 Goto next entry in the table of context.
466 Goto previous entry in the table of context.
469 Goto next section heading. Useful when many labels and index entries
470 separate section headings.
473 Goto previous section heading.
476 Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps
479 @tablesubheading{Access to document locations}
481 Show the corresponding location in another window. This command does
482 @emph{not} select that other window.
485 Goto the location in another window.
488 Go to the location and hide the @file{*toc*} buffer. This will restore
489 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
493 @vindex reftex-highlight-selection
494 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
495 See also variable @code{reftex-highlight-selection}, @ref{Options
499 @vindex reftex-toc-follow-mode
500 @vindex reftex-revisit-to-follow
501 Toggle follow mode. When follow mode is active, the other window will
502 always show the location corresponding to the line at point in the
503 @file{*toc*} buffer. This is similar to pressing @key{SPC} after each
504 cursor motion. The default for this flag can be set with the variable
505 @code{reftex-toc-follow-mode}. Note that only context in files already
506 visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
507 mode. See, however, the variable
508 @code{reftex-revisit-to-follow}.
511 Show calling point in another window. This is the point from where
512 @code{reftex-toc} was last called.
515 @tablesubheading{Promotion and Demotion}
518 Promote the current section. This will convert @code{\section} to
519 @code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
520 an active region, all sections in the region will be promoted, including
521 the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh
522 document scan before executing this command - if necessary, it will
523 automatically do this scan and ask the user to repeat the promotion
527 Demote the current section. This is the opposite of promotion. It will
528 convert @code{\chapter} to @code{\section} etc. If there is an active
529 region, all sections in the region will be demoted, including the one at
533 Rename the label at point. While generally not recommended, this can be
534 useful when a package like @file{fancyref} is used where the label
535 prefix determines the wording of a reference. After a
536 promotion/demotion it may be necessary to change a few labels from
537 @samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be
538 used to do this - it launches a query replace to rename the definition
539 and all references of a label.
541 @tablesubheading{Exiting}
543 Hide the @file{*toc*} buffer, return to the position where
544 @code{reftex-toc} was last called.
547 Kill the @file{*toc*} buffer, return to the position where
548 @code{reftex-toc} was last called.
551 Switch to the @file{*Index*} buffer of this document. With prefix
552 @samp{2}, restrict the index to the section at point in the @file{*toc*}
555 @tablesubheading{Controlling what gets displayed}
558 @vindex reftex-toc-max-level
559 Change the maximum level of toc entries displayed in the @file{*toc*}
560 buffer. Without prefix arg, all levels will be included. With prefix
561 arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
562 @var{arg} (3 in this case). Chapters are level 1, sections are level 2.
563 The mode line @samp{T<>} indicator shows the current value. The default
564 depth can be configured with the variable
565 @code{reftex-toc-max-level}.
568 @vindex reftex-toc-include-file-boundaries
569 Toggle the display of the file borders of a multifile document in the
570 @file{*toc*} buffer. The default for this flag can be set with the
571 variable @code{reftex-toc-include-file-boundaries}.
574 @vindex reftex-toc-include-labels
575 Toggle the display of labels in the @file{*toc*} buffer. The default
576 for this flag can be set with the variable
577 @code{reftex-toc-include-labels}. When called with a prefix argument,
578 @b{Ref@TeX{}} will prompt for a label type and include only labels of
579 the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
580 indicator shows which labels are included.
583 @vindex reftex-toc-include-index-entries
584 Toggle the display of index entries in the @file{*toc*} buffer. The
585 default for this flag can be set with the variable
586 @code{reftex-toc-include-index-entries}. When called with a prefix
587 argument, @b{Ref@TeX{}} will prompt for a specific index and include
588 only entries in the selected index in the @file{*toc*} buffer. The mode
589 line @samp{I<>} indicator shows which index is used.
592 @vindex reftex-toc-include-context
593 Toggle the display of label and index context in the @file{*toc*}
594 buffer. The default for this flag can be set with the variable
595 @code{reftex-toc-include-context}.
597 @tablesubheading{Updating the buffer}
600 Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
604 @vindex reftex-enable-partial-scans
605 Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
606 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
607 location is defined in, not the entire document.
610 Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
614 Switch to the @file{*toc*} buffer of an external document. When the
615 current document is using the @code{xr} package (@pxref{xr (LaTeX
616 package)}), @b{Ref@TeX{}} will switch to one of the external
620 @tablesubheading{Automatic recentering}
623 Toggle the display of a dedicated frame displaying just the @file{*toc*}
624 buffer. Follow mode and visiting locations will not work that frame,
625 but automatic recentering will make this frame always show your current
626 editing location in the document (see below).
629 Toggle the automatic recentering of the @file{*toc*} buffer. When this
630 option is on, moving around in the document will cause the @file{*toc*}
631 to always highlight the current section. By default, this option is
632 active while the dedicated @file{*TOC*} frame exists. See also the
633 variable @code{reftex-auto-recenter-toc}.
637 @vindex reftex-toc-map
638 In order to define additional commands for the @file{*toc*} buffer, the
639 keymap @code{reftex-toc-map} may be used.
641 @findex reftex-toc-recenter
642 @vindex reftex-auto-recenter-toc
643 @vindex reftex-idle-time
644 @cindex @file{*toc*} buffer, recentering
645 @cindex Table of contents buffer, recentering
647 If you call @code{reftex-toc} while the @file{*toc*} buffer already
648 exists, the cursor will immediately jump to the right place, i.e. the
649 section from which @code{reftex-toc} was called will be highlighted.
650 The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
651 the @file{*toc*} buffer and highlight the correct line without actually
652 selecting the @file{*toc*} window. This can be useful to quickly find
653 out where in the document you currently are. You can also automate this
654 by asking RefTeX to keep track of your current editing position in the
655 TOC. The TOC window will then be updated whenever you stop typing for
656 more than @code{reftex-idle-time} seconds. By default this works only
657 with the dedicated @file{*TOC*} frame. But you can also force automatic
658 recentering of the TOC window on the current frame with
660 (setq reftex-auto-recenter-toc t)
664 @cindex Sectioning commands
665 @cindex KOMA-Script, LaTeX classes
666 @cindex LaTeX classes, KOMA-Script
667 @cindex TOC entries for environments
668 @vindex reftex-section-levels
669 The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
670 macros (from @code{\part} to @code{\subsubparagraph}) and the commands
671 @code{\addchap} and @code{\addsec} from the KOMA-Script classes.
672 Additional macros can be configured with the variable
673 @code{reftex-section-levels}. It is also possible to add certain LaTeX
674 environments to the table of contents. This is probably only useful for
675 theorem-like environments. @xref{Defining Label Environments}, for an
678 @node Labels and References, Citations, Table of Contents, Top
679 @chapter Labels and References
680 @cindex Labels in LaTeX
681 @cindex References in LaTeX
682 @cindex Label category
683 @cindex Label environment
684 @cindex @code{\label}
686 LaTeX provides a powerful mechanism to deal with cross--references in a
687 document. When writing a document, any part of it can be marked with a
688 label, like @samp{\label@{mark@}}. LaTeX records the current value of a
689 certain counter when a label is defined. Later references to this label
690 (like @samp{\ref@{mark@}}) will produce the recorded value of the
693 Labels can be used to mark sections, figures, tables, equations,
694 footnotes, items in enumerate lists etc. LaTeX is context sensitive in
695 doing this: A label defined in a figure environment automatically
696 records the figure counter, not the section counter.
698 Several different environments can share a common counter and therefore
699 a common label category. E.g. labels in both @code{equation} and
700 @code{eqnarray} environments record the value of the same counter - the
705 * Referencing Labels::
706 * Builtin Label Environments:: The environments RefTeX knows about.
707 * Defining Label Environments:: ... and environments it doesn't.
708 * Reference Info:: View the label corresponding to a \ref.
709 * xr (LaTeX package):: References to external documents.
710 * varioref (LaTeX package):: How to create \vref instead of \ref.
711 * fancyref (LaTeX package):: How to create \fref instead of \ref.
714 @node Creating Labels, Referencing Labels, , Labels and References
715 @section Creating Labels
716 @cindex Creating labels
717 @cindex Labels, creating
718 @cindex Labels, deriving from context
722 In order to create a label in a LaTeX document, press @kbd{C-c (}
723 (@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
724 and will figure out the environment it currently is in and adapt the
725 label to that environment. A label usually consists of a short prefix
726 indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
727 3 different modes to create this mark.
731 @vindex reftex-translate-to-ascii-function
732 @vindex reftex-derive-label-parameters
733 @vindex reftex-label-illegal-re
734 @vindex reftex-abbrev-parameters
735 A label can be derived from context. This means, @b{Ref@TeX{}} takes
736 the context of the label definition and constructs a label from
737 that@footnote{Note that the context may contain constructs which are
738 invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from
739 accented Latin-1 characters and remove everything else which is not
740 valid in labels. This mechanism is safe, but may not be satisfactory
741 for non-western languages. Check the following variables if you need to
742 change things: @code{reftex-translate-to-ascii-function},
743 @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
744 @code{reftex-abbrev-parameters}.}. This works best for section labels,
745 where the section heading is used to construct a label. In fact,
746 @b{Ref@TeX{}}'s default settings use this method only for section
747 labels. You will be asked to confirm the derived label, or edit
751 We may also use a simple unique number to identify a label. This is
752 mostly useful for labels where it is difficult to come up with a very
753 good descriptive name. @b{Ref@TeX{}}'s default settings use this method
754 for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
755 tends to write documents with many equations and finds it impossible
756 to come up with good names for each of them. These simple labels are
757 inserted without query, and are therefore very fast. Good descriptive
758 names are not really necessary as @b{Ref@TeX{}} will provide context to
759 reference a label (@pxref{Referencing Labels}).
762 The third method is to ask the user for a label. This is most
763 useful for things which are easy to describe briefly and do not turn up
764 too frequently in a document. @b{Ref@TeX{}} uses this for figures and
765 tables. Of course, one can enter the label directly by typing the full
766 @samp{\label@{mark@}}. The advantage of using @code{reftex-label}
767 anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
768 It will then not be necessary to rescan the document in order to access
772 @vindex reftex-insert-label-flags
773 If you want to change the way certain labels are created, check out the
774 variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
777 If you are using AUCTeX to write your LaTeX documents, you can
778 set it up to delegate the creation of labels to
779 @b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
781 @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
782 @section Referencing Labels
783 @cindex Referencing labels
784 @cindex Labels, referencing
785 @cindex Selection buffer, labels
786 @cindex Selection process
789 @findex reftex-reference
791 @vindex reftex-trust-label-prefix
792 @b{Ref@TeX{}} scans the document in order to find all labels. To make
793 referencing labels easier, it assigns to each label a category, the
794 @emph{label type} (for example section, table, figure, equation, etc.).
795 In order to determine the label type, RefTeX parses around each label
796 to see in what kind of environments it is located. You can speed up
797 the parsing by using type-specific prefixes for labels and configuring
798 the variable @code{reftex-trust-label-prefix}.
800 Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c
801 )} in order to reference a label (reftex-reference). This will start a
802 selection process and finally insert the complete @samp{\ref@{label@}}
805 First, @b{Ref@TeX{}} will determine the label category which is required.
806 Often that can be figured out from context. For example, if you
807 write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
808 that an equation label is going to be referenced. If it cannot figure
809 out what label category is needed, it will query for one.
811 You will then be presented with a label selection menu. This is a
812 special buffer which contains an outline of the document along with all
813 labels of the given label category. In addition, next to the label
814 there will be one line of context of the label definition, which is some
815 text in the buffer near the label definition. Usually this is
816 sufficient to identify the label. If you are unsure about a certain
817 label, pressing @key{SPC} will show the label definition point in
820 In order to reference a label, move to cursor to the correct label and
821 press @key{RET}. You can also reference several labels with a single
822 call to @code{reftex-reference} by marking entries with the @kbd{m}
826 Here is a list of special commands in the selection buffer. A summary
827 of this information is always available from the selection process by
833 @tablesubheading{General}
835 Show a summary of available commands.
840 @tablesubheading{Moving around}
845 Go to previous label.
848 Jump back to the position where you last left the selection buffer.
849 Normally this should get you back to the last referenced label.
852 Goto next section heading.
855 Goto previous section heading.
858 Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to
861 @tablesubheading{Displaying Context}
863 Show the surroundings of the definition of the current label in another
864 window. See also the @kbd{f} key.
867 @vindex reftex-revisit-to-follow
868 Toggle follow mode. When follow mode is active, the other window will
869 always display the full context of the current label. This is similar
870 to pressing @key{SPC} after each cursor motion. Note that only context
871 in files already visited is shown. @b{RefTeX} will not visit a file
872 just for follow mode. See, however, the variable
873 @code{reftex-revisit-to-follow}.
876 Show insertion point in another window. This is the point from where you
877 called @code{reftex-reference}.
879 @tablesubheading{Selecting a label and creating the reference}
881 Insert a reference to the label at point into the buffer from which the
882 selection process was started. When entries have been marked, @key{RET}
883 references all marked labels.
886 @vindex reftex-highlight-selection
887 Clicking with mouse button 2 on a label will accept it like @key{RET}
888 would. See also variable @code{reftex-highlight-selection}, @ref{Options
891 @vindex reftex-multiref-punctuation
893 Mark the current entry. When several entries have been marked, pressing
894 @kbd{RET} will accept all of them and place them into several
895 @code{\ref} macros. The special markers @samp{,-+} also store a
896 separator to be inserted before the corresponding reference. So marking
897 six entries with the keys @samp{m , , - , +} will give a reference list
898 like this (see the variable @code{reftex-multiref-punctuation})
900 In eqs. (1), (2), (3)--(4), (5) and (6)
904 Unmark a marked entry.
906 @c FIXME: Do we need `A' as well for consistency?
907 @cindex LaTeX packages, @code{saferef}
908 @cindex @code{saferef}, LaTeX package
910 Accept the marked entries and put all labels as a comma-separated list
911 into one @emph{single} @code{\ref} macro. Some packages like
912 @file{saferef.sty} support multiple references in this way.
915 Use the last referenced label(s) again. This is equivalent to moving to
916 that label and pressing @key{RET}.
919 Enter a label with completion. This may also be a label which does not
920 yet exist in the document.
923 @cindex @code{varioref}, LaTeX package
925 @cindex LaTeX packages, @code{varioref}
926 Toggle between @code{\ref} and @code{\vref} macro for references. The
927 @code{\vref} macro is defined in the @code{varioref} LaTeX package.
928 With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
929 macro. The current state of this flag is displayed by the @samp{S<>}
930 indicator in the mode line of the selection buffer.
933 @cindex @code{fancyref}, LaTeX package
936 @cindex LaTeX packages, @code{fancyref}
937 Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The
938 @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
939 LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a
940 @code{\fref} or @code{\Fref} macro. The current state of this flag is
941 displayed by the @samp{S<>} indicator in the mode line of the
944 @tablesubheading{Exiting}
947 Exit the selection process without inserting any reference into the
950 @tablesubheading{Controlling what gets displayed}
951 @vindex reftex-label-menu-flags
952 The defaults for the following flags can be configured with the variable
953 @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
956 Toggle the display of the one-line label definition context in the
960 Toggle the display of the file borders of a multifile document in the
964 Toggle the display of the table of contents in the selection buffer.
965 With prefix @var{arg}, change the maximum level of toc entries displayed
966 to @var{arg}. Chapters are level 1, section are level 2.
969 Toggle the display of a label counter in the selection buffer.
972 Toggle the display of labels hidden in comments in the selection
973 buffers. Sometimes, you may have commented out parts of your document.
974 If these parts contain label definitions, @b{Ref@TeX{}} can still display
975 and reference these labels.
977 @tablesubheading{Updating the buffer}
979 Update the menu. This will rebuilt the menu from the internal label
980 list, but not reparse the document (see @kbd{r}).
983 @vindex reftex-enable-partial-scans
984 Reparse the document to update the information on all labels and rebuild
985 the menu. If the variable @code{reftex-enable-partial-scans} is
986 non-@code{nil} and your document is a multifile document, this will
987 reparse only a part of the document (the file in which the label at
991 Reparse the @emph{entire} document.
994 Switch the label category. After prompting for another label category,
995 a menu for that category will be shown.
998 Reference a label from an external document. With the LaTeX package
999 @code{xr} it is possible to reference labels defined in another
1000 document. This key will switch to the label menu of an external
1001 document and let you select a label from there (@pxref{xr (LaTeX
1006 @vindex reftex-select-label-map
1007 In order to define additional commands for the selection process, the
1008 keymap @code{reftex-select-label-map} may be used.
1010 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
1011 @section Builtin Label Environments
1012 @cindex Builtin label environments
1013 @cindex Label environments, builtin
1014 @cindex Environments, builtin
1015 @vindex reftex-label-alist
1016 @vindex reftex-label-alist-builtin
1018 @b{Ref@TeX{}} needs to be aware of the environments which can be referenced
1019 with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}
1020 recognizes all labeled environments and macros discussed in @cite{The
1021 LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
1026 @cindex @code{figure}, LaTeX environment
1027 @cindex @code{figure*}, LaTeX environment
1028 @cindex @code{table}, LaTeX environment
1029 @cindex @code{table*}, LaTeX environment
1030 @cindex @code{equation}, LaTeX environment
1031 @cindex @code{eqnarray}, LaTeX environment
1032 @cindex @code{enumerate}, LaTeX environment
1033 @cindex @code{\footnote}, LaTeX macro
1034 @cindex LaTeX macro @code{footnote}
1036 @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
1037 @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
1038 the LaTeX core stuff)
1041 @cindex @code{amsmath}, LaTeX package
1042 @cindex LaTeX packages, @code{amsmath}
1043 @cindex @code{align}, AMS-LaTeX environment
1044 @cindex @code{gather}, AMS-LaTeX environment
1045 @cindex @code{multline}, AMS-LaTeX environment
1046 @cindex @code{flalign}, AMS-LaTeX environment
1047 @cindex @code{alignat}, AMS-LaTeX environment
1048 @cindex @code{xalignat}, AMS-LaTeX environment
1049 @cindex @code{xxalignat}, AMS-LaTeX environment
1050 @cindex @code{subequations}, AMS-LaTeX environment
1051 @code{align}, @code{gather}, @code{multline}, @code{flalign},
1052 @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
1053 (from AMS-LaTeX's @file{amsmath.sty} package)
1055 @cindex @code{endnote}, LaTeX package
1056 @cindex LaTeX packages, @code{endnote}
1057 @cindex @code{\endnote}, LaTeX macro
1058 the @code{\endnote} macro (from @file{endnotes.sty})
1060 @cindex @code{fancybox}, LaTeX package
1061 @cindex LaTeX packages, @code{fancybox}
1062 @cindex @code{Beqnarray}, LaTeX environment
1063 @code{Beqnarray} (@file{fancybox.sty})
1065 @cindex @code{floatfig}, LaTeX package
1066 @cindex LaTeX packages, @code{floatfig}
1067 @cindex @code{floatingfig}, LaTeX environment
1068 @code{floatingfig} (@file{floatfig.sty})
1070 @cindex @code{longtable}, LaTeX package
1071 @cindex LaTeX packages, @code{longtable}
1072 @cindex @code{longtable}, LaTeX environment
1073 @code{longtable} (@file{longtable.sty})
1075 @cindex @code{picinpar}, LaTeX package
1076 @cindex LaTeX packages, @code{picinpar}
1077 @cindex @code{figwindow}, LaTeX environment
1078 @cindex @code{tabwindow}, LaTeX environment
1079 @code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1081 @cindex @code{sidecap}, LaTeX package
1082 @cindex LaTeX packages, @code{sidecap}
1083 @cindex @code{SCfigure}, LaTeX environment
1084 @cindex @code{SCtable}, LaTeX environment
1085 @code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1087 @cindex @code{rotating}, LaTeX package
1088 @cindex LaTeX packages, @code{rotating}
1089 @cindex @code{sidewaysfigure}, LaTeX environment
1090 @cindex @code{sidewaystable}, LaTeX environment
1091 @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1093 @cindex @code{subfig}, LaTeX package
1094 @cindex LaTeX packages, @code{subfigure}
1095 @cindex @code{subfigure}, LaTeX environment
1096 @cindex @code{subfigure*}, LaTeX environment
1097 @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1098 (@file{subfigure.sty})
1100 @cindex @code{supertab}, LaTeX package
1101 @cindex LaTeX packages, @code{supertab}
1102 @cindex @code{supertabular}, LaTeX environment
1103 @code{supertabular} (@file{supertab.sty})
1105 @cindex @code{wrapfig}, LaTeX package
1106 @cindex LaTeX packages, @code{wrapfig}
1107 @cindex @code{wrapfigure}, LaTeX environment
1108 @code{wrapfigure} (@file{wrapfig.sty})
1111 If you want to use other labeled environments, defined with
1112 @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
1113 them (@pxref{Defining Label Environments}).
1115 @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
1116 @section Defining Label Environments
1117 @cindex Label environments, defining
1119 @vindex reftex-label-alist
1120 @b{Ref@TeX{}} can be configured to recognize additional labeled
1121 environments and macros. This is done with the variable
1122 @code{reftex-label-alist} (@pxref{Options (Defining Label
1123 Environments)}). If you are not familiar with Lisp, you can use the
1124 @code{custom} library to configure this rather complex variable. To do
1128 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1131 @vindex reftex-label-alist-builtin
1132 Here we will discuss a few examples, in order to make things clearer.
1133 It can also be instructive to look at the constant
1134 @code{reftex-label-alist-builtin} which contains the entries for
1135 all the builtin environments and macros (@pxref{Builtin Label
1139 * Theorem and Axiom:: Defined with @code{\newenvironment}.
1140 * Quick Equation:: When a macro sets the label type.
1141 * Figure Wrapper:: When a macro argument is a label.
1142 * Adding Magic Words:: Other words for other languages.
1143 * Using \eqref:: How to switch to this AMS-LaTeX macro.
1144 * Non-Standard Environments:: Environments without \begin and \end
1145 * Putting it Together:: How to combine many entries.
1148 @node Theorem and Axiom, Quick Equation, , Defining Label Environments
1149 @subsection Theorem and Axiom Environments
1150 @cindex @code{theorem}, newtheorem
1151 @cindex @code{axiom}, newtheorem
1152 @cindex @code{\newtheorem}
1154 Suppose you are using @code{\newtheorem} in LaTeX in order to define two
1155 new environments, @code{theorem} and @code{axiom}
1158 \newtheorem@{axiom@}@{Axiom@}
1159 \newtheorem@{theorem@}@{Theorem@}
1163 to be used like this:
1172 So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
1173 labeled environments which define their own label categories. We can
1174 either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
1175 library. With Lisp it would look like this
1178 (setq reftex-label-alist
1179 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1180 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3)))
1183 The type indicator characters @code{?a} and @code{?h} are used for
1184 prompts when @b{Ref@TeX{}} queries for a label type. @code{?h}
1185 was chosen for @code{theorem} since @code{?t} is already taken by
1186 @code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
1187 @code{?i}, @code{?n} are already used for standard environments.
1190 The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1191 @samp{thr:}, respectively. @xref{AUCTeX}, for information on how
1192 AUCTeX can use RefTeX to automatically create labels when a new environment
1193 is inserted into a buffer. Additionally, the following needs to be
1194 added to one's .emacs file before AUCTeX will automatically create
1195 labels for the new environments.
1198 (add-hook 'LaTeX-mode-hook
1200 (LaTeX-add-environments
1201 '("axiom" LaTeX-env-label)
1202 '("theorem" LaTeX-env-label))))
1207 The @samp{~\ref@{%s@}} is a format string indicating how to insert
1208 references to these labels.
1211 The next item indicates how to grab context of the label definition.
1214 @code{t} means to get it from a default location (from the beginning of
1215 a @code{\macro} or after the @code{\begin} statement). @code{t} is
1216 @emph{not} a good choice for eqnarray and similar environments.
1218 @code{nil} means to use the text right after the label definition.
1220 For more complex ways of getting context, see the variable
1221 @code{reftex-label-alist} (@ref{Options (Defining Label
1225 The following list of strings is used to guess the correct label type
1226 from the word before point when creating a reference. E.g. if you
1227 write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
1228 @b{Ref@TeX{}} will know that you are looking for a theorem label and
1229 restrict the menu to only these labels without even asking.
1231 The final item in each entry is the level at which the environment
1232 should produce entries in the table of context buffer. If the number is
1233 positive, the environment will produce numbered entries (like
1234 @code{\section}), if it is negative the entries will be unnumbered (like
1235 @code{\section*}). Use this only for environments which structure the
1236 document similar to sectioning commands. For everything else, omit the
1239 To do the same configuration with @code{customize}, you need to click on
1240 the @code{[INS]} button twice to create two templates and fill them in
1244 Reftex Label Alist: [Hide]
1245 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1246 Environment or \macro : [Value Menu] String: axiom
1247 Type specification : [Value Menu] Char : a
1248 Label prefix string : [Value Menu] String: ax:
1249 Label reference format: [Value Menu] String: ~\ref@{%s@}
1250 Context method : [Value Menu] After label
1252 [INS] [DEL] String: axiom
1253 [INS] [DEL] String: ax.
1255 [X] Make TOC entry : [Value Menu] Level: -2
1256 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1257 Environment or \macro : [Value Menu] String: theorem
1258 Type specification : [Value Menu] Char : h
1259 Label prefix string : [Value Menu] String: thr:
1260 Label reference format: [Value Menu] String: ~\ref@{%s@}
1261 Context method : [Value Menu] Default position
1263 [INS] [DEL] String: theorem
1264 [INS] [DEL] String: theor.
1265 [INS] [DEL] String: th.
1267 [X] Make TOC entry : [Value Menu] Level: -3
1270 @vindex reftex-insert-label-flags
1271 @vindex reftex-label-menu-flags
1272 Depending on how you would like the label insertion and selection for
1273 the new environments to work, you might want to add the letters @samp{a}
1274 and @samp{h} to some of the flags in the variables
1275 @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1276 and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1280 @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
1281 @subsection Quick Equation Macro
1282 @cindex Quick equation macro
1283 @cindex Macros as environment wrappers
1285 Suppose you would like to have a macro for quick equations. It
1286 could be defined like this:
1289 \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1296 Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1299 We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
1300 @code{\quickeq} is an equation label. Here is how to do this with lisp:
1303 (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1306 The first element in this list is now the macro with empty braces as an
1307 @emph{image} of the macro arguments. @code{?e} indicates that this is
1308 an equation label, the different @code{nil} elements indicate to use the
1309 default values for equations. The @samp{1} as the fifth element
1310 indicates that the context of the label definition should be the 1st
1311 argument of the macro.
1313 Here is again how this would look in the customization buffer:
1316 Reftex Label Alist: [Hide]
1317 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1318 Environment or \macro : [Value Menu] String: \quickeq@{@}
1319 Type specification : [Value Menu] Char : e
1320 Label prefix string : [Value Menu] Default
1321 Label reference format: [Value Menu] Default
1322 Context method : [Value Menu] Macro arg nr: 1
1325 [ ] Make TOC entry : [Value Menu] No entry
1328 @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
1329 @subsection Figure Wrapping Macro
1330 @cindex Macros as environment wrappers
1331 @cindex Figure wrapping macro
1333 Suppose you want to make figures not directly with the figure
1334 environment, but with a macro like
1337 \newcommand@{\myfig@}[5][tbp]@{%
1338 \begin@{figure@}[#1]
1346 which would be called like
1349 \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1352 Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
1353 @code{\myfig} macro @emph{is itself} a figure label, and where to find
1357 (setq reftex-label-alist
1358 '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1361 The empty pairs of brackets indicate the different arguments of the
1362 @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
1363 indicates that this is a figure label which will be listed together with
1364 labels from normal figure environments. The @code{nil} entries for
1365 prefix and reference format mean to use the defaults for figure labels.
1366 The @samp{3} for the context method means to grab the 3rd macro argument
1369 As a side effect of this configuration, @code{reftex-label} will now
1370 insert the required naked label (without the @code{\label} macro) when
1371 point is directly after the opening parenthesis of a @code{\myfig} macro
1374 Again, here the configuration in the customization buffer:
1377 [INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1378 Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1379 Type specification : [Value Menu] Char : f
1380 Label prefix string : [Value Menu] Default
1381 Label reference format: [Value Menu] Default
1382 Context method : [Value Menu] Macro arg nr: 3
1385 [ ] Make TOC entry : [Value Menu] No entry
1388 @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
1389 @subsection Adding Magic Words
1391 @cindex German magic words
1392 @cindex Label category
1394 Sometimes you don't want to define a new label environment or macro, but
1395 just change the information associated with a label category. Maybe you
1396 want to add some magic words, for another language. Changing only the
1397 information associated with a label category is done by giving
1398 @code{nil} for the environment name and then specify the items you want
1399 to define. Here is an example which adds German magic words to all
1400 predefined label categories.
1403 (setq reftex-label-alist
1404 '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1405 (nil ?e nil nil nil ("Gleichung" "Gl."))
1406 (nil ?t nil nil nil ("Tabelle"))
1407 (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1408 (nil ?n nil nil nil ("Anmerkung" "Anm."))
1409 (nil ?i nil nil nil ("Punkt"))))
1412 @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
1413 @subsection Using @code{\eqref}
1414 @cindex @code{\eqref}, AMS-LaTeX macro
1416 @cindex Label category
1418 Another case where one only wants to change the information associated
1419 with the label category is to change the macro which is used for
1420 referencing the label. When working with the AMS-LaTeX stuff, you might
1421 prefer @code{\eqref} for doing equation references. Here is how to
1425 (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1428 @b{Ref@TeX{}} has also a predefined symbol for this special purpose. The
1429 following is equivalent to the line above.
1432 (setq reftex-label-alist '(AMSTeX))
1435 Note that this is automatically done by the @file{amsmath.el} style file
1436 of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
1437 this configuration will not be necessary.
1439 @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
1440 @subsection Non-standard Environments
1441 @cindex Non-standard environments
1442 @cindex Environments without @code{\begin}
1443 @cindex Special parser functions
1444 @cindex Parser functions, for special environments
1446 Some LaTeX packages define environment-like structures without using the
1447 standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse
1448 these directly, but you can write your own special-purpose parser and
1449 use it instead of the name of an environment in an entry for
1450 @code{reftex-label-alist}. The function should check if point is
1451 currently in the special environment it was written to detect. If so,
1452 it must return a buffer position indicating the start of this
1453 environment. The return value must be @code{nil} on failure to detect
1454 the environment. The function is called with one argument @var{bound}.
1455 If non-@code{nil}, @var{bound} is a boundary for backwards searches
1456 which should be observed. We will discuss two examples.
1458 @cindex LaTeX commands, abbreviated
1460 Some people define abbreviations for
1461 environments, like @code{\be} for @code{\begin@{equation@}}, and
1462 @code{\ee} for @code{\end@{equation@}}. The parser function would have
1463 to search backward for these macros. When the first match is
1464 @code{\ee}, point is not in this environment. When the first match is
1465 @code{\be}, point is in this environment and the function must return
1466 the beginning of the match. To avoid scanning too far, we can also look
1467 for empty lines which cannot occur inside an equation environment.
1471 ;; Setup entry in reftex-label-alist, using all defaults for equations
1472 (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1474 (defun detect-be-ee (bound)
1475 ;; Search backward for the macros or an empty line
1476 (if (re-search-backward
1477 "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1478 (if (match-beginning 2)
1479 (match-beginning 2) ; Return start of environment
1480 nil) ; Return nil because env is closed
1481 nil)) ; Return nil for not found
1484 @cindex @code{linguex}, LaTeX package
1485 @cindex LaTeX packages, @code{linguex}
1486 A more complex example is the @file{linguex.sty} package which defines
1487 list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1488 terminated by @samp{\z.} or by an empty line.
1491 \ex. \label@{ex:12@} Some text in an exotic language ...
1492 \a. \label@{ex:13@} more stuff
1493 \b. \label@{ex:14@} still more stuff
1494 \a. List on a deeper level
1496 \b. and the third one
1498 \b. Third item on this level.
1500 ... text after the empty line terminating all lists
1503 The difficulty is that the @samp{\a.} lists can nest and that an empty
1504 line terminates all list levels in one go. So we have to count nesting
1505 levels between @samp{\a.} and @samp{\z.}. Here is the implementation
1509 (setq reftex-label-alist
1510 '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1512 (defun detect-linguex (bound)
1516 ;; Search backward for all possible delimiters
1518 (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1519 "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1521 ;; Check which delimiter was matched.
1523 ((match-beginning 1)
1524 ;; empty line terminates all - return nil
1526 ((match-beginning 2)
1527 ;; \z. terminates one list level - decrease nesting count
1529 ((match-beginning 3)
1530 ;; \ex. : return match unless there was a \z. on this level
1531 (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1532 ((match-beginning 4)
1533 ;; \a. : return match when on level 0, otherwise
1534 ;; increment nesting count
1536 (throw 'exit (match-beginning 4))
1540 @node Putting it Together, , Non-Standard Environments, Defining Label Environments
1541 @subsection Putting it all together
1543 When you have to put several entries into @code{reftex-label-alist}, just
1544 put them after each other in a list, or create that many templates in
1545 the customization buffer. Here is a lisp example which uses several of
1546 the entries described above:
1549 (setq reftex-label-alist
1550 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1551 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3)
1552 ("\\quickeq@{@}" ?e nil nil 1 nil)
1554 ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1555 (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1558 @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
1559 @section Reference Info
1560 @findex reftex-view-crossref
1561 @findex reftex-mouse-view-crossref
1562 @cindex Cross-references, displaying
1563 @cindex Reference info
1564 @cindex Displaying cross-references
1565 @cindex Viewing cross-references
1569 When point is idle for more than @code{reftex-idle-time} seconds on the
1570 argument of a @code{\ref} macro, the echo area will display some
1571 information about the label referenced there. Note that the information
1572 is only displayed if the echo area is not occupied by a different
1575 @b{Ref@TeX{}} can also display the label definition corresponding to a
1576 @code{\ref} macro, or all reference locations corresponding to a
1577 @code{\label} macro. @xref{Viewing Cross-References}, for more
1580 @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
1581 @section @code{xr}: Cross-Document References
1582 @cindex @code{xr}, LaTeX package
1583 @cindex LaTeX packages, @code{xr}
1584 @cindex @code{\externaldocument}
1585 @cindex External documents
1586 @cindex References to external documents
1587 @cindex Cross-document references
1589 The LaTeX package @code{xr} makes it possible to create references to
1590 labels defined in external documents. The preamble of a document using
1591 @code{xr} will contain something like this:
1595 \externaldocument[V1-]@{volume1@}
1596 \externaldocument[V3-]@{volume3@}
1600 and we can make references to any labels defined in these
1601 external documents by using the prefixes @samp{V1-} and @samp{V3-},
1604 @b{Ref@TeX{}} can be used to create such references as well. Start the
1605 referencing process normally, by pressing @kbd{C-c )}. Select a label
1606 type if necessary. When you see the label selection buffer, pressing
1607 @kbd{x} will switch to the label selection buffer of one of the external
1608 documents. You may then select a label as before and @b{Ref@TeX{}} will
1609 insert it along with the required prefix.
1611 For this kind of inter-document cross-references, saving of parsing
1612 information and the use of multiple selection buffers can mean a large
1613 speed-up (@pxref{Optimizations}).
1615 @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
1616 @section @code{varioref}: Variable Page References
1617 @cindex @code{varioref}, LaTeX package
1618 @cindex @code{\vref}
1619 @cindex LaTeX packages, @code{varioref}
1620 @vindex reftex-vref-is-default
1621 @code{varioref} is a frequently used LaTeX package to create
1622 cross--references with page information. When you want to make a
1623 reference with the @code{\vref} macro, just press the @kbd{v} key in the
1624 selection buffer to toggle between @code{\ref} and @code{\vref}
1625 (@pxref{Referencing Labels}). The mode line of the selection buffer
1626 shows the current status of this switch. If you find that you almost
1627 always use @code{\vref}, you may want to make it the default by
1628 customizing the variable @code{reftex-vref-is-default}. If this
1629 toggling seems too inconvenient, you can also use the command
1630 @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
1631 Or use AUCTeX to create your macros (@pxref{AUCTeX}).
1633 @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
1634 @section @code{fancyref}: Fancy Cross References
1635 @cindex @code{fancyref}, LaTeX package
1636 @cindex @code{\fref}
1637 @cindex @code{\Fref}
1638 @cindex LaTeX packages, @code{fancyref}
1639 @vindex reftex-fref-is-default
1640 @code{fancyref} is a LaTeX package where a macro call like
1641 @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
1642 the referenced counter but also the complete text around it, like
1643 @samp{Figure 3 on the preceding page}. In order to make it work you
1644 need to use label prefixes like @samp{fig:} consistently - something
1645 @b{Ref@TeX{}} does automatically. When you want to make a reference
1646 with the @code{\fref} macro, just press the @kbd{V} key in the selection
1647 buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
1648 (@pxref{Referencing Labels}). The mode line of the selection buffer
1649 shows the current status of this switch. If this cycling seems
1650 inconvenient, you can also use the commands @code{reftex-fancyref-fref}
1651 and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
1652 f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros
1655 @node Citations, Index Support, Labels and References, Top
1658 @cindex @code{\cite}
1660 Citations in LaTeX are done with the @code{\cite} macro or variations of
1661 it. The argument of the macro is a citation key which identifies an
1662 article or book in either a BibTeX database file or in an explicit
1663 @code{thebibliography} environment in the document. @b{Ref@TeX{}}'s
1664 support for citations helps to select the correct key quickly.
1667 * Creating Citations:: How to create them.
1668 * Citation Styles:: Natbib, Harvard, Chicago and Co.
1669 * Citation Info:: View the corresponding database entry.
1670 * Chapterbib and Bibunits:: Multiple bibliographies in a Document.
1671 * Citations Outside LaTeX:: How to make citations in Emails etc.
1672 * BibTeX Database Subsets:: Extract parts of a big database.
1675 @node Creating Citations, Citation Styles, , Citations
1676 @section Creating Citations
1677 @cindex Creating citations
1678 @cindex Citations, creating
1679 @findex reftex-citation
1681 @cindex Selection buffer, citations
1682 @cindex Selection process
1684 In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then
1685 prompts for a regular expression which will be used to search through
1686 the database and present the list of matches to choose from in a
1687 selection process similar to that for selecting labels
1688 (@pxref{Referencing Labels}).
1690 The regular expression uses an extended syntax: @samp{&&} defines a
1691 logic @code{and} for regular expressions. For example
1692 @samp{Einstein&&Bose} will match all articles which mention
1693 Bose-Einstein condensation, or which are co-authored by Bose and
1694 Einstein. When entering the regular expression, you can complete on
1695 known citation keys. RefTeX also offers a default when prompting for a
1696 regular expression. This default is the word before the cursor or the
1697 word before the current @samp{\cite} command. Sometimes this may be a
1700 @cindex @code{\bibliography}
1701 @cindex @code{thebibliography}, LaTeX environment
1702 @cindex @code{BIBINPUTS}, environment variable
1703 @cindex @code{TEXBIB}, environment variable
1704 @b{Ref@TeX{}} prefers to use BibTeX database files specified with a
1705 @code{\bibliography} macro to collect its information. Just like
1706 BibTeX, it will search for the specified files in the current directory
1707 and along the path given in the environment variable @code{BIBINPUTS}.
1708 If you do not use BibTeX, but the document contains an explicit
1709 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
1710 information from there. Note that in this case the information
1711 presented in the selection buffer will just be a copy of relevant
1712 @code{\bibitem} entries, not the structured listing available with
1713 BibTeX database files.
1716 In the selection buffer, the following keys provide special commands. A
1717 summary of this information is always available from the selection
1718 process by pressing @kbd{?}.
1721 @tablesubheading{General}
1723 Show a summary of available commands.
1728 @tablesubheading{Moving around}
1733 Go to previous article.
1735 @tablesubheading{Access to full database entries}
1737 Show the database entry corresponding to the article at point, in
1738 another window. See also the @kbd{f} key.
1741 Toggle follow mode. When follow mode is active, the other window will
1742 always display the full database entry of the current article. This is
1743 equivalent to pressing @key{SPC} after each cursor motion. With BibTeX
1744 entries, follow mode can be rather slow.
1746 @tablesubheading{Selecting entries and creating the citation}
1748 Insert a citation referencing the article at point into the buffer from
1749 which the selection process was started.
1752 @vindex reftex-highlight-selection
1753 Clicking with mouse button 2 on a citation will accept it like @key{RET}
1754 would. See also variable @code{reftex-highlight-selection}, @ref{Options
1758 Mark the current entry. When one or several entries are marked,
1759 pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
1760 @key{RET} behaves like the @kbd{a} key.
1763 Unmark a marked entry.
1766 Accept all (marked) entries in the selection buffer and create a single
1767 @code{\cite} macro referring to them.
1770 Accept all (marked) entries in the selection buffer and create a
1771 separate @code{\cite} macro for each of it.
1774 Create a new BibTeX database file which contains all @i{marked} entries
1775 in the selection buffer. If no entries are marked, all entries are
1779 Create a new BibTeX database file which contains all @i{unmarked}
1780 entries in the selection buffer. If no entries are marked, all entries
1784 Enter a citation key with completion. This may also be a key which does
1788 Show insertion point in another window. This is the point from where you
1789 called @code{reftex-citation}.
1791 @tablesubheading{Exiting}
1793 Exit the selection process without inserting a citation into the
1796 @tablesubheading{Updating the buffer}
1799 Start over with a new regular expression. The full database will be
1800 rescanned with the new expression (see also @kbd{r}).
1802 @c FIXME: Should we use something else here? r is usually rescan!
1804 Refine the current selection with another regular expression. This will
1805 @emph{not} rescan the entire database, but just the already selected
1810 @vindex reftex-select-bib-map
1811 In order to define additional commands for this selection process, the
1812 keymap @code{reftex-select-bib-map} may be used.
1814 @node Citation Styles, Citation Info, Creating Citations, Citations
1815 @section Citation Styles
1816 @cindex Citation styles
1817 @cindex Citation styles, @code{natbib}
1818 @cindex Citation styles, @code{harvard}
1819 @cindex Citation styles, @code{chicago}
1820 @cindex @code{natbib}, citation style
1821 @cindex @code{harvard}, citation style
1822 @cindex @code{chicago}, citation style
1824 @vindex reftex-cite-format
1825 The standard LaTeX macro @code{\cite} works well with numeric or simple
1826 key citations. To deal with the more complex task of author-year
1827 citations as used in many natural sciences, a variety of packages has
1828 been developed which define derived forms of the @code{\cite} macro.
1829 @b{Ref@TeX{}} can be configured to produce these citation macros as well by
1830 setting the variable @code{reftex-cite-format}. For the most commonly
1831 used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
1832 be done from the menu, under @code{Ref->Citation Styles}. Since there
1833 are usually several macros to create the citations, executing
1834 @code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
1835 macro. For the Natbib style, this looks like this:
1838 SELECT A CITATION FORMAT
1845 [e] \citep[e.g.][]@{%l@}
1846 [s] \citep[see][]@{%l@}
1847 [a] \citeauthor@{%l@}
1848 [A] \citeauthor*@{%l@}
1852 @vindex reftex-cite-prompt-optional-args
1853 If cite formats contain empty paris of square brackets, RefTeX can
1854 will prompt for values of these optional arguments if you call the
1855 @code{reftex-citation} command with a @kbd{C-u} prefix.
1856 Following the most generic of these packages, @code{natbib}, the builtin
1857 citation packages always accept the @kbd{t} key for a @emph{textual}
1858 citation (like: @code{Jones et al. (1997) have shown...}) as well as
1859 the @kbd{p} key for a parenthetical citation (like: @code{As shown
1860 earlier (Jones et al, 1997)}).
1862 To make one of these styles the default, customize the variable
1863 @code{reftex-cite-format} or put into @file{.emacs}:
1866 (setq reftex-cite-format 'natbib)
1869 You can also use AUCTeX style files to automatically set the
1870 citation style based on the @code{usepackage} commands in a given
1871 document. @xref{Style Files}, for information on how to set up the style
1874 @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
1875 @section Citation Info
1876 @cindex Displaying citations
1877 @cindex Citations, displaying
1878 @cindex Citation info
1879 @cindex Viewing citations
1882 @findex reftex-view-crossref
1883 @findex reftex-mouse-view-crossref
1885 When point is idle for more than @code{reftex-idle-time} seconds on the
1886 argument of a @code{\cite} macro, the echo area will display some
1887 information about the article cited there. Note that the information is
1888 only displayed if the echo area is not occupied by a different message.
1890 @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
1891 entry corresponding to a @code{\cite} macro, or all citation locations
1892 corresponding to a @code{\bibitem} or BibTeX database entry.
1893 @xref{Viewing Cross-References}.
1895 @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
1896 @section Chapterbib and Bibunits
1897 @cindex @code{chapterbib}, LaTeX package
1898 @cindex @code{bibunits}, LaTeX package
1899 @cindex Bibliographies, multiple
1901 @code{chapterbib} and @code{bibunits} are two LaTeX packages which
1902 produce multiple bibliographies in a document. This is no problem for
1903 @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
1904 files. If they do not, it is best to have each document part in a
1905 separate file (as it is required for @code{chapterbib} anyway). Then
1906 @b{Ref@TeX{}} will still scan the locally relevant databases correctly. If
1907 you have multiple bibliographies within a @emph{single file}, this may
1908 or may not be the case.
1910 @node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations
1911 @section Citations outside LaTeX
1912 @cindex Citations outside LaTeX
1913 @vindex reftex-default-bibliography
1915 The command @code{reftex-citation} can also be executed outside a LaTeX
1916 buffer. This can be useful to reference articles in the mail buffer and
1917 other documents. You should @emph{not} enter @code{reftex-mode} for
1918 this, just execute the command. The list of BibTeX files will in this
1919 case be taken from the variable @code{reftex-default-bibliography}.
1920 Setting the variable @code{reftex-cite-format} to the symbol
1921 @code{locally} does a decent job of putting all relevant information
1922 about a citation directly into the buffer. Here is the lisp code to add
1923 the @kbd{C-c [} binding to the mail buffer. It also provides a local
1924 binding for @code{reftex-cite-format}.
1927 (add-hook 'mail-setup-hook
1928 (lambda () (define-key mail-mode-map "\C-c["
1929 (lambda () (interactive)
1931 (let ((reftex-cite-format 'locally))
1932 (reftex-citation))))))
1935 @node BibTeX Database Subsets, , Citations Outside LaTeX, Citations
1936 @section Database Subsets
1937 @cindex BibTeX database subsets
1938 @findex reftex-create-bibtex-file
1940 @b{Ref@TeX{}} offers two ways to create a new BibTeX database file.
1942 The first option produces a file which contains only the entries
1943 actually referenced in the current document. This can be useful if
1944 the database in only meant for a single document and you want to clean
1945 it of old and unused ballast. It can also be useful while writing a
1946 document together with collaborators, in order to avoid sending around
1947 the entire (possibly very large) database. To create the file, use
1948 @kbd{M-x reftex-create-bibtex-file}, also available from the menu
1949 under @code{Ref->Global Actions->Create Bibtex File}. The command will
1950 prompt for a BibTeX file name and write the extracted entries to that
1953 The second option makes use of the selection process started by the
1954 command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a
1955 regular expression to select entries, and lists them in a formatted
1956 selection buffer. After pressing the @kbd{e} key (mnemonics: Export),
1957 the command will prompt for the name of a new BibTeX file and write
1958 the selected entries to that file. You can also first mark some
1959 entries in the selection buffer with the @kbd{m} key and then export
1960 either the @i{marked} entries (with the @kbd{e} key) or the
1961 @i{unmarked} entries (with the @kbd{E} key).
1963 @node Index Support, Viewing Cross-References, Citations, Top
1964 @chapter Index Support
1965 @cindex Index Support
1966 @cindex @code{\index}
1968 LaTeX has builtin support for creating an Index. The LaTeX core
1969 supports two different indices, the standard index and a glossary. With
1970 the help of special LaTeX packages (@file{multind.sty} or
1971 @file{index.sty}), any number of indices can be supported.
1973 Index entries are created with the @code{\index@{@var{entry}@}} macro.
1974 All entries defined in a document are written out to the @file{.aux}
1975 file. A separate tool must be used to convert this information into a
1976 nicely formatted index. Tools used with LaTeX include @code{MakeIndex}
1979 Indexing is a very difficult task. It must follow strict conventions to
1980 make the index consistent and complete. There are basically two
1981 approaches one can follow, and both have their merits.
1985 Part of the indexing should already be done with the markup. The
1986 document structure should be reflected in the index, so when starting
1987 new sections, the basic topics of the section should be indexed. If the
1988 document contains definitions, theorems or the like, these should all
1989 correspond to appropriate index entries. This part of the index can
1990 very well be developed along with the document. Often it is worthwhile
1991 to define special purpose macros which define an item and at the same
1992 time make an index entry, possibly with special formatting to make the
1993 reference page in the index bold or underlined. To make @b{Ref@TeX{}}
1994 support for indexing possible, these special macros must be added to
1995 @b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}).
1998 The rest of the index is often just a collection of where in the
1999 document certain words or phrases are being used. This part is
2000 difficult to develop along with the document, because consistent entries
2001 for each occurrence are needed and are best selected when the document
2002 is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file}
2003 which collects phrases and helps indexing the phrases globally.
2006 Before you start, you need to make sure that @b{Ref@TeX{}} knows about
2007 the index style being used in the current document. @b{Ref@TeX{}} has
2008 builtin support for the default @code{\index} and @code{\glossary}
2009 macros. Other LaTeX packages, like the @file{multind} or @file{index}
2010 package, redefine the @code{\index} macro to have an additional
2011 argument, and @b{Ref@TeX{}} needs to be configured for those. A
2012 sufficiently new version of AUCTeX (9.10c or later) will do this
2013 automatically. If you really don't use AUCTeX (you should!), this
2014 configuration needs to be done by hand with the menu (@code{Ref->Index
2015 Style}), or globally for all your documents with
2018 (setq reftex-index-macros '(multind)) @r{or}
2019 (setq reftex-index-macros '(index))
2023 * Creating Index Entries:: Macros and completion of entries.
2024 * The Index Phrases File:: A special file for global indexing.
2025 * Displaying and Editing the Index:: The index editor.
2026 * Builtin Index Macros:: The index macros RefTeX knows about.
2027 * Defining Index Macros:: ... and macros it doesn't.
2030 @node Creating Index Entries, The Index Phrases File, , Index Support
2031 @section Creating Index Entries
2032 @cindex Creating index entries
2033 @cindex Index entries, creating
2035 @findex reftex-index
2037 @findex reftex-index-selection-or-word
2039 In order to index the current selection or the word at the cursor press
2040 @kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
2041 selection or word @samp{@var{word}} to be replaced with
2042 @samp{\index@{@var{word}@}@var{word}}. The macro which is used
2043 (@code{\index} by default) can be configured with the variable
2044 @code{reftex-index-default-macro}. When the command is called with a
2045 prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
2046 generated index entry. Use this to change the case of the word or to
2047 make the entry a subentry, for example by entering
2048 @samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
2049 (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
2050 When there is nothing selected and no word at point, this command will
2051 just call @code{reftex-index}, described below.
2053 In order to create a general index entry, press @kbd{C-c <}
2054 (@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the
2055 available index macros and for its arguments. Completion will be
2056 available for the index entry and, if applicable, the index tag. The
2057 index tag is a string identifying one of multiple indices. With the
2058 @file{multind} and @file{index} packages, this tag is the first argument
2059 to the redefined @code{\index} macro.
2061 @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
2062 @section The Index Phrases File
2063 @cindex Index phrase file
2066 @findex reftex-index-visit-phrases-buffer
2067 @cindex Macro definition lines, in phrase buffer
2069 @b{Ref@TeX{}} maintains a file in which phrases can be collected for
2070 later indexing. The file is located in the same directory as the master
2071 file of the document and has the extension @file{.rip} (@b{R}eftex
2072 @b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c
2073 |} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it
2074 is initialized by inserting a file header which contains the definition
2075 of the available index macros. This list is initialized from
2076 @code{reftex-index-macros} (@pxref{Defining Index Macros}). You can
2077 edit the header as needed, but if you define new LaTeX indexing macros,
2078 don't forget to add them to @code{reftex-index-macros} as well. Here is
2079 a phrase file header example:
2082 % -*- mode: reftex-index-phrases -*-
2083 % Key Macro Format Repeat
2084 %----------------------------------------------------------
2085 >>>INDEX_MACRO_DEFINITION: i \index@{%s@} t
2086 >>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil
2087 >>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t
2088 >>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil
2089 %----------------------------------------------------------
2092 The macro definition lines consist of a unique letter identifying a
2093 macro, a format string and the @var{repeat} flag, all separated by
2094 @key{TAB}. The format string shows how the macro is to be applied, the
2095 @samp{%s} will be replaced with the index entry. The repeat flag
2096 indicates if @var{word} is indexed by the macro as
2097 @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
2098 @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the
2099 above example it is assumed that the macro @code{\index*@{@var{word}@}}
2100 already typesets its argument in the text, so that it is unnecessary to
2101 repeat @var{word} outside the macro.
2104 * Collecting Phrases:: Collecting from document or external.
2105 * Consistency Checks:: Check for duplicates etc.
2106 * Global Indexing:: The interactive indexing process.
2109 @node Collecting Phrases, Consistency Checks, , The Index Phrases File
2110 @subsection Collecting Phrases
2111 @cindex Collecting index phrases
2112 @cindex Index phrases, collection
2113 @cindex Phrases, collecting
2115 Phrases for indexing can be collected while writing the document. The
2116 command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2117 copies the current selection (if active) or the word near point into the
2118 phrases buffer. It then selects this buffer, so that the phrase line
2119 can be edited. To return to the LaTeX document, press @kbd{C-c C-c}
2120 (@code{reftex-index-phrases-save-and-return}).
2122 You can also prepare the list of index phrases in a different way and
2123 copy it into the phrases file. For example you might want to start from
2124 a word list of the document and remove all words which should not be
2127 The phrase lines in the phrase buffer must have a specific format.
2128 @b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
2129 format. A phrase line looks like this:
2132 [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
2135 @code{<TABs>} stands for white space containing at least one @key{TAB}.
2136 @var{key} must be at the start of the line and is the character
2137 identifying one of the macros defined in the file header. It is
2138 optional - when omitted, the first macro definition line in the file
2139 will be used for this phrase. The @var{phrase} is the phrase to be
2140 searched for when indexing. It may contain several words separated by
2141 spaces. By default the search phrase is also the text entered as
2142 argument of the index macro. If you want the index entry to be
2143 different from the search phrase, enter another @key{TAB} and the index
2144 argument @var{arg}. If you want to have each match produce several
2145 index entries, separate the different index arguments with @samp{ &&
2146 }@footnote{@samp{&&} with optional spaces, see
2147 @code{reftex-index-phrases-logical-and-regexp}.}. If you want to be
2148 able to choose at each match between several different index arguments,
2149 separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2150 see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an
2154 %--------------------------------------------------------------------
2158 Jupiter Planets!Jupiter
2159 i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2160 i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto
2164 So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2165 @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2166 @samp{Vega} will be indexed as a subitem of @samp{Stars}. The
2167 @samp{Jupiter} line will also use the @samp{i} macro as it was the first
2168 macro definition in the file header (see above example). At each
2169 occurrence of @samp{Mars} you will be able choose between indexing it as
2170 a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2171 Finally, every occurrence of @samp{Pluto} will be indexed as
2172 @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2173 and will therefore create two different index entries.
2175 @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
2176 @subsection Consistency Checks
2177 @cindex Index phrases, consistency checks
2178 @cindex Phrases, consistency checks
2179 @cindex Consistency check for index phrases
2182 Before indexing the phrases in the phrases buffer, they should be
2183 checked carefully for consistency. A first step is to sort the phrases
2184 alphabetically - this is done with the command @kbd{C-c C-s}
2185 (@code{reftex-index-sort-phrases}). It will sort all phrases in the
2186 buffer alphabetically by search phrase. If you want to group certain
2187 phrases and only sort within the groups, insert empty lines between the
2188 groups. Sorting will only change the sequence of phrases within each
2189 group (see the variable @code{reftex-index-phrases-sort-in-blocks}).
2192 A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2193 which lists information about the phrase at point, including an example
2194 of how the index entry will look like and the number of expected matches
2198 Another important check is to find out if there are double or
2199 overlapping entries in the buffer. For example if you are first
2200 searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2201 second phrase will not match because of the index macro inserted before
2202 @samp{Mars} earlier. The command @kbd{C-c C-t}
2203 (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2204 the buffer which is either duplicate or a subphrase of another phrase.
2205 In order to check the whole buffer like this, start at the beginning and
2206 execute this command repeatedly.
2208 @node Global Indexing, , Consistency Checks, The Index Phrases File
2209 @subsection Global Indexing
2210 @cindex Global indexing
2211 @cindex Indexing, global
2212 @cindex Indexing, from @file{phrases} buffer
2214 Once the index phrases have been collected and organized, you are set
2215 for global indexing. I recommend to do this only on an otherwise
2216 finished document. Global indexing starts from the phrases buffer.
2217 There are several commands which start indexing: @kbd{C-c C-x} acts on
2218 the current phrase line, @kbd{C-c C-r} on all lines in the current
2219 region and @kbd{C-c C-a} on all phrase lines in the buffer. It is
2220 probably good to do indexing in small chunks since your concentration
2221 may not last long enough to do everything in one go.
2223 @b{Ref@TeX{}} will start at the first phrase line and search the phrase
2224 globally in the whole document. At each match it will stop, compute the
2225 replacement string and offer you the following choices@footnote{Windows
2226 users: Restrict yourself to the described keys during indexing. Pressing
2227 @key{Help} at the indexing prompt can apparently hang Emacs.}:
2231 Replace this match with the proposed string.
2235 Replace this and all further matches in this file.
2237 Skip this match, start with next file.
2239 Skip this match, start with next phrase.
2241 Select a different indexing macro for this match.
2243 Select one of multiple index keys (those separated with @samp{||}).
2245 Edit the replacement text.
2247 Recursive edit. Use @kbd{C-M-c} to return to the indexing process.
2249 Save this buffer and ask again about the current match.
2251 Save all document buffers and ask again about the current match.
2253 Abort the indexing process.
2256 The @samp{Find and Index in Document} menu in the phrases buffer also
2257 lists a few options for the indexing process. The options have
2258 associated customization variables to set the defaults (@pxref{Options
2259 (Index Support)}). Here is a short explanation of what the options do:
2262 @item Match Whole Words
2263 When searching for index phrases, make sure whole words are matched.
2264 This should probably always be on.
2265 @item Case Sensitive Search
2266 Search case sensitively for phrases. I recommend to have this setting
2267 off, in order to match the capitalized words at the beginning of a
2268 sentence, and even typos. You can always say @emph{no} at a match you
2270 @item Wrap Long Lines
2271 Inserting index macros increases the line length. Turn this option on
2272 to allow @b{Ref@TeX{}} to wrap long lines.
2273 @item Skip Indexed Matches
2274 When this is on, @b{Ref@TeX{}} will at each match try to figure out if
2275 this match is already indexed. A match is considered indexed if it is
2276 either the argument of an index macro, or if an index macro is directly
2277 (without whitespace separation) before or after the match. Index macros
2278 are those configured in @code{reftex-index-macros}. Intended for
2279 re-indexing a documents after changes have been made.
2282 Even though indexing should be the last thing you do to a document, you
2283 are bound to make changes afterwards. Indexing then has to be applied
2284 to the changed regions. The command
2285 @code{reftex-index-phrases-apply-to-region} is designed for this
2286 purpose. When called from a LaTeX document with active region, it will
2287 apply @code{reftex-index-all-phrases} to the current region.
2289 @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support
2290 @section Displaying and Editing the Index
2291 @cindex Displaying the Index
2292 @cindex Editing the Index
2293 @cindex Index entries, creating
2294 @cindex Index, displaying
2295 @cindex Index, editing
2297 @findex reftex-display-index
2299 In order to compile and display the index, press @kbd{C-c >}. If the
2300 document uses multiple indices, @b{Ref@TeX{}} will ask you to select
2301 one. Then, all index entries will be sorted alphabetically and
2302 displayed in a special buffer, the @file{*Index*} buffer. From that
2303 buffer you can check and edit each entry.
2305 The index can be restricted to the current section or the region. Then
2306 only entries in that part of the document will go into the compiled
2307 index. To restrict to the current section, use a numeric prefix
2308 @samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
2309 region, make the region active and use a numeric prefix @samp{3} (press
2310 @kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
2311 restriction can be moved from one section to the next by pressing the
2312 @kbd{<} and @kbd{>} keys.
2314 One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
2315 by searching near the buffer position where it had found to macro during
2316 scanning. If you have several identical index entries in the same
2317 buffer and significant changes have shifted the entries around, you must
2318 rescan the buffer to ensure the correspondence between the
2319 @file{*Index*} buffer and the definition locations. It is therefore
2320 advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2321 frequently while editing the index from the @file{*Index*}
2325 Here is a list of special commands available in the @file{*Index*} buffer. A
2326 summary of this information is always available by pressing
2330 @tablesubheading{General}
2332 Display a summary of commands.
2337 @tablesubheading{Moving around}
2339 Pressing any capital letter will jump to the corresponding section in
2340 the @file{*Index*} buffer. The exclamation mark is special and jumps to
2341 the first entries alphabetically sorted below @samp{A}. These are
2342 usually non-alphanumeric characters.
2346 Go to previous entry.
2348 @tablesubheading{Access to document locations}
2350 Show the place in the document where this index entry is defined.
2353 Go to the definition of the current index entry in another
2357 Go to the definition of the current index entry and hide the
2358 @file{*Index*} buffer window.
2361 @vindex reftex-index-follow-mode
2362 @vindex reftex-revisit-to-follow
2363 Toggle follow mode. When follow mode is active, the other window will
2364 always show the location corresponding to the line in the @file{*Index*}
2365 buffer at point. This is similar to pressing @key{SPC} after each
2366 cursor motion. The default for this flag can be set with the variable
2367 @code{reftex-index-follow-mode}. Note that only context in files
2368 already visited is shown. @b{Ref@TeX{}} will not visit a file just for
2369 follow mode. See, however, the variable
2370 @code{reftex-revisit-to-follow}.
2372 @tablesubheading{Entry editing}
2374 Edit the current index entry. In the minibuffer, you can edit the
2375 index macro which defines this entry.
2378 Kill the index entry. Currently not implemented because I don't know
2379 how to implement an @code{undo} function for this.
2382 Edit the @var{key} part of the entry. This is the initial part of the
2383 entry which determines the location of the entry in the index.
2386 Edit the @var{attribute} part of the entry. This is the part after the
2387 vertical bar. With @code{MakeIndex}, this part is an encapsulating
2388 macro. With @code{xindy}, it is called @emph{attribute} and is a
2389 property of the index entry that can lead to special formatting. When
2390 called with @kbd{C-u} prefix, kill the entire @var{attribute}
2394 Edit the @var{visual} part of the entry. This is the part after the
2395 @samp{@@} which is used by @code{MakeIndex} to change the visual
2396 appearance of the entry in the index. When called with @kbd{C-u}
2397 prefix, kill the entire @var{visual} part.
2400 Toggle the beginning of page range property @samp{|(} of the
2404 Toggle the end of page range property @samp{|)} of the entry.
2407 Make the current entry a subentry. This command will prompt for the
2408 superordinate entry and insert it.
2411 Remove the highest superordinate entry. If the current entry is a
2412 subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2415 @tablesubheading{Exiting}
2417 Hide the @file{*Index*} buffer.
2420 Kill the @file{*Index*} buffer.
2423 Switch to the Table of Contents buffer of this document.
2425 @tablesubheading{Controlling what gets displayed}
2427 @vindex reftex-index-include-context
2428 Toggle the display of short context in the @file{*Index*} buffer. The
2429 default for this flag can be set with the variable
2430 @code{reftex-index-include-context}.
2433 Restrict the index to a single document section. The corresponding
2434 section number will be displayed in the @code{R<>} indicator in the
2435 mode line and in the header of the @file{*Index*} buffer.
2438 Widen the index to contain all entries of the document.
2441 When the index is currently restricted, move the restriction to the
2445 When the index is currently restricted, move the restriction to the
2448 @tablesubheading{Updating the buffer}
2450 Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
2451 document. However, it sorts the entries again, so that edited entries
2452 will move to the correct position.
2455 @vindex reftex-enable-partial-scans
2456 Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When
2457 @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
2458 location is defined in, not the entire document.
2461 Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
2465 Switch to a different index (for documents with multiple
2470 @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
2471 @section Builtin Index Macros
2472 @cindex Builtin index macros
2473 @cindex Index macros, builtin
2474 @vindex reftex-index-macros
2475 @cindex @code{multind}, LaTeX package
2476 @cindex @code{index}, LaTeX package
2477 @cindex LaTeX packages, @code{multind}
2478 @cindex LaTeX packages, @code{index}
2480 @b{Ref@TeX{}} by default recognizes the @code{\index} and
2481 @code{\glossary} macros which are defined in the LaTeX core. It has
2482 also builtin support for the re-implementations of @code{\index}
2483 in the @file{multind} and @file{index} packages. However, since
2484 the different definitions of the @code{\index} macro are incompatible,
2485 you will have to explicitly specify the index style used.
2486 @xref{Creating Index Entries}, for information on how to do that.
2488 @node Defining Index Macros, , Builtin Index Macros, Index Support
2489 @section Defining Index Macros
2490 @cindex Defining Index Macros
2491 @cindex Index macros, defining
2492 @vindex reftex-index-macros
2494 When writing a document with an index you will probably define
2495 additional macros which make entries into the index.
2496 Let's look at an example.
2499 \newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2500 \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2501 \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2504 The first macro @code{\ix} typesets its argument in the text and places
2505 it into the index. The second macro @code{\nindex} typesets its
2506 argument in the text and places it into a separate index with the tag
2507 @samp{name}@footnote{We are using the syntax of the @file{index} package
2508 here.}. The last macro also places its argument into the index, but as
2509 subitems under the main index entry @samp{Astronomical Objects}. Here
2510 is how to make @b{Ref@TeX{}} recognize and correctly interpret these
2511 macros, first with Emacs Lisp.
2514 (setq reftex-index-macros
2515 '(("\\ix@{*@}" "idx" ?x "" nil nil)
2516 ("\\nindex@{*@}" "name" ?n "" nil nil)
2517 ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2520 Note that the index tag is @samp{idx} for the main index, and
2521 @samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
2522 for the default index and for the glossary.
2524 The character arguments @code{?x}, @code{?n}, and @code{?o} are for
2525 quick identification of these macros when @b{Ref@TeX{}} inserts new
2526 index entries with @code{reftex-index}. These codes need to be
2527 unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2528 @code{\index}, @code{\index*}, and @code{\glossary} macros,
2531 The following string is empty unless your macro adds a superordinate
2532 entry to the index key - this is the case for the @code{\astobj} macro.
2534 The next entry can be a hook function to exclude certain matches, it
2535 almost always can be @code{nil}.
2537 The final element in the list indicates if the text being indexed needs
2538 to be repeated outside the macro. For the normal index macros, this
2539 should be @code{t}. Only if the macro typesets the entry in the text
2540 (like @code{\ix} and @code{\nindex} in the example do), this should be
2543 To do the same thing with customize, you need to fill in the templates
2549 Macro with args: \ix@{*@}
2550 Index Tag : [Value Menu] String: idx
2553 Exclusion hook : nil
2554 Repeat Outside : [Toggle] off (nil)
2556 Macro with args: \nindex@{*@}
2557 Index Tag : [Value Menu] String: name
2560 Exclusion hook : nil
2561 Repeat Outside : [Toggle] off (nil)
2563 Macro with args: \astobj@{*@}
2564 Index Tag : [Value Menu] String: idx
2566 Key Prefix : Astronomical Objects!
2567 Exclusion hook : nil
2568 Repeat Outside : [Toggle] on (non-nil)
2572 With the macro @code{\ix} defined, you may want to change the default
2573 macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2574 This would be done like this
2577 (setq reftex-index-default-macro '(?x "idx"))
2580 which specifies that the macro identified with the character @code{?x} (the
2581 @code{\ix} macro) should be used for indexing phrases and words already
2582 in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2583 The index tag is "idx".
2585 @node Viewing Cross-References, RefTeXs Menu, Index Support, Top
2586 @chapter Viewing Cross--References
2587 @findex reftex-view-crossref
2588 @findex reftex-mouse-view-crossref
2592 @b{Ref@TeX{}} can display cross--referencing information. This means,
2593 if two document locations are linked, @b{Ref@TeX{}} can display the
2594 matching location(s) in another window. The @code{\label} and @code{\ref}
2595 macros are one way of establishing such a link. Also, a @code{\cite}
2596 macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
2599 The feature is invoked by pressing @kbd{C-c &}
2600 (@code{reftex-view-crossref}) while point is on the @var{key} argument
2601 of a macro involved in cross--referencing. You can also click with
2602 @kbd{S-mouse-2} on the macro argument. Here is what will happen for
2603 individual classes of macros:
2609 Display the corresponding label definition. All usual
2610 variants@footnote{all macros that start with @samp{ref} or end with
2611 @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
2612 cross--reference display. This works also for labels defined in an
2613 external document when the current document refers to them through the
2614 @code{xr} interface (@pxref{xr (LaTeX package)}).
2617 @cindex @code{\label}
2618 @vindex reftex-label-alist
2619 Display a document location which references this label. Pressing
2620 @kbd{C-c &} several times moves through the entire document and finds
2621 all locations. Not only the @code{\label} macro but also other macros
2622 with label arguments (as configured with @code{reftex-label-alist}) are
2623 active for cross--reference display.
2626 @cindex @code{\cite}
2627 Display the corresponding BibTeX database entry or @code{\bibitem}.
2628 All usual variants@footnote{all macros that either start or end with
2629 @samp{cite}} of the @code{\cite} macro are active for cross--reference
2632 @item @code{\bibitem}
2633 @cindex @code{\bibitem}
2634 Display a document location which cites this article. Pressing
2635 @kbd{C-c &} several times moves through the entire document and finds
2639 @cindex BibTeX buffer, viewing cite locations from
2640 @cindex Viewing cite locations from BibTeX buffer
2641 @kbd{C-c &} is also active in BibTeX buffers. All locations in a
2642 document where the database entry at point is cited will be displayed.
2643 On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
2644 the document you want to search. Subsequent calls will use the same
2645 document, until you break this link with a prefix argument to @kbd{C-c
2649 @cindex @code{\index}
2650 Display other locations in the document which are marked by an index
2651 macro with the same key argument. Along with the standard @code{\index}
2652 and @code{\glossary} macros, all macros configured in
2653 @code{reftex-index-macros} will be recognized.
2656 @vindex reftex-view-crossref-extra
2657 While the display of cross referencing information for the above
2658 mentioned macros is hard--coded, you can configure additional relations
2659 in the variable @code{reftex-view-crossref-extra}.
2662 @chapter All the Rest
2665 @node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
2666 @section @b{Ref@TeX{}}'s Menu
2667 @cindex RefTeXs Menu
2668 @cindex Menu, in the menu bar
2670 @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
2671 which support this. From this menu you can access all of
2672 @b{Ref@TeX{}}'s commands and a few of its options. There is also a
2673 @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
2674 entire set of options.
2676 @node Key Bindings, Faces, RefTeXs Menu, Top
2677 @section Default Key Bindings
2678 @cindex Key Bindings, summary
2680 Here is a summary of the available key bindings.
2695 @kbd{C-c =} @code{reftex-toc}
2696 @kbd{C-c -} @code{reftex-toc-recenter}
2697 @kbd{C-c (} @code{reftex-label}
2698 @kbd{C-c )} @code{reftex-reference}
2699 @kbd{C-c [} @code{reftex-citation}
2700 @kbd{C-c &} @code{reftex-view-crossref}
2701 @kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
2702 @kbd{C-c /} @code{reftex-index-selection-or-word}
2703 @kbd{C-c \} @code{reftex-index-phrase-selection-or-word}
2704 @kbd{C-c |} @code{reftex-index-visit-phrases-buffer}
2705 @kbd{C-c <} @code{reftex-index}
2706 @kbd{C-c >} @code{reftex-display-index}
2709 Note that the @kbd{S-mouse-2} binding is only provided if this key is
2710 not already used by some other package. @b{Ref@TeX{}} will not override an
2711 existing binding to @kbd{S-mouse-2}.
2713 Personally, I also bind some functions in the users @kbd{C-c} map for
2716 @c FIXME: Do we need bindings for the Index macros here as well?
2717 @c C-c i C-c I or so????
2718 @c How about key bindings for reftex-reset-mode and reftex-parse-document?
2727 @kbd{C-c t} @code{reftex-toc}
2728 @kbd{C-c l} @code{reftex-label}
2729 @kbd{C-c r} @code{reftex-reference}
2730 @kbd{C-c c} @code{reftex-citation}
2731 @kbd{C-c v} @code{reftex-view-crossref}
2732 @kbd{C-c s} @code{reftex-search-document}
2733 @kbd{C-c g} @code{reftex-grep-document}
2736 @noindent These keys are reserved for the user, so I cannot bind them by
2737 default. If you want to have these key bindings available, set in your
2740 @vindex reftex-extra-bindings
2742 (setq reftex-extra-bindings t)
2745 @vindex reftex-load-hook
2746 Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook
2747 @code{reftex-load-hook}. For information on the keymaps
2748 which should be used to add keys, see @ref{Keymaps and Hooks}.
2750 @node Faces, AUCTeX, Key Bindings, Top
2754 @b{Ref@TeX{}} uses faces when available to structure the selection and
2755 table of contents buffers. It does not create its own faces, but uses
2756 the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will
2757 use faces only when @code{font-lock} is loaded. This seems to be
2758 reasonable because people who like faces will very likely have it
2759 loaded. If you wish to turn off fontification or change the involved
2760 faces, see @ref{Options (Fontification)}.
2762 @node Multifile Documents, Language Support, AUCTeX, Top
2763 @section Multifile Documents
2764 @cindex Multifile documents
2765 @cindex Documents, spread over files
2767 The following is relevant when working with documents spread over many
2772 @b{Ref@TeX{}} has full support for multifile documents. You can edit parts of
2773 several (multifile) documents at the same time without conflicts.
2774 @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
2775 @code{query-replace} on all files which are part of a multifile
2779 @vindex tex-main-file
2781 All files belonging to a multifile document should define a File
2782 Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
2783 standard Emacs LaTeX mode) containing the name of the master file. For
2784 example, to set the file variable @code{TeX-master}, include something
2785 like the following at the end of each TeX file:
2788 %%% Local Variables: ***
2790 %%% TeX-master: "thesis.tex" ***
2794 AUCTeX with the setting
2797 (setq-default TeX-master nil)
2800 will actually ask you for each new file about the master file and insert
2801 this comment automatically. For more details see the documentation of
2802 the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
2803 documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2804 The GNU Emacs Manual}) and the Emacs documentation on File Variables
2805 (@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
2808 The context of a label definition must be found in the same file as the
2809 label itself in order to be processed correctly by @b{Ref@TeX{}}. The only
2810 exception is that section labels referring to a section statement
2811 outside the current file can still use that section title as
2815 @node Language Support, Finding Files, Multifile Documents, Top
2816 @section Language Support
2817 @cindex Language support
2819 Some parts of @b{Ref@TeX{}} are language dependent. The default
2820 settings work well for English. If you are writing in a different
2821 language, the following hints may be useful:
2825 @vindex reftex-derive-label-parameters
2826 @vindex reftex-abbrev-parameters
2827 The mechanism to derive a label from context includes the abbreviation
2828 of words and omission of unimportant words. These mechanisms may have
2829 to be changed for other languages. See the variables
2830 @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2833 @vindex reftex-translate-to-ascii-function
2834 @vindex reftex-label-illegal-re
2835 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
2836 context string from non-ASCII characters in order to make a valid label.
2837 If there should ever be a version of @TeX{} which allows extended
2838 characters @emph{in labels}, then we will have to look at the
2839 variables @code{reftex-translate-to-ascii-function} and
2840 @code{reftex-label-illegal-re}.
2843 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
2844 to guess which label type is required. These @emph{magic words} are
2845 different in every language. For an example of how to add magic words,
2846 see @ref{Adding Magic Words}.
2848 @vindex reftex-multiref-punctuation
2849 @vindex reftex-cite-punctuation
2851 @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
2852 for the author list in citations. Some of this may be language
2853 dependent. See the variables @code{reftex-multiref-punctuation} and
2854 @code{reftex-cite-punctuation}.
2857 @node Finding Files, Optimizations, Language Support, Top
2858 @section Finding Files
2859 @cindex Finding files
2861 In order to find files included in a document via @code{\input} or
2862 @code{\include}, @b{Ref@TeX{}} searches all directories specified in the
2863 environment variable @code{TEXINPUTS}. Similarly, it will search the
2864 path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
2865 BibTeX database files.
2867 When searching, @b{Ref@TeX{}} will also expand recursive path
2868 definitions (directories ending in @samp{//} or @samp{!!}). But it will
2869 only search and expand directories @emph{explicitly} given in these
2870 variables. This may cause problems under the following circumstances:
2874 Most TeX system have a default search path for both TeX files and BibTeX
2875 files which is defined in some setup file. Usually this default path is
2876 for system files which @b{Ref@TeX{}} does not need to see. But if your
2877 document needs TeX files or BibTeX database files in a directory only
2878 given in the default search path, @b{Ref@TeX{}} will fail to find them.
2880 Some TeX systems do not use environment variables at all in order to
2881 specify the search path. Both default and user search path are then
2882 defined in setup files.
2886 There are three ways to solve this problem:
2890 Specify all relevant directories explicitly in the environment
2891 variables. If for some reason you don't want to mess with the default
2892 variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
2893 variables and configure @b{Ref@TeX{}} to use them instead:
2896 (setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
2897 (setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
2901 Specify the full search path directly in @b{Ref@TeX{}}'s variables.
2904 (setq reftex-texpath-environment-variables
2905 '("./inp:/home/cd/tex//:/usr/local/tex//"))
2906 (setq reftex-bibpath-environment-variables
2907 '("/home/cd/tex/lit/"))
2911 Some TeX systems provide stand--alone programs to do the file search just
2912 like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the
2913 @code{kpathsearch} library which provides the command @code{kpsewhich}
2914 to search for files. @b{Ref@TeX{}} can be configured to use this
2915 program. Note that the exact syntax of the @code{kpsewhich}
2916 command depends upon the version of that program.
2919 (setq reftex-use-external-file-finders t)
2920 (setq reftex-external-file-finders
2921 '(("tex" . "kpsewhich -format=.tex %f")
2922 ("bib" . "kpsewhich -format=.bib %f")))
2927 @vindex reftex-file-extensions
2928 @vindex TeX-file-extensions
2929 Some people like to use RefTeX with noweb files, which usually have the
2930 extension @file{.nw}. In order to deal with such files, the new
2931 extension must be added to the list of valid extensions in the variable
2932 @code{reftex-file-extensions}. When working with AUCTeX as major mode,
2933 the new extension must also be known to AUCTeX via the variable
2934 @code{TeX-file-extension}. For example:
2937 (setq reftex-file-extensions
2938 '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
2939 (setq TeX-file-extensions
2940 '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
2943 @node Optimizations, Problems and Work-Arounds, Finding Files, Top
2944 @section Optimizations
2945 @cindex Optimizations
2947 @b{Note added 2002. Computers have gotten a lot faster, so most of the
2948 optimizations discussed below will not be necessary on new machines. I
2949 am leaving this stuff in the manual for people who want to write thick
2950 books, where some of it still might be useful.}
2952 Implementing the principle of least surprises, the default settings of
2953 @b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
2954 when using @b{Ref@TeX{}} for a large project and/or on a small computer,
2955 there are ways to improve speed or memory usage.
2959 @b{Removing Lookup Buffers}@*
2960 @cindex Removing lookup buffers
2961 @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
2962 database files for lookup purposes. These buffers are kept, so that
2963 subsequent use of the same files is fast. If you can't afford keeping
2964 these buffers around, and if you can live with a speed penalty, try
2966 @vindex reftex-keep-temporary-buffers
2968 (setq reftex-keep-temporary-buffers nil)
2972 @b{Partial Document Scans}@*
2973 @cindex Partial documents scans
2974 @cindex Document scanning, partial
2975 A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
2976 (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
2977 @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
2978 =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
2979 re-parsing of the entire document in order to update the parsing
2980 information. For a large document this can be unnecessary, in
2981 particular if only one file has changed. @b{Ref@TeX{}} can be configured
2982 to do partial scans instead of full ones. @kbd{C-u} re-parsing then
2983 does apply only to the current buffer and files included from it.
2984 Likewise, the @kbd{r} key in both the label selection buffer and the
2985 table-of-contents buffer will only prompt scanning of the file in which
2986 the label or section macro near the cursor was defined. Re-parsing of
2987 the entire document is still available by using @kbd{C-u C-u} as a
2988 prefix, or the capital @kbd{R} key in the menus. To use this feature,
2991 @vindex reftex-enable-partial-scans
2993 (setq reftex-enable-partial-scans t)
2997 @b{Saving Parser Information}@*
2998 @cindex Saving parser information
2999 @cindex Parse information, saving to a file
3000 @vindex reftex-parse-file-extension
3001 Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
3002 scan, when you start working with a document. To avoid this, parsing
3003 information can be stored in a file. The file @file{MASTER.rel} is used
3004 for storing information about a document with master file
3005 @file{MASTER.tex}. It is written automatically when you kill a buffer
3006 in @code{reftex-mode} or when you exit Emacs. The information is
3007 restored when you begin working with a document in a new editing
3008 session. To use this feature, put into @file{.emacs}:
3010 @vindex reftex-save-parse-info
3012 (setq reftex-save-parse-info t)
3016 @b{Identifying label types by prefix}@*
3017 @cindex Parse information, saving to a file
3018 @vindex reftex-trust-label-prefix
3019 @b{Ref@TeX{}} normally parses around each label to check in which
3020 environment this label is located, in order to assign a label type to
3021 the label. If your document contains thousands of labels, document
3022 parsing will take considerable time. If you have been using label prefixes
3023 like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the
3024 label type directly from the prefix, without additional parsing. This
3025 will be faster and also allow labels to end up in the correct category
3026 if for some reason it is not possible to derive the correct type from
3027 context. For example, to enable this feature for footnote and
3028 equation labels, use
3031 (setq reftex-trust-label-prefix '("fn:" "eq:"))
3035 @b{Automatic Document Scans}@*
3036 @cindex Automatic document scans
3037 @cindex Document scanning, automatic
3038 At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
3039 document. If this gets into your way, it can be turned off with
3041 @vindex reftex-allow-automatic-rescan
3043 (setq reftex-allow-automatic-rescan nil)
3046 @b{Ref@TeX{}} will then occasionally annotate new labels in the selection
3047 buffer, saying that their position in the label list in uncertain. A
3048 manual document scan will fix this.
3051 @b{Multiple Selection Buffers}@*
3052 @cindex Multiple selection buffers
3053 @cindex Selection buffers, multiple
3054 Normally, the selection buffer @file{*RefTeX Select*} is re-created for
3055 every selection process. In documents with very many labels this can
3056 take several seconds. @b{Ref@TeX{}} provides an option to create a
3057 separate selection buffer for each label type and to keep this buffer
3058 from one selection to the next. These buffers are updated automatically
3059 only when a new label has been added in the buffers category with
3060 @code{reftex-label}. Updating the buffer takes as long as recreating it
3061 - so the time saving is limited to cases where no new labels of that
3062 category have been added. To turn on this feature, use
3064 @vindex reftex-use-multiple-selection-buffers
3066 (setq reftex-use-multiple-selection-buffers t)
3070 @cindex Selection buffers, updating
3071 You can also inhibit the automatic updating entirely. Then the
3072 selection buffer will always pop up very fast, but may not contain the
3073 most recently defined labels. You can always update the buffer by hand,
3074 with the @kbd{g} key. To get this behavior, use instead
3076 @vindex reftex-auto-update-selection-buffers
3078 (setq reftex-use-multiple-selection-buffers t
3079 reftex-auto-update-selection-buffers nil)
3085 @b{As a summary}, here are the settings I recommend for heavy use of
3086 @b{Ref@TeX{}} with large documents:
3090 (setq reftex-enable-partial-scans t
3091 reftex-save-parse-info t
3092 reftex-use-multiple-selection-buffers t)
3096 @node AUCTeX, Multifile Documents, Faces, Top
3098 @cindex @code{AUCTeX}, Emacs package
3099 @cindex Emacs packages, @code{AUCTeX}
3101 AUCTeX is without doubt the best major mode for editing TeX and LaTeX
3102 files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
3103 If AUCTeX is not part of your Emacs distribution, you can get
3104 it@footnote{XEmacs 21.x users may want to install the corresponding
3105 XEmacs package.} by ftp from the @value{AUCTEXSITE}.
3108 * AUCTeX-RefTeX Interface:: How both packages work together
3109 * Style Files:: AUCTeX's style files can support RefTeX
3110 * Bib-Cite:: Hypertext reading of a document
3113 @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
3114 @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
3116 @b{Ref@TeX{}} contains code to interface with AUCTeX. When this
3117 interface is turned on, both packages will interact closely. Instead of
3118 using @b{Ref@TeX{}}'s commands directly, you can then also use them
3119 indirectly as part of the AUCTeX
3120 environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
3121 needed for all of this to work. Parts of it work also with earlier
3122 versions.}. The interface is turned on with
3125 (setq reftex-plug-into-AUCTeX t)
3128 If you need finer control about which parts of the interface are used
3129 and which not, read the docstring of the variable
3130 @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
3131 customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
3133 The following list describes the individual parts of the interface.
3137 @findex reftex-label
3138 @vindex LaTeX-label-function, @r{AUCTeX}
3141 @findex LaTeX-section, @r{AUCTeX}
3142 @findex TeX-insert-macro, @r{AUCTeX}
3143 @b{AUCTeX calls @code{reftex-label} to insert labels}@*
3144 When a new section is created with @kbd{C-c C-s}, or a new environment
3145 is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
3146 go with it. With the interface, @code{reftex-label} is called instead.
3147 For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
3148 @b{Ref@TeX{}} will insert
3158 without further prompts.
3160 Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
3161 will offer its default label which is derived from the section title.
3164 @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
3165 When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
3166 have to rescan the buffer in order to see it.
3169 @findex reftex-arg-label
3170 @findex TeX-arg-label, @r{AUCTeX function}
3171 @findex reftex-arg-ref
3172 @findex TeX-arg-ref, @r{AUCTeX function}
3173 @findex reftex-arg-cite
3174 @findex TeX-arg-cite, @r{AUCTeX function}
3175 @findex reftex-arg-index
3176 @findex TeX-arg-index, @r{AUCTeX function}
3177 @findex TeX-insert-macro, @r{AUCTeX function}
3178 @kindex C-c @key{RET}
3179 @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
3180 interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
3181 macro arguments. Internally, it uses the functions
3182 @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3183 prompt for arguments which are labels, citation keys and index entries.
3184 The interface takes over these functions@footnote{@code{fset} is used to
3185 do this, which is not reversible. However, @b{Ref@TeX{}} implements the
3186 old functionality when you later decide to turn off the interface.} and
3187 supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For
3188 example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
3189 will supply its label selection process (@pxref{Referencing
3193 @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
3194 @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
3197 @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
3198 @subsection Style Files
3199 @cindex Style files, AUCTeX
3200 @findex TeX-add-style-hook, @r{AUCTeX}
3201 Style files are Emacs Lisp files which are evaluated by AUCTeX in
3202 association with the @code{\documentclass} and @code{\usepackage}
3203 commands of a document (@pxref{Style Files,,,auctex}). Support for
3204 @b{Ref@TeX{}} in such a style file is useful when the LaTeX style
3205 defines macros or environments connected with labels, citations, or the
3206 index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el})
3207 distributed with AUCTeX already support @b{Ref@TeX{}} in this
3210 Before calling a @b{Ref@TeX{}} function, the style hook should always
3211 test for the availability of the function, so that the style file will
3212 also work for people who do not use @b{Ref@TeX{}}.
3214 Additions made with style files in the way described below remain local
3215 to the current document. For example, if one package uses AMSTeX, the
3216 style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
3217 this will not affect other documents.
3219 @findex reftex-add-label-environments
3220 @findex reftex-add-to-label-alist
3221 A style hook may contain calls to
3222 @code{reftex-add-label-environments}@footnote{This used to be the
3223 function @code{reftex-add-to-label-alist} which is still available as an
3224 alias for compatibility.} which defines additions to
3225 @code{reftex-label-alist}. The argument taken by this function must have
3226 the same format as @code{reftex-label-alist}. The @file{amsmath.el}
3227 style file of AUCTeX for example contains the following:
3231 (TeX-add-style-hook "amsmath"
3233 (if (fboundp 'reftex-add-label-environments)
3234 (reftex-add-label-environments '(AMSTeX)))))
3239 @findex LaTeX-add-environments, @r{AUCTeX}
3240 while a package @code{myprop} defining a @code{proposition} environment
3241 with @code{\newtheorem} might use
3245 (TeX-add-style-hook "myprop"
3247 (LaTeX-add-environments '("proposition" LaTeX-env-label))
3248 (if (fboundp 'reftex-add-label-environments)
3249 (reftex-add-label-environments
3250 '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3251 ("Proposition" "Prop.") -3))))))
3255 @findex reftex-set-cite-format
3256 Similarly, a style hook may contain a call to
3257 @code{reftex-set-cite-format} to set the citation format. The style
3258 file @file{natbib.el} for the Natbib citation style does switch
3259 @b{Ref@TeX{}}'s citation format like this:
3262 (TeX-add-style-hook "natbib"
3264 (if (fboundp 'reftex-set-cite-format)
3265 (reftex-set-cite-format 'natbib))))
3268 @findex reftex-add-index-macros
3269 The hook may contain a call to @code{reftex-add-index-macros} to
3270 define additional @code{\index}-like macros. The argument must have
3271 the same format as @code{reftex-index-macros}. It may be a symbol, to
3272 trigger support for one of the builtin index packages. For example,
3273 the style @file{multind.el} contains
3276 (TeX-add-style-hook "multind"
3278 (and (fboundp 'reftex-add-index-macros)
3279 (reftex-add-index-macros '(multind)))))
3282 If you have your own package @file{myindex} which defines the
3283 following macros to be used with the LaTeX @file{index.sty} file
3285 \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3286 \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3289 you could write this in the style file @file{myindex.el}:
3292 (TeX-add-style-hook "myindex"
3295 '("molec" TeX-arg-index)
3296 '("aindex" TeX-arg-index))
3297 (if (fboundp 'reftex-add-index-macros)
3298 (reftex-add-index-macros
3299 '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3300 ("aindex@{*@}" "author" ?a "" nil nil))))))
3303 @findex reftex-add-section-levels
3304 Finally the hook may contain a call to @code{reftex-add-section-levels}
3305 to define additional section statements. For example, the FoilTeX class
3306 has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
3307 is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
3310 (TeX-add-style-hook "foils"
3312 (if (fboundp 'reftex-add-section-levels)
3313 (reftex-add-section-levels '(("foilhead" . 3)
3314 ("rotatefoilhead" . 3))))))
3317 @node Bib-Cite, , Style Files, AUCTeX
3318 @subsection Bib-Cite
3319 @cindex @code{bib-cite}, Emacs package
3320 @cindex Emacs packages, @code{bib-cite}
3322 Once you have written a document with labels, references and citations,
3323 it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has
3324 support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3325 &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3326 @code{reftex-search-document}. A somewhat fancier interface with mouse
3327 highlighting is provided (among other things) by Peter S. Galbraith's
3328 @file{bib-cite.el}. There is some overlap in the functionalities of
3329 Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with
3332 Bib-cite version 3.06 and later can be configured so that bib-cite's
3333 mouse functions use @b{Ref@TeX{}} for displaying references and citations.
3334 This can be useful in particular when working with the LaTeX @code{xr}
3335 package or with an explicit @code{thebibliography} environment (rather
3336 than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To
3337 make use of this feature, try
3339 @vindex bib-cite-use-reftex-view-crossref
3341 (setq bib-cite-use-reftex-view-crossref t)
3345 @node Problems and Work-Arounds, Imprint, Optimizations, Top
3346 @section Problems and Work-arounds
3347 @cindex Problems and work-arounds
3351 @b{LaTeX commands}@*
3352 @cindex LaTeX commands, not found
3353 @code{\input}, @code{\include}, and @code{\section} (etc.) statements
3354 have to be first on a line (except for white space).
3357 @b{Commented regions}@*
3358 @cindex Labels, commented out
3359 @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
3360 make duplicates of such labels. This is considered to be a feature.
3363 @b{Wrong section numbers}@*
3364 @cindex Section numbers, wrong
3365 @vindex reftex-enable-partial-scans
3366 When using partial scans (@code{reftex-enable-partial-scans}), the section
3367 numbers in the table of contents may eventually become wrong. A full
3371 @b{Local settings}@*
3372 @cindex Settings, local
3373 @findex reftex-add-label-environments
3374 @findex reftex-set-cite-format
3375 @findex reftex-add-section-levels
3376 The label environment definitions in @code{reftex-label-alist} are
3377 global and apply to all documents. If you need to make definitions
3378 local to a document, because they would interfere with settings in other
3379 documents, you should use AUCTeX and set up style files with calls to
3380 @code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3381 @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3382 Settings made with these functions remain local to the current
3383 document. @xref{AUCTeX}.
3386 @b{Funny display in selection buffer}@*
3387 @cindex @code{x-symbol}, Emacs package
3388 @cindex Emacs packages, @code{x-symbol}
3389 @cindex @code{isotex}, Emacs package
3390 @cindex Emacs packages, @code{isotex}
3391 @cindex @code{iso-cvt}, Emacs package
3392 @cindex Emacs packages, @code{iso-cvt}
3393 When using packages which make the buffer representation of a file
3394 different from its disk representation (e.g. x-symbol, isotex,
3395 iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
3396 reflects the disk state of a file. This happens only in @emph{unvisited}
3397 parts of a multifile document, because @b{Ref@TeX{}} visits these files
3398 literally for speed reasons. Then both short context and section
3399 headings may look different from what you usually see on your screen.
3400 In rare cases @code{reftex-toc} may have problems to jump to an affected
3401 section heading. There are three possible ways to deal with
3405 @vindex reftex-keep-temporary-buffers
3406 @code{(setq reftex-keep-temporary-buffers t)}@*
3407 This implies that @b{Ref@TeX{}} will load all parts of a multifile
3408 document into Emacs (i.e. there won't be any temporary buffers).
3410 @vindex reftex-initialize-temporary-buffers
3411 @code{(setq reftex-initialize-temporary-buffers t)}@*
3412 This means full initialization of temporary buffers. It involves
3413 a penalty when the same unvisited file is used for lookup often.
3415 Set @code{reftex-initialize-temporary-buffers} to a list of hook
3416 functions doing a minimal initialization.
3418 @vindex reftex-refontify-context
3419 See also the variable @code{reftex-refontify-context}.
3422 @b{Labels as arguments to \begin}@*
3423 @cindex @code{pf}, LaTeX package
3424 @cindex LaTeX packages, @code{pf}
3425 Some packages use an additional argument to a @code{\begin} macro
3426 to specify a label. E.g. Lamport's @file{pf.sty} uses both
3428 \step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
3434 We need to trick @b{Ref@TeX{}} into swallowing this:
3438 ;; Configuration for Lamport's pf.sty
3439 (setq reftex-label-alist
3440 '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3441 ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3446 The first line is just a normal configuration for a macro. For the
3447 @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
3448 @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3449 argument (which really is a second argument to the macro @code{\begin})
3450 as a label of type @code{?p}. Argument count for this macro starts only
3451 after the @samp{@{step+@}}, also when specifying how to get
3455 @b{Idle timers in XEmacs}@*
3456 @cindex Idle timer restart
3457 @vindex reftex-use-itimer-in-xemacs
3458 In XEmacs, idle timer restart does not work reliably after fast
3459 keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command
3460 hook to start the timer used for automatic crossref information. When
3461 this bug gets fixed, a real idle timer can be requested with
3463 (setq reftex-use-itimer-in-xemacs t)
3469 @cindex Key bindings, problems with Viper mode
3470 @findex viper-harness-minor-mode
3471 With @i{Viper} mode prior to Vipers version 3.01, you need to protect
3472 @b{Ref@TeX{}}'s keymaps with
3475 (viper-harness-minor-mode "reftex")
3481 @node Imprint, Commands, Problems and Work-Arounds, Top
3485 @cindex Acknowledgments
3488 @cindex @code{http}, @b{Ref@TeX{}} home page
3489 @cindex @code{ftp}, @b{Ref@TeX{}} site
3491 @b{Ref@TeX{}} was written by @i{Carsten Dominik}
3492 @email{dominik@@science.uva.nl}, with contributions by @i{Stephen
3493 Eglen}. @b{Ref@TeX{}} is currently maintained by
3496 Carsten Dominik <dominik@@science.uva.nl>
3498 If you have questions about @b{Ref@TeX{}}, there are several Usenet
3499 groups which have competent readers: @code{comp.emacs},
3500 @code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex},
3501 @code{de.comp.text.tex}. You can also write directly to the
3504 If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
3505 to contribute code or ideas, please @value{MAINTAINERCONTACT}. Remember
3506 to provide all necessary information such as version numbers of Emacs
3507 and @b{Ref@TeX{}}, and the relevant part of your configuration in
3508 @file{.emacs}. When reporting a bug which throws an exception, please
3509 include a backtrace if you know how to produce one.
3511 @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
3512 It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
3513 21.x users want to install the corresponding plugin package which is
3514 available from the @value{XEMACSFTP}. See the XEmacs 21.x
3515 documentation on package installation for details.
3517 Users of earlier Emacs distributions (including Emacs 19) can get a
3518 @b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that
3519 the Emacs 19 version supports many but not all features described in
3522 Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
3523 developing it with their reports. In particular thanks to @i{Fran
3524 Burstall, Alastair Burt, Lars Clausen, Soren Dayton, Stephen Eglen,
3525 Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai Grossjohann, Frank
3526 Harrell, Peter Heslin, Stephan Heuel, Alan Ho, Lute Kamstra, Dieter
3527 Kraft, David Kastrup, Adrian Lanz, Juri Linkov, Rory Molinari, Stefan
3528 Monnier, Laurent Mugnier, Dan Nicolaescu, Sudeep Kumar Palat, Daniel
3529 Polani, Alan Shutko, Robin Socha, Richard Stanton, Allan Strand, Jan
3530 Vroonhof, Christoph Wedler, Alan Williams, Roland Winkler,
3531 Hans-Christoph Wirth, Eli Zaretskii}.
3534 The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3537 Finally thanks to @i{Uwe Bolick} who first got me interested in
3538 supporting LaTeX labels and references with an editor (which was
3539 MicroEmacs at the time).
3541 @node Commands, Options, Imprint, Top
3543 @cindex Commands, list of
3545 Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
3546 LaTeX files. Command which are executed from the special buffers are
3547 not described here. All commands are available from the @code{Ref}
3548 menu. See @xref{Key Bindings}.
3550 @deffn Command reftex-toc
3551 Show the table of contents for the current document. When called with
3552 one ore two @kbd{C-u} prefixes, rescan the document first.
3555 @deffn Command reftex-label
3556 Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
3557 document rescan first.
3560 @deffn Command reftex-reference
3561 Start a selection process to select a label, and insert a reference to
3562 it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
3565 @deffn Command reftex-citation
3566 Make a citation using BibTeX database files. After prompting for a regular
3567 expression, scans the buffers with BibTeX entries (taken from the
3568 @code{\bibliography} command or a @code{thebibliography} environment)
3569 and offers the matching entries for selection. The selected entry is
3570 formatted according to @code{reftex-cite-format} and inserted into the
3572 When called with a @kbd{C-u} prefixe, prompt for optional arguments in
3573 cite macros. When called with a numeric prefix, make that many citations.
3574 When called with point inside the braces of a @code{\cite} command, it
3575 will add another key, ignoring the value of
3576 @code{reftex-cite-format}. @*
3577 The regular expression uses an expanded syntax: @samp{&&} is interpreted
3578 as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
3579 both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
3580 on knows citation keys is possible. @samp{=} is a good regular
3581 expression to match all entries in all files.
3584 @deffn Command reftex-index
3585 Query for an index macro and insert it along with its arguments. The
3586 index macros available are those defined in @code{reftex-index-macro} or
3587 by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
3588 style file. @b{Ref@TeX{}} provides completion for the index tag and the
3589 index key, and will prompt for other arguments.
3592 @deffn Command reftex-index-selection-or-word
3593 Put current selection or the word near point into the default index
3594 macro. This uses the information in @code{reftex-index-default-macro}
3595 to make an index entry. The phrase indexed is the current selection or
3596 the word near point. When called with one @kbd{C-u} prefix, let the
3597 user have a chance to edit the index entry. When called with 2
3598 @kbd{C-u} as prefix, also ask for the index macro and other stuff. When
3599 called inside TeX math mode as determined by the @file{texmathp.el}
3600 library which is part of AUCTeX, the string is first processed with the
3601 @code{reftex-index-math-format}, which see.
3604 @deffn Command reftex-index-phrase-selection-or-word
3605 Add current selection or the word at point to the phrases buffer.
3606 When you are in transient-mark-mode and the region is active, the
3607 selection will be used - otherwise the word at point.
3608 You get a chance to edit the entry in the phrases buffer - to save the
3609 buffer and return to the LaTeX document, finish with @kbd{C-c C-c}.
3612 @deffn Command reftex-index-visit-phrases-buffer
3613 Switch to the phrases buffer, initialize if empty.
3616 @deffn Command reftex-index-phrases-apply-to-region
3617 Index all index phrases in the current region.
3618 This works exactly like global indexing from the index phrases buffer,
3619 but operation is restricted to the current region.
3622 @deffn Command reftex-display-index
3623 Display a buffer with an index compiled from the current document.
3624 When the document has multiple indices, first prompts for the correct one.
3625 When index support is turned off, offer to turn it on.
3626 With one or two @kbd{C-u} prefixes, rescan document first.
3627 With prefix 2, restrict index to current document section.
3628 With prefix 3, restrict index to active region.
3631 @deffn Command reftex-view-crossref
3632 View cross reference of macro at point. Point must be on the @var{key}
3633 argument. Works with the macros @code{\label}, @code{\ref},
3634 @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3635 these. Where it makes sense, subsequent calls show additional
3636 locations. See also the variable @code{reftex-view-crossref-extra} and
3637 the command @code{reftex-view-crossref-from-bibtex}. With one or two
3638 @kbd{C-u} prefixes, enforce rescanning of the document. With argument
3639 2, select the window showing the cross reference.
3642 @deffn Command reftex-view-crossref-from-bibtex
3643 View location in a LaTeX document which cites the BibTeX entry at point.
3644 Since BibTeX files can be used by many LaTeX documents, this function
3645 prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
3646 link to a document, call the function with a prefix arg. Calling
3647 this function several times find successive citation locations.
3650 @deffn Command reftex-create-tags-file
3651 Create TAGS file by running @code{etags} on the current document. The
3652 TAGS file is also immediately visited with
3653 @code{visit-tags-table}.
3656 @deffn Command reftex-grep-document
3657 Run grep query through all files related to this document.
3658 With prefix arg, force to rescan document.
3659 No active TAGS table is required.
3662 @deffn Command reftex-search-document
3663 Regexp search through all files of the current document.
3664 Starts always in the master file. Stops when a match is found.
3665 No active TAGS table is required.
3668 @deffn Command reftex-query-replace-document
3669 Run a query-replace-regexp of @var{from} with @var{to} over the entire
3670 document. With prefix arg, replace only word-delimited matches. No
3671 active TAGS table is required.
3674 @deffn Command reftex-isearch-minor-mode
3675 Toggle a minor mode which enables incremental search to work globally
3676 on the entire multifile document. Files will be searched in th
3677 sequence they appear in the document.
3680 @deffn Command reftex-goto-label
3681 Prompt for a label (with completion) and jump to the location of this
3682 label. Optional prefix argument @var{other-window} goes to the label in
3687 @deffn Command reftex-change-label
3688 Query replace @var{from} with @var{to} in all @code{\label} and
3689 @code{\ref} commands. Works on the entire multifile document. No
3690 active TAGS table is required.
3693 @deffn Command reftex-renumber-simple-labels
3694 Renumber all simple labels in the document to make them sequentially.
3695 Simple labels are the ones created by RefTeX, consisting only of the
3696 prefix and a number. After the command completes, all these labels will
3697 have sequential numbers throughout the document. Any references to the
3698 labels will be changed as well. For this, @b{Ref@TeX{}} looks at the
3699 arguments of any macros which either start or end with the string
3700 @samp{ref}. This command should be used with care, in particular in
3701 multifile documents. You should not use it if another document refers
3702 to this one with the @code{xr} package.
3705 @deffn Command reftex-find-duplicate-labels
3706 Produce a list of all duplicate labels in the document.
3709 @deffn Command reftex-create-bibtex-file
3710 Create a new BibTeX database file with all entries referenced in document.
3711 The command prompts for a filename and writes the collected entries to
3712 that file. Only entries referenced in the current document with
3713 any @code{\cite}-like macros are used.
3714 The sequence in the new file is the same as it was in the old database.
3717 @deffn Command reftex-customize
3718 Run the customize browser on the @b{Ref@TeX{}} group.
3720 @deffn Command reftex-show-commentary
3721 Show the commentary section from @file{reftex.el}.
3723 @deffn Command reftex-info
3724 Run info on the top @b{Ref@TeX{}} node.
3726 @deffn Command reftex-parse-document
3727 Parse the entire document in order to update the parsing information.
3729 @deffn Command reftex-reset-mode
3730 Enforce rebuilding of several internal lists and variables. Also
3731 removes the parse file associated with the current document.
3734 @node Options, Keymaps and Hooks, Commands, Top
3735 @chapter Options, Keymaps, Hooks
3736 @cindex Options, list of
3738 Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All
3739 variables have customize support - so if you are not familiar with Emacs
3740 Lisp (and even if you are) you might find it more comfortable to use
3741 @code{customize} to look at and change these variables. @kbd{M-x
3742 reftex-customize} will get you there.
3745 * Options (Table of Contents)::
3746 * Options (Defining Label Environments)::
3747 * Options (Creating Labels)::
3748 * Options (Referencing Labels)::
3749 * Options (Creating Citations)::
3750 * Options (Index Support)::
3751 * Options (Viewing Cross-References)::
3752 * Options (Finding Files)::
3753 * Options (Optimizations)::
3754 * Options (Fontification)::
3758 @node Options (Table of Contents), Options (Defining Label Environments), , Options
3759 @section Table of Contents
3760 @cindex Options, table of contents
3761 @cindex Table of contents, options
3763 @defopt reftex-include-file-commands
3764 List of LaTeX commands which input another file.
3765 The file name is expected after the command, either in braces or separated
3769 @defopt reftex-max-section-depth
3770 Maximum depth of section levels in document structure.
3771 Standard LaTeX needs 7, default is 12.
3774 @defopt reftex-section-levels
3775 Commands and levels used for defining sections in the document. The
3776 @code{car} of each cons cell is the name of the section macro. The
3777 @code{cdr} is a number indicating its level. A negative level means the
3778 same as the positive value, but the section will never get a number.
3779 The @code{cdr} may also be a function which then has to return the
3780 level. This list is also used for promotion and demption of sectioning
3781 commands. If you are using a document class which has several sets of
3782 sectioning commands, promotion only works correctly if this list is
3783 sorted first by set, then within each set by level. The promotion
3784 commands always select the nearest entry with the correct new level.
3788 @defopt reftex-toc-max-level
3789 The maximum level of toc entries which will be included in the TOC.
3790 Section headings with a bigger level will be ignored. In RefTeX,
3791 chapters are level 1, sections level 2 etc. This variable can be
3792 changed from within the @file{*toc*} buffer with the @kbd{t} key.
3795 @defopt reftex-part-resets-chapter
3796 Non-@code{nil} means, @code{\part} is like any other sectioning command.
3797 This means, part numbers will be included in the numbering of chapters, and
3798 chapter counters will be reset for each part.
3799 When @code{nil} (the default), parts are special, do not reset the
3800 chapter counter and also do not show up in chapter numbers.
3803 @defopt reftex-auto-recenter-toc
3804 Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
3805 When active, the @file{*TOC*} window will always show the section you
3806 are currently working in. Recentering happens whenever Emacs is idle for
3807 more than @code{reftex-idle-time} seconds.
3809 Value @code{t} means, turn on immediately when RefTeX gets started. Then,
3810 recentering will work for any toc window created during the session.
3812 Value @code{frame} (the default) means, turn automatic recentering on
3813 only while the dedicated TOC frame does exist, and do the recentering
3814 only in that frame. So when creating that frame (with @kbd{d} key in an
3815 ordinary TOC window), the automatic recentering is turned on. When the
3816 frame gets destroyed, automatic recentering is turned off again.
3818 This feature can be turned on and off from the menu
3822 @defopt reftex-toc-split-windows-horizontally
3823 Non-@code{nil} means, create TOC window by splitting window
3824 horizontally. The default is to split vertically.
3827 @defopt reftex-toc-split-windows-fraction
3828 Fraction of the width or height of the frame to be used for TOC window.
3831 @defopt reftex-toc-keep-other-windows
3832 Non-@code{nil} means, split the selected window to display the
3833 @file{*toc*} buffer. This helps to keep the window configuration, but
3834 makes the @file{*toc*} small. When @code{nil}, all other windows except
3835 the selected one will be deleted, so that the @file{*toc*} window fills
3839 @defopt reftex-toc-include-file-boundaries
3840 Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3841 This flag can be toggled from within the @file{*toc*} buffer with the
3845 @defopt reftex-toc-include-labels
3846 Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
3847 can be toggled from within the @file{*toc*} buffer with the @kbd{l}
3851 @defopt reftex-toc-include-index-entries
3852 Non-@code{nil} means, include index entries in @file{*toc*} buffer.
3853 This flag can be toggled from within the @file{*toc*} buffer with the
3857 @defopt reftex-toc-include-context
3858 Non-@code{nil} means, include context with labels in the @file{*toc*}
3859 buffer. Context will only be shown if the labels are visible as well.
3860 This flag can be toggled from within the @file{*toc*} buffer with the
3864 @defopt reftex-toc-follow-mode
3865 Non-@code{nil} means, point in @file{*toc*} buffer (the
3866 table-of-contents buffer) will cause other window to follow. The other
3867 window will show the corresponding part of the document. This flag can
3868 be toggled from within the @file{*toc*} buffer with the @kbd{f}
3872 @deffn {Normal Hook} reftex-toc-mode-hook
3873 Normal hook which is run when a @file{*toc*} buffer is
3877 @deffn Keymap reftex-toc-map
3878 The keymap which is active in the @file{*toc*} buffer.
3879 (@pxref{Table of Contents}).
3882 @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
3883 @section Defining Label Environments
3884 @cindex Options, defining label environments
3885 @cindex Defining label environments, options
3887 @defopt reftex-default-label-alist-entries
3888 Default label alist specifications. It is a list of symbols with
3889 associations in the constant @code{reftex-label-alist-builtin}.
3890 @code{LaTeX} should always be the last entry.
3893 @defopt reftex-label-alist
3894 Set this variable to define additions and changes to the defaults in
3895 @code{reftex-default-label-alist-entries}. The only things you
3896 @emph{must not} change is that @code{?s} is the type indicator for
3897 section labels, and @key{SPC} for the @code{any} label type. These are
3898 hard-coded at other places in the code.
3900 The value of the variable must be a list of items. Each item is a list
3901 itself and has the following structure:
3904 (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
3905 @var{context-method} (@var{magic-word} ... ) @var{toc-level})
3908 Each list entry describes either an environment carrying a counter for
3909 use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
3910 label as (or inside) one of its arguments. The elements of each list
3914 @item @var{env-or-macro}
3915 Name of the environment (like @samp{table}) or macro (like
3916 @samp{\myfig}). For macros, indicate the arguments, as in
3917 @samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
3918 arguments, a star to mark the label argument, if any. The macro does
3919 not have to have a label argument - you could also use
3920 @samp{\label@{...@}} inside one of its arguments.
3922 Special names: @code{section} for section labels, @code{any} to define a
3923 group which contains all labels.
3925 This may also be a function to do local parsing and identify point to be
3926 in a non-standard label environment. The function must take an
3927 argument @var{bound} and limit backward searches to this value. It
3928 should return either nil or a cons cell @code{(@var{function}
3929 . @var{position})} with the function symbol and the position where the
3930 special environment starts. See the Info documentation for an
3933 Finally this may also be @code{nil} if the entry is only meant to change
3934 some settings associated with the type indicator character (see
3937 @item @var{type-key}
3938 Type indicator character, like @code{?t}, must be a printable ASCII
3939 character. The type indicator is a single character which defines a
3940 label type. Any label inside the environment or macro is assumed to
3941 belong to this type. The same character may occur several times in this
3942 list, to cover cases in which different environments carry the same
3943 label type (like @code{equation} and @code{eqnarray}). If the type
3944 indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
3945 the macro defines neutral labels just like @code{\label}. In this case
3946 the reminder of this entry is ignored.
3948 @item @var{label-prefix}
3949 Label prefix string, like @samp{tab:}. The prefix is a short string
3950 used as the start of a label. It may be the empty string. The prefix
3951 may contain the following @samp{%} escapes:
3954 %f Current file name, directory and extension stripped.
3955 %F Current file name relative to master file directory.
3956 %m Master file name, directory and extension stripped.
3957 %M Directory name (without path) where master file is located.
3958 %u User login name, on systems which support this.
3959 %S A section prefix derived with variable @code{reftex-section-prefixes}.
3963 Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
3966 @item @var{reference-format}
3967 Format string for reference insert in buffer. @samp{%s} will be
3968 replaced by the label. When the format starts with @samp{~}, this
3969 @samp{~} will only be inserted when the character before point is
3970 @emph{not} a whitespace.
3972 @item @var{context-method}
3973 Indication on how to find the short context.
3976 If @code{nil}, use the text following the @samp{\label@{...@}} macro.
3981 the section heading for section labels.
3983 text following the @samp{\begin@{...@}} statement of environments (not
3984 a good choice for environments like eqnarray or enumerate, where one has
3985 several labels in a single environment).
3987 text after the macro name (starting with the first arg) for
3991 If an integer, use the nth argument of the macro. As a special case,
3992 1000 means to get text after the last macro argument.
3994 If a string, use as regexp to search @emph{backward} from the label.
3995 Context is then the text following the end of the match. E.g. putting
3996 this to @samp{\\caption[[@{]} will use the caption in a figure or table
3997 environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
4000 If any of @code{caption}, @code{item}, @code{eqnarray-like},
4001 @code{alignat-like}, this symbol will internally be translated into an
4002 appropriate regexp (see also the variable
4003 @code{reftex-default-context-regexps}).
4005 If a function, call this function with the name of the environment/macro
4006 as argument. On call, point will be just after the @code{\label} macro.
4007 The function is expected to return a suitable context string. It should
4008 throw an exception (error) when failing to find context. As an example,
4009 here is a function returning the 10 chars following the label macro as
4013 (defun my-context-function (env-or-mac)
4014 (if (> (point-max) (+ 10 (point)))
4015 (buffer-substring (point) (+ 10 (point)))
4016 (error "Buffer too small")))
4020 Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
4021 menu, and to derive a label string. If you want to use a different
4022 method for each of these, specify them as a dotted pair.
4023 E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
4024 display, and text from the default position (@code{t}) to derive a label
4025 string. This is actually used for section labels.
4027 @item @var{magic-word-list}
4028 List of magic words which identify a reference to be of this type. If
4029 the word before point is equal to one of these words when calling
4030 @code{reftex-reference}, the label list offered will be automatically
4031 restricted to labels of the correct type. If the first element of this
4032 word--list is the symbol `regexp', the strings are interpreted as regular
4035 @item @var{toc-level}
4036 The integer level at which this environment should be added to the table
4037 of contents. See also @code{reftex-section-levels}. A positive value
4038 will number the entries mixed with the sectioning commands of the same
4039 level. A negative value will make unnumbered entries. Useful only for
4040 theorem-like environments which structure the document. Will be ignored
4041 for macros. When omitted or @code{nil}, no TOC entries will be
4045 If the type indicator characters of two or more entries are the same,
4046 @b{Ref@TeX{}} will use
4049 the first non-@code{nil} format and prefix
4051 the magic words of all involved entries.
4054 Any list entry may also be a symbol. If that has an association in
4055 @code{reftex-label-alist-builtin}, the @code{cddr} of that association is
4056 spliced into the list. However, builtin defaults should normally be set
4057 with the variable @code{reftex-default-label-alist-entries}.
4060 @defopt reftex-section-prefixes
4061 Prefixes for section labels. When the label prefix given in an entry in
4062 @code{reftex-label-alist} contains @samp{%S}, this list is used to
4063 determine the correct prefix string depending on the current section
4064 level. The list is an alist, with each entry of the form
4065 @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
4066 names like @samp{chapter}, integer section levels (as given in
4067 @code{reftex-section-levels}), and @code{t} for the default.
4070 @defopt reftex-default-context-regexps
4071 Alist with default regular expressions for finding context. The emacs
4072 lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
4073 to calculate the final regular expression - so @samp{%s} will be
4074 replaced with the environment or macro.
4077 @defopt reftex-trust-label-prefix
4078 Non-@code{nil} means, trust the label prefix when determining label type.
4079 It is customary to use special label prefixes to distinguish different label
4080 types. The label prefixes have no syntactic meaning in LaTeX (unless
4081 special packages like fancyref) are being used. RefTeX can and by
4082 default does parse around each label to detect the correct label type,
4083 but this process can be slow when a document contains thousands of
4084 labels. If you use label prefixes consistently, you may speed up
4085 document parsing by setting this variable to a non-nil value. RefTeX
4086 will then compare the label prefix with the prefixes found in
4087 `reftex-label-alist' and derive the correct label type in this way.
4088 Possible values for this option are:
4091 t @r{This means to trust any label prefixes found.}
4092 regexp @r{If a regexp, only prefixes matched by the regexp are trusted.}
4093 list @r{List of accepted prefixes, as strings. The colon is part of}
4094 @r{the prefix, e.g. ("fn:" "eqn:" "item:").}
4095 nil @r{Never trust a label prefix.}
4097 The only disadvantage of using this feature is that the label context
4098 displayed in the label selection buffer along with each label is
4099 simply some text after the label definition. This is no problem if you
4100 place labels keeping this in mind (e.g. @i{before} the equation, @i{at
4101 the beginning} of a fig/tab caption ...). Anyway, it is probably best
4102 to use the regexp or the list value types to fine-tune this feature.
4103 For example, if your document contains thousands of footnotes with
4104 labels fn:xxx, you may want to set this variable to the value "^fn:$" or
4105 ("fn:"). Then RefTeX will still do extensive parsing for any
4106 non-footnote labels.
4109 @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
4110 @section Creating Labels
4111 @cindex Options, creating labels
4112 @cindex Creating labels, options
4114 @defopt reftex-insert-label-flags
4115 Flags governing label insertion. The value has the form
4118 (@var{derive} @var{prompt})
4121 If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
4122 label from context. A section label for example will be derived from
4123 the section heading. The conversion of the context to a valid label is
4124 governed by the specifications given in
4125 @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
4126 the default label will consist of the prefix and a unique number, like
4129 If @var{prompt} is @code{t}, the user will be prompted for a label
4130 string. When @var{prompt} is @code{nil}, the default label will be
4131 inserted without query.
4133 So the combination of @var{derive} and @var{prompt} controls label
4134 insertion. Here is a table describing all four possibilities:
4138 @var{derive} @var{prompt} @var{action}
4139 -----------------------------------------------------------
4140 nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
4141 nil t @r{Prompt for label.}
4142 t nil @r{Derive a label from context and insert. No query.}
4143 t t @r{Derive a label from context, prompt for confirmation.}
4147 Each flag may be set to @code{t}, @code{nil}, or a string of label type
4148 letters indicating the label types for which it should be true. Thus,
4149 the combination may be set differently for each label type. The default
4150 settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
4151 headings (with confirmation). Prompt for figure and table labels. Use
4152 simple labels without confirmation for everything else.
4154 The available label types are: @code{s} (section), @code{f} (figure),
4155 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4156 (footnote), @code{N} (endnote) plus any definitions in
4157 @code{reftex-label-alist}.
4160 @deffn Hook reftex-format-label-function
4161 If non-@code{nil}, should be a function which produces the string to
4162 insert as a label definition. The function will be called with two
4163 arguments, the @var{label} and the @var{default-format} (usually
4164 @samp{\label@{%s@}}). It should return the string to insert into the
4168 @deffn Hook reftex-string-to-label-function
4169 Function to turn an arbitrary string into a valid label.
4170 @b{Ref@TeX{}}'s default function uses the variable
4171 @code{reftex-derive-label-parameters}.
4174 @deffn Hook reftex-translate-to-ascii-function
4175 Filter function which will process a context string before it is used to
4176 derive a label from it. The intended application is to convert ISO or
4177 Mule characters into something valid in labels. The default function
4178 @code{reftex-latin1-to-ascii} removes the accents from Latin-1
4179 characters. X-Symbol (>=2.6) sets this variable to the much more
4180 general @code{x-symbol-translate-to-ascii}.
4183 @defopt reftex-derive-label-parameters
4184 Parameters for converting a string into a label. This variable is a
4185 list of the following items:
4188 Number of words to use.
4190 Maximum number of characters in a label string.
4192 @code{nil}: Throw away any words containing characters invalid in labels.@*
4193 @code{t}: Throw away only the invalid characters, not the whole word.
4195 @code{nil}: Never abbreviate words.@*
4196 @code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
4197 @code{1}: Abbreviate words if necessary to shorten label string.
4198 @item @var{separator}
4199 String separating different words in the label.
4200 @item @var{ignorewords}
4201 List of words which should not be part of labels.
4202 @item @var{downcase}
4203 @code{t}: Downcase words before putting them into the label.@*
4207 @defopt reftex-label-illegal-re
4208 Regexp matching characters not valid in labels.
4211 @defopt reftex-abbrev-parameters
4212 Parameters for abbreviation of words. A list of four parameters.
4214 @item @var{min-chars}
4215 Minimum number of characters remaining after abbreviation.
4216 @item @var{min-kill}
4217 Minimum number of characters to remove when abbreviating words.
4219 Character class before abbrev point in word.
4221 Character class after abbrev point in word.
4225 @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
4226 @section Referencing Labels
4227 @cindex Options, referencing labels
4228 @cindex Referencing labels, options
4230 @defopt reftex-label-menu-flags
4231 List of flags governing the label menu makeup. The flags are:
4233 @item @var{table-of-contents}
4234 Show the labels embedded in a table of context.
4235 @item @var{section-numbers}
4236 Include section numbers (like 4.1.3) in table of contents.
4237 @item @var{counters}
4238 Show counters. This just numbers the labels in the menu.
4239 @item @var{no-context}
4240 Non-@code{nil} means do @emph{not} show the short context.
4242 Follow full context in other window.
4243 @item @var{show-commented}
4244 Show labels from regions which are commented out.
4245 @item @var{match-everywhere}
4247 @item @var{show-files}
4248 Show begin and end of included files.
4251 Each of these flags can be set to @code{t} or @code{nil}, or to a string
4252 of type letters indicating the label types for which it should be true.
4253 These strings work like character classes in regular expressions. Thus,
4254 setting one of the flags to @samp{"sf"} makes the flag true for section
4255 and figure labels, @code{nil} for everything else. Setting it to
4256 @samp{"^sf"} makes it the other way round.
4258 The available label types are: @code{s} (section), @code{f} (figure),
4259 @code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4260 (footnote), plus any definitions in @code{reftex-label-alist}.
4262 Most options can also be switched from the label menu itself - so if you
4263 decide here to not have a table of contents in the label menu, you can
4264 still get one interactively during selection from the label menu.
4267 @defopt reftex-multiref-punctuation
4268 Punctuation strings for multiple references. When marking is used in
4269 the selection buffer to select several references, this variable
4270 associates the 3 marking characters @samp{,-+} with prefix strings to be
4271 inserted into the buffer before the corresponding @code{\ref} macro.
4272 This is used to string together whole reference sets, like
4273 @samp{eqs. 1,2,3-5,6 and 7} in a single call to
4274 @code{reftex-reference}.
4277 @defopt reftex-vref-is-default
4278 Non-@code{nil} means, the varioref macro @code{\vref} is used as
4279 default. In the selection buffer, the @kbd{v} key toggles the reference
4280 macro between @code{\ref} and @code{\vref}. The value of this variable
4281 determines the default which is active when entering the selection
4282 process. Instead of @code{nil} or @code{t}, this may also be a string
4283 of type letters indicating the label types for which it should be
4287 @defopt reftex-fref-is-default
4288 Non-@code{nil} means, the fancyref macro @code{\fref} is used as
4289 default. In the selection buffer, the @kbd{V} key toggles the reference
4290 macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of
4291 this variable determines the default which is active when entering the
4292 selection process. Instead of @code{nil} or @code{t}, this may also be
4293 a string of type letters indicating the label types for which it should
4297 @deffn Hook reftex-format-ref-function
4298 If non-@code{nil}, should be a function which produces the string to
4299 insert as a reference. Note that the insertion format can also be
4300 changed with @code{reftex-label-alist}. This hook also is used by the
4301 special commands to insert @code{\vref} and @code{\fref} references, so
4302 even if you set this, your setting will be ignored by the special
4303 commands. The function will be called with two arguments, the
4304 @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
4305 It should return the string to insert into the buffer.
4308 @defopt reftex-level-indent
4309 Number of spaces to be used for indentation per section level.
4312 @defopt reftex-guess-label-type
4313 Non-@code{nil} means, @code{reftex-reference} will try to guess the
4314 label type. To do that, @b{Ref@TeX{}} will look at the word before the
4315 cursor and compare it with the magic words given in
4316 @code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will
4317 immediately offer the correct label menu - otherwise it will prompt you
4318 for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}
4319 will always prompt for a label type.
4322 @deffn {Normal Hook} reftex-display-copied-context-hook
4323 Normal Hook which is run before context is displayed anywhere. Designed
4324 for @w{@code{X-Symbol}}, but may have other uses as well.
4327 @deffn Hook reftex-pre-refontification-functions
4328 @code{X-Symbol} specific hook. Probably not useful for other purposes.
4329 The functions get two arguments, the buffer from where the command
4330 started and a symbol indicating in what context the hook is
4334 @deffn {Normal Hook} reftex-select-label-mode-hook
4335 Normal hook which is run when a selection buffer enters
4336 @code{reftex-select-label-mode}.
4339 @deffn Keymap reftex-select-label-map
4340 The keymap which is active in the labels selection process
4341 (@pxref{Referencing Labels}).
4344 @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
4345 @section Creating Citations
4346 @cindex Options, creating citations
4347 @cindex Creating citations, options
4349 @defopt reftex-bibliography-commands
4350 LaTeX commands which specify the BibTeX databases to use with the document.
4353 @defopt reftex-bibfile-ignore-regexps
4354 List of regular expressions to exclude files in
4355 @code{\\bibliography@{..@}}. File names matched by any of these regexps
4356 will not be parsed. Intended for files which contain only
4357 @code{@@string} macro definitions and the like, which are ignored by
4358 @b{Ref@TeX{}} anyway.
4361 @defopt reftex-default-bibliography
4362 List of BibTeX database files which should be used if none are specified.
4363 When @code{reftex-citation} is called from a document with neither
4364 a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4365 environment, @b{Ref@TeX{}} will scan these files instead. Intended for
4366 using @code{reftex-citation} in non-LaTeX files. The files will be
4367 searched along the BIBINPUTS or TEXBIB path.
4370 @defopt reftex-sort-bibtex-matches
4371 Sorting of the entries found in BibTeX databases by reftex-citation.
4374 nil @r{Do not sort entries.}
4375 author @r{Sort entries by author name.}
4376 year @r{Sort entries by increasing year.}
4377 reverse-year @r{Sort entries by decreasing year.}
4381 @defopt reftex-cite-format
4382 The format of citations to be inserted into the buffer. It can be a
4383 string, an alist or a symbol. In the simplest case this is just the string
4384 @samp{\cite@{%l@}}, which is also the default. See the definition of
4385 @code{reftex-cite-format-builtin} for more complex examples.
4387 If @code{reftex-cite-format} is a string, it will be used as the format.
4388 In the format, the following percent escapes will be expanded.
4392 The BibTeX label of the citation.
4394 List of author names, see also @code{reftex-cite-punctuation}.
4396 Like %a, but abbreviate more than 2 authors like Jones et al.
4398 First author name only.
4400 Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4401 @samp{%E} work a well).
4404 It is also possible to access all other BibTeX database fields:
4407 %b booktitle %c chapter %d edition %h howpublished
4408 %i institution %j journal %k key %m month
4409 %n number %o organization %p pages %P first page
4410 %r address %s school %u publisher %t title
4412 %B booktitle, abbreviated %T title, abbreviated
4416 Usually, only @samp{%l} is needed. The other stuff is mainly for the
4417 echo area display, and for @code{(setq reftex-comment-citations t)}.
4419 @samp{%<} as a special operator kills punctuation and space around it
4420 after the string has been formatted.
4422 A pair of square brackets indicates an optional argument, and RefTeX
4423 will prompt for the values of these arguments.
4425 Beware that all this only works with BibTeX database files. When
4426 citations are made from the @code{\bibitems} in an explicit
4427 @code{thebibliography} environment, only @samp{%l} is available.
4429 If @code{reftex-cite-format} is an alist of characters and strings, the
4430 user will be prompted for a character to select one of the possible
4433 In order to configure this variable, you can either set
4434 @code{reftex-cite-format} directly yourself or set it to the
4435 @emph{symbol} of one of the predefined styles. The predefined symbols
4436 are those which have an association in the constant
4437 @code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
4441 @deffn Hook reftex-format-cite-function
4442 If non-@code{nil}, should be a function which produces the string to
4443 insert as a citation. Note that the citation format can also be changed
4444 with the variable @code{reftex-cite-format}. The function will be
4445 called with two arguments, the @var{citation-key} and the
4446 @var{default-format} (taken from @code{reftex-cite-format}). It should
4447 return the string to insert into the buffer.
4450 @defopt reftex-cite-prompt-optional-args
4451 Non-@code{nil} means, prompt for empty optional arguments in cite macros.
4452 When an entry in @code{reftex-cite-format} ist given with square brackets to
4453 indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
4454 prompt for values. Possible values are:
4456 nil @r{Never prompt for optional arguments}
4458 maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example
4459 Unnecessary empty optional arguments are removed before insertion into
4460 the buffer. See @code{reftex-cite-cleanup-optional-args}.
4463 @defopt reftex-cite-cleanup-optional-args
4464 Non-@code{nil} means, remove empty optional arguments from cite macros
4468 @defopt reftex-comment-citations
4469 Non-@code{nil} means add a comment for each citation describing the full
4470 entry. The comment is formatted according to
4471 @code{reftex-cite-comment-format}.
4474 @defopt reftex-cite-comment-format
4475 Citation format used for commented citations. Must @emph{not} contain
4476 @samp{%l}. See the variable @code{reftex-cite-format} for possible
4480 @defopt reftex-cite-punctuation
4481 Punctuation for formatting of name lists in citations. This is a list
4485 normal names separator, like @samp{, } in Jones, Brown and Miller
4487 final names separator, like @samp{ and } in Jones, Brown and Miller
4489 The @samp{et al.} string, like @samp{ @{\it et al.@}} in
4490 Jones @{\it et al.@}
4494 @deffn {Normal Hook} reftex-select-bib-mode-hook
4495 Normal hook which is run when a selection buffer enters
4496 @code{reftex-select-bib-mode}.
4499 @deffn Keymap reftex-select-bib-map
4500 The keymap which is active in the citation-key selection process
4501 (@pxref{Creating Citations}).
4504 @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options
4505 @section Index Support
4506 @cindex Options, Index support
4507 @cindex Index support, options
4509 @defopt reftex-support-index
4510 Non-@code{nil} means, index entries are parsed as well. Index support
4511 is resource intensive and the internal structure holding the parsed
4512 information can become quite big. Therefore it can be turned off. When
4513 this is @code{nil} and you execute a command which requires index
4514 support, you will be asked for confirmation to turn it on and rescan the
4518 @defopt reftex-index-special-chars
4519 List of special characters in index entries, given as strings. These
4520 correspond to the @code{MakeIndex} keywords
4521 @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4524 @defopt reftex-index-macros
4525 List of macros which define index entries. The structure of each entry
4528 (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4531 @var{macro} is the macro. Arguments should be denoted by empty braces,
4532 as for example in @samp{\index[]@{*@}}. Use square brackets to denote
4533 optional arguments. The star marks where the index key is.
4535 @var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
4536 are reserved for the default index and the glossary. Other indices can
4537 be defined as well. If this is an integer, the Nth argument of the
4538 macro holds the index tag.
4540 @var{key} is a character which is used to identify the macro for input
4541 with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
4542 reserved for default index and glossary.
4544 @var{prefix} can be a prefix which is added to the @var{key} part of the
4545 index entry. If you have a macro
4546 @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4547 should be @samp{Molecules!}.
4549 @var{exclude} can be a function. If this function exists and returns a
4550 non-@code{nil} value, the index entry at point is ignored. This was
4551 implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4552 in the LaTeX2e @code{index} package.
4554 @var{repeat}, if non-@code{nil}, means the index macro does not typeset
4555 the entry in the text, so that the text has to be repeated outside the
4556 index macro. Needed for @code{reftex-index-selection-or-word} and for
4557 indexing from the phrase buffer.
4559 The final entry may also be a symbol. It must have an association in
4560 the variable @code{reftex-index-macros-builtin} to specify the main
4561 indexing package you are using. Valid values are currently
4563 default @r{The LaTeX default - unnecessary to specify this one}
4564 multind @r{The multind.sty package}
4565 index @r{The index.sty package}
4566 index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
4567 @r{Should not be used - only for old documents}
4569 Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
4570 so with a sufficiently new version of AUCTeX, you should not set the
4574 @defopt reftex-index-default-macro
4575 The default index macro for @code{reftex-index-selection-or-word}.
4576 This is a list with @code{(@var{macro-key} @var{default-tag})}.
4578 @var{macro-key} is a character identifying an index macro - see
4579 @code{reftex-index-macros}.
4581 @var{default-tag} is the tag to be used if the macro requires a
4582 @var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
4583 @b{Ref@TeX{}} will ask for it. When this is the empty string and the
4584 TAG argument of the index macro is optional, the TAG argument will be
4588 @defopt reftex-index-default-tag
4589 Default index tag. When working with multiple indexes, RefTeX queries
4590 for an index tag when creating index entries or displaying a specific
4591 index. This variable controls the default offered for these queries.
4592 The default can be selected with @key{RET} during selection or
4593 completion. Valid values of this variable are:
4595 nil @r{Do not provide a default index}
4596 "tag" @r{The default index tag given as a string, e.g. "idx"}
4597 last @r{The last used index tag will be offered as default}
4601 @defopt reftex-index-math-format
4602 Format of index entries when copied from inside math mode. When
4603 @code{reftex-index-selection-or-word} is executed inside TeX math mode,
4604 the index key copied from the buffer is processed with this format
4605 string through the @code{format} function. This can be used to add the
4606 math delimiters (e.g. @samp{$}) to the string. Requires the
4607 @file{texmathp.el} library which is part of AUCTeX.
4610 @defopt reftex-index-phrase-file-extension
4611 File extension for the index phrase file. This extension will be added
4612 to the base name of the master file.
4615 @defopt reftex-index-phrases-logical-and-regexp
4616 Regexp matching the @samp{and} operator for index arguments in phrases
4617 file. When several index arguments in a phrase line are separated by
4618 this operator, each part will generate an index macro. So each match of
4619 the search phrase will produce @emph{several} different index entries.
4620 Make sure this does no match things which are not separators. This
4621 logical @samp{and} has higher priority than the logical @samp{or}
4622 specified in @code{reftex-index-phrases-logical-or-regexp}.
4625 @defopt reftex-index-phrases-logical-or-regexp
4626 Regexp matching the @samp{or} operator for index arguments in phrases
4627 file. When several index arguments in a phrase line are separated by
4628 this operator, the user will be asked to select one of them at each
4629 match of the search phrase. The first index arg will be the default. A
4630 number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make
4631 sure this does no match things which are not separators. The logical
4632 @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4633 has higher priority than this logical @samp{or}.
4636 @defopt reftex-index-phrases-search-whole-words
4637 Non-@code{nil} means phrases search will look for whole words, not subwords.
4638 This works by requiring word boundaries at the beginning and end of
4639 the search string. When the search phrase already has a non-word-char
4640 at one of these points, no word boundary is required there.
4643 @defopt reftex-index-phrases-case-fold-search
4644 Non-@code{nil} means, searching for index phrases will ignore
4648 @defopt reftex-index-verify-function
4649 A function which is called at each match during global indexing.
4650 If the function returns nil, the current match is skipped.
4653 @defopt reftex-index-phrases-skip-indexed-matches
4654 Non-@code{nil} means, skip matches which appear to be indexed already.
4655 When doing global indexing from the phrases buffer, searches for some
4656 phrases may match at places where that phrase was already indexed. In
4657 particular when indexing an already processed document again, this
4658 will even be the norm. When this variable is non-@code{nil},
4659 @b{Ref@TeX{}} checks if the match is an index macro argument, or if an
4660 index macro is directly before or after the phrase. If that is the
4661 case, that match will be ignored.
4664 @defopt reftex-index-phrases-wrap-long-lines
4665 Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
4666 Inserting indexing commands in a line makes the line longer - often
4667 so long that it does not fit onto the screen. When this variable is
4668 non-@code{nil}, newlines will be added as necessary before and/or after the
4669 indexing command to keep lines short. However, the matched text
4670 phrase and its index command will always end up on a single line.
4673 @defopt reftex-index-phrases-sort-prefers-entry
4674 Non-@code{nil} means when sorting phrase lines, the explicit index entry
4675 is used. Phrase lines in the phrases buffer contain a search phrase, and
4676 sorting is normally based on these. Some phrase lines also have
4677 an explicit index argument specified. When this variable is
4678 non-@code{nil}, the index argument will be used for sorting.
4681 @defopt reftex-index-phrases-sort-in-blocks
4682 Non-@code{nil} means, empty and comment lines separate phrase buffer
4683 into blocks. Sorting will then preserve blocks, so that lines are
4684 re-arranged only within blocks.
4687 @defopt reftex-index-phrases-map
4688 Keymap for the Index Phrases buffer.
4691 @defopt reftex-index-phrases-mode-hook
4692 Normal hook which is run when a buffer is put into
4693 @code{reftex-index-phrases-mode}.
4696 @defopt reftex-index-section-letters
4697 The letters which denote sections in the index. Usually these are all
4698 capital letters. Don't use any downcase letters. Order is not
4699 significant, the index will be sorted by whatever the sort function
4700 thinks is correct. In addition to these letters, @b{Ref@TeX{}} will
4701 create a group @samp{!} which contains all entries sorted below the
4702 lowest specified letter. In the @file{*Index*} buffer, pressing any of
4703 these capital letters or @kbd{!} will jump to that section.
4706 @defopt reftex-index-include-context
4707 Non-@code{nil} means, display the index definition context in the
4708 @file{*Index*} buffer. This flag may also be toggled from the
4709 @file{*Index*} buffer with the @kbd{c} key.
4712 @defopt reftex-index-follow-mode
4713 Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4714 window to follow. The other window will show the corresponding part of
4715 the document. This flag can be toggled from within the @file{*Index*}
4716 buffer with the @kbd{f} key.
4719 @deffn Keymap reftex-index-map
4720 The keymap which is active in the @file{*Index*} buffer
4721 (@pxref{Index Support}).
4724 @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options
4725 @section Viewing Cross-References
4726 @cindex Options, viewing cross-references
4727 @cindex Viewing cross-references, options
4729 @defopt reftex-view-crossref-extra
4730 Macros which can be used for the display of cross references.
4731 This is used when `reftex-view-crossref' is called with point in an
4732 argument of a macro. Note that crossref viewing for citations,
4733 references (both ways) and index entries is hard-coded. This variable
4734 is only to configure additional structures for which crossreference
4735 viewing can be useful. Each entry has the structure
4737 (@var{macro-re} @var{search-re} @var{highlight}).
4739 @var{macro-re} is matched against the macro. @var{search-re} is the
4740 regexp used to search for cross references. @samp{%s} in this regexp is
4741 replaced with the macro argument at point. @var{highlight} is an
4742 integer indicating which subgroup of the match should be highlighted.
4745 @defopt reftex-auto-view-crossref
4746 Non-@code{nil} means, initially turn automatic viewing of crossref info
4747 on. Automatic viewing of crossref info normally uses the echo area.
4748 Whenever point is idle for more than @code{reftex-idle-time} seconds on
4749 the argument of a @code{\ref} or @code{\cite} macro, and no other
4750 message is being displayed, the echo area will display information about
4751 that cross reference. You can also set the variable to the symbol
4752 @code{window}. In this case a small temporary window is used for the
4753 display. This feature can be turned on and off from the menu
4757 @defopt reftex-idle-time
4758 Time (secs) Emacs has to be idle before automatic crossref display
4759 or toc recentering is done.
4762 @defopt reftex-cite-view-format
4763 Citation format used to display citation info in the message area. See
4764 the variable @code{reftex-cite-format} for possible percent
4768 @defopt reftex-revisit-to-echo
4769 Non-@code{nil} means, automatic citation display will revisit files if
4770 necessary. When nil, citation display in echo area will only be active
4771 for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4772 BibTeX database files which are already visited by a live associated
4776 @defopt reftex-cache-cite-echo
4777 Non-@code{nil} means, the information displayed in the echo area for
4778 cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4779 saved along with the parsing information. The cache survives document
4780 scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
4783 @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options
4784 @section Finding Files
4785 @cindex Options, Finding Files
4786 @cindex Finding files, options
4788 @defopt reftex-texpath-environment-variables
4789 List of specifications how to retrieve the search path for TeX files.
4790 Several entries are possible.
4793 If an element is the name of an environment variable, its content is
4796 If an element starts with an exclamation mark, it is used as a command
4797 to retrieve the path. A typical command with the kpathsearch library
4798 would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4800 Otherwise the element itself is interpreted as a path.
4802 Multiple directories can be separated by the system dependent
4803 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4804 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4807 @defopt reftex-bibpath-environment-variables
4808 List of specifications how to retrieve the search path for BibTeX
4809 files. Several entries are possible.
4812 If an element is the name of an environment variable, its content is
4815 If an element starts with an exclamation mark, it is used as a command
4816 to retrieve the path. A typical command with the kpathsearch library
4817 would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4819 Otherwise the element itself is interpreted as a path.
4821 Multiple directories can be separated by the system dependent
4822 @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4823 be expanded recursively. See also @code{reftex-use-external-file-finders}.
4826 @defopt reftex-file-extensions
4827 Association list with file extensions for different file types.
4828 This is a list of items, each item is like:
4829 @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
4831 @var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
4832 @var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
4833 @var{other-ext}: @r{Any number of other valid extensions for this file type.}
4835 When a files is searched and it does not have any of the valid extensions,
4836 we try the default extension first, and then the naked file name.
4839 @defopt reftex-search-unrecursed-path-first
4840 Non-@code{nil} means, search all specified directories before trying
4841 recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
4842 then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
4843 option is @code{nil}, the subdirectories of @samp{./} are searched
4844 before @samp{/tex/}. This is mainly for speed - most of the time the
4845 recursive path is for the system files and not for the user files. Set
4846 this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
4847 equal names in wrong sequence.
4850 @defopt reftex-use-external-file-finders
4851 Non-@code{nil} means, use external programs to find files. Normally,
4852 @b{Ref@TeX{}} searches the paths given in the environment variables
4853 @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
4854 database files. With this option turned on, it calls an external
4855 program specified in the option @code{reftex-external-file-finders}
4856 instead. As a side effect, the variables
4857 @code{reftex-texpath-environment-variables} and
4858 @code{reftex-bibpath-environment-variables} will be ignored.
4861 @defopt reftex-external-file-finders
4862 Association list with external programs to call for finding files. Each
4863 entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
4864 @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
4865 string containing the external program to use with any arguments.
4866 @code{%f} will be replaced by the name of the file to be found. Note
4867 that these commands will be executed directly, not via a shell. Only
4868 relevant when @code{reftex-use-external-file-finders} is
4873 @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
4874 @section Optimizations
4875 @cindex Options, optimizations
4876 @cindex Optimizations, options
4878 @defopt reftex-keep-temporary-buffers
4879 Non-@code{nil} means, keep buffers created for parsing and lookup.
4880 @b{Ref@TeX{}} sometimes needs to visit files related to the current
4881 document. We distinguish files visited for
4884 Parts of a multifile document loaded when (re)-parsing the
4887 BibTeX database files and TeX files loaded to find a reference, to
4888 display label context, etc.
4890 The created buffers can be kept for later use, or be thrown away
4891 immediately after use, depending on the value of this variable:
4895 Throw away as much as possible.
4899 Throw away buffers created for parsing, but keep the ones created for
4903 If a buffer is to be kept, the file is visited normally (which is
4904 potentially slow but will happen only once). If a buffer is to be thrown
4905 away, the initialization of the buffer depends upon the variable
4906 @code{reftex-initialize-temporary-buffers}.
4909 @defopt reftex-initialize-temporary-buffers
4910 Non-@code{nil} means do initializations even when visiting file
4911 temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
4912 other stuff to briefly visit a file. When @code{t}, the full default
4913 initializations are done (@code{find-file-hook} etc.). Instead of
4914 @code{t} or @code{nil}, this variable may also be a list of hook
4915 functions to do a minimal initialization.
4918 @defopt reftex-no-include-regexps
4919 List of regular expressions to exclude certain input files from parsing.
4920 If the name of a file included via @code{\include} or @code{\input} is
4921 matched by any of the regular expressions in this list, that file is not
4922 parsed by @b{Ref@TeX{}}.
4925 @defopt reftex-enable-partial-scans
4926 Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4927 Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
4928 commands, or with the @kbd{r} key in menus. When this option is
4929 @code{t} in a multifile document, we will only parse the current buffer,
4930 or the file associated with the label or section heading near point in a
4931 menu. Requesting re-parsing of an entire multifile document then
4932 requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
4936 @defopt reftex-save-parse-info
4937 Non-@code{nil} means, save information gathered with parsing in files.
4938 The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
4939 used to save the information. When this variable is @code{t},
4942 accessing the parsing information for the first time in an editing
4943 session will read that file (if available) instead of parsing the
4946 exiting Emacs or killing a buffer in reftex-mode will cause a new
4947 version of the file to be written.
4951 @defopt reftex-parse-file-extension
4952 File extension for the file in which parser information is stored.
4953 This extension is added to the base name of the master file.
4956 @defopt reftex-allow-automatic-rescan
4957 Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
4958 necessary. Applies (currently) only in rare cases, when a new label
4959 cannot be placed with certainty into the internal label list.
4962 @defopt reftex-use-multiple-selection-buffers
4963 Non-@code{nil} means use a separate selection buffer for each label
4964 type. These buffers are kept from one selection to the next and need
4965 not to be created for each use - so the menu generally comes up faster.
4966 The selection buffers will be erased (and therefore updated)
4967 automatically when new labels in its category are added. See the
4968 variable @code{reftex-auto-update-selection-buffers}.
4971 @defopt reftex-auto-update-selection-buffers
4972 Non-@code{nil} means, selection buffers will be updated automatically.
4973 When a new label is defined with @code{reftex-label}, all selection
4974 buffers associated with that label category are emptied, in order to
4975 force an update upon next use. When @code{nil}, the buffers are left
4976 alone and have to be updated by hand, with the @kbd{g} key from the
4977 label selection process. The value of this variable will only have any
4978 effect when @code{reftex-use-multiple-selection-buffers} is
4982 @node Options (Fontification), Options (Misc), Options (Optimizations), Options
4983 @section Fontification
4984 @cindex Options, fontification
4985 @cindex Fontification, options
4987 @defopt reftex-use-fonts
4988 Non-@code{nil} means, use fonts in label menu and on-the-fly help.
4989 Font-lock must be loaded as well to actually get fontified
4990 display. After changing this option, a rescan may be necessary to
4994 @defopt reftex-refontify-context
4995 Non-@code{nil} means, re-fontify the context in the label menu with
4996 font-lock. This slightly slows down the creation of the label menu. It
4997 is only necessary when you definitely want the context fontified.
4999 This option may have 3 different values:
5006 Refontify when necessary, e.g. with old versions of the x-symbol
5009 The option is ignored when @code{reftex-use-fonts} is @code{nil}.
5012 @defopt reftex-highlight-selection
5013 Non-@code{nil} means, highlight selected text in selection and
5014 @file{*toc*} buffers. Normally, the text near the cursor is the
5015 @emph{selected} text, and it is highlighted. This is the entry most
5016 keys in the selection and @file{*toc*} buffers act on. However, if you
5017 mainly use the mouse to select an item, you may find it nice to have
5018 mouse-triggered highlighting @emph{instead} or @emph{as well}. The
5019 variable may have one of these values:
5022 nil @r{No highlighting.}
5023 cursor @r{Highlighting is cursor driven.}
5024 mouse @r{Highlighting is mouse driven.}
5025 both @r{Both cursor and mouse trigger highlighting.}
5028 Changing this variable requires to rebuild the selection and *toc*
5029 buffers to become effective (keys @kbd{g} or @kbd{r}).
5032 @defopt reftex-cursor-selected-face
5033 Face name to highlight cursor selected item in toc and selection buffers.
5034 See also the variable @code{reftex-highlight-selection}.
5036 @defopt reftex-mouse-selected-face
5037 Face name to highlight mouse selected item in toc and selection buffers.
5038 See also the variable @code{reftex-highlight-selection}.
5040 @defopt reftex-file-boundary-face
5041 Face name for file boundaries in selection buffer.
5043 @defopt reftex-label-face
5044 Face name for labels in selection buffer.
5046 @defopt reftex-section-heading-face
5047 Face name for section headings in toc and selection buffers.
5049 @defopt reftex-toc-header-face
5050 Face name for the header of a toc buffer.
5052 @defopt reftex-bib-author-face
5053 Face name for author names in bib selection buffer.
5055 @defopt reftex-bib-year-face
5056 Face name for year in bib selection buffer.
5058 @defopt reftex-bib-title-face
5059 Face name for article title in bib selection buffer.
5061 @defopt reftex-bib-extra-face
5062 Face name for bibliographic information in bib selection buffer.
5064 @defopt reftex-select-mark-face
5065 Face name for marked entries in the selection buffers.
5067 @defopt reftex-index-header-face
5068 Face name for the header of an index buffer.
5070 @defopt reftex-index-section-face
5071 Face name for the start of a new letter section in the index.
5073 @defopt reftex-index-tag-face
5074 Face name for index names (for multiple indices).
5076 @defopt reftex-index-face
5077 Face name for index entries.
5080 @node Options (Misc), , Options (Fontification), Options
5081 @section Miscellaneous
5082 @cindex Options, misc
5084 @defopt reftex-extra-bindings
5085 Non-@code{nil} means, make additional key bindings on startup. These
5086 extra bindings are located in the users @samp{C-c letter}
5087 map. @xref{Key Bindings}.
5090 @defopt reftex-plug-into-AUCTeX
5091 Plug-in flags for AUCTeX interface. This variable is a list of
5092 5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}
5096 - supply labels in new sections and environments (flag 1)
5097 - supply arguments for macros like @code{\label} (flag 2)
5098 - supply arguments for macros like @code{\ref} (flag 3)
5099 - supply arguments for macros like @code{\cite} (flag 4)
5100 - supply arguments for macros like @code{\index} (flag 5)
5103 You may also set the variable itself to t or nil in order to turn all
5104 options on or off, respectively.@*
5105 Supplying labels in new sections and environments applies when creating
5106 sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
5107 Supplying macro arguments applies when you insert such a macro
5108 interactively with @kbd{C-c @key{RET}}.@*
5109 See the AUCTeX documentation for more information.
5112 @defopt reftex-revisit-to-follow
5113 Non-@code{nil} means, follow-mode will revisit files if necessary.
5114 When nil, follow-mode will be suspended for stuff in unvisited files.
5117 @defopt reftex-allow-detached-macro-args
5118 Non-@code{nil} means, allow arguments of macros to be detached by
5119 whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
5120 [xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
5121 this will be the case even if @code{\bb} is defined with zero or one
5125 @node Keymaps and Hooks, Changes, Options, Top
5126 @section Keymaps and Hooks
5129 @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
5131 @deffn Keymap reftex-mode-map
5132 The keymap for @b{Ref@TeX{}} mode.
5135 @deffn {Normal Hook} reftex-load-hook
5136 Normal hook which is being run when loading @file{reftex.el}.
5139 @deffn {Normal Hook} reftex-mode-hook
5140 Normal hook which is being run when turning on @b{Ref@TeX{}} mode.
5143 Furthermore, the 4 modes used for referencing labels, creating
5144 citations, the table of contents buffer and the phrases buffer have
5145 their own keymaps and mode hooks. See the respective sections. There
5146 are many more hooks which are described in the relevant sections about
5147 options for a specific part of @b{Ref@TeX{}}.
5149 @node Changes, , Keymaps and Hooks, Top
5153 Here is a list of recent changes to @b{Ref@TeX{}}.
5155 @noindent @b{Version 4.26}
5161 @noindent @b{Version 4.25}
5164 Fixed bug with @samp{%F} in a label prefix. Added new escapes
5165 @samp{%m} and @samp{%M} for mater file name and master directory.
5168 @noindent @b{Version 4.24}
5171 Inserting citation commands now prompts for optional arguments
5172 when called with a prefix argument. Related new options are
5173 @code{reftex-cite-prompt-optional-args} and
5174 @code{reftex-cite-cleanup-optional-args}.
5176 New option @code{reftex-trust-label-prefix}. Configure this variable
5177 if you'd like RefTeX to base its classification of labels on prefixes.
5178 This can speed-up document parsing, but may in some cases reduce the
5179 quality of the context used by RefTeX to describe a label.
5181 Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
5184 Fixed bugs in indexing: Case-sensitive search, quotes before and/or
5185 after words. Disabbled indexing in comment lines.
5188 @noindent @b{Version 4.22}
5191 New command @code{reftex-create-bibtex-file} to create a new database
5192 with all entries referenced in the current document.
5194 New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
5195 from entries marked in a citation selection buffer.
5198 @noindent @b{Version 4.21}
5201 Renaming labels from the toc buffer with key @kbd{M-%}.
5204 @noindent @b{Version 4.20}
5207 Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in
5208 the TOC buffer promote/demote the section at point or all sections in
5211 New option @code{reftex-toc-split-windows-fraction} to set the size of
5212 the window used by the TOC. This makes the old variable
5213 @code{reftex-toc-split-windows-horizontally-fraction} obsolete.
5215 A dedicated frame can show the TOC with the current section
5216 always automatically highlighted. The frame is created and
5217 deleted from the toc buffer with the @kbd{d} key.
5220 @noindent @b{Version 4.19}
5223 New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
5224 section in the TOC buffer without selecting the TOC window.
5226 Recentering happens automatically in idle time when the option
5227 @code{reftex-auto-recenter-toc} is turned on.
5229 Fixed several bugs related to automatic cursor positioning in the TOC
5232 The highlight in the TOC buffer stays when the focus moves to a
5235 New command `reftex-goto-label'.
5237 Part numbers are no longer included in chapter numbers, and a new
5238 part does not reset the chapter counter. See new option
5239 @code{reftex-part-resets-chapter}.
5242 @noindent @b{Version 4.18}
5245 @code{reftex-citation} uses the word before the cursor as a default
5248 Simplified several regular expressions for speed.
5250 Better support for chapterbib.
5253 @noindent @b{Version 4.17}
5256 The toc window can be split off horizontally. See new options
5257 @code{reftex-toc-split-windows-horizontally},
5258 @code{reftex-toc-split-windows-horizontally-fraction}.
5260 It is possible to specify a function which verifies an index match
5261 during global indexing. See new option @code{reftex-index-verify-function}.
5263 The macros which input a file in LaTeX (like \input, \include) can
5264 be configured. See new option @code{reftex-include-file-commands}.
5266 The macros which specify the bibliography file (like \bibliography) can
5267 be configured. See new option @code{reftex-bibliography-commands}.
5269 The regular expression used to search for the \bibliography macro has
5270 been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
5276 @noindent @b{Version 4.15}
5279 Fixed bug with parsing of BibTeX files, when fields contain quotes or
5280 unmatched parenthesis.
5284 Improved interaction with Emacs LaTeX mode.
5287 @noindent @b{Version 4.12}
5290 Support for @file{bibentry} citation style.
5293 @noindent @b{Version 4.11}
5296 Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5299 @noindent @b{Version 4.10}
5302 Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5303 with @file{reftex-vars.el} on DOS machines.
5305 New options @code{reftex-parse-file-extension} and
5306 @code{reftex-index-phrase-file-extension}.
5311 @noindent @b{Version 4.09}
5314 New option @code{reftex-toc-max-level} to limit the depth of the toc.
5315 New key binding @kbd{t} in the @file{*toc*} buffer to change this
5318 RefTeX maintains an @file{Index Phrases} file in which phrases can be
5319 collected. When the document is ready, RefTeX can search all
5320 these phrases and assist indexing all matches.
5322 The variables @code{reftex-index-macros} and
5323 @code{reftex-index-default-macro} have changed their syntax slightly.
5324 The @var{repeat} parameter has move from the latter to the former.
5325 Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5328 The variable @code{reftex-section-levels} no longer contains the
5329 default stuff which has been moved to a constant.
5331 Environments like theorems can be placed into the TOC by putting
5332 entries for @samp{"begin@{theorem@}"} in
5333 @code{reftex-setion-levels}.
5336 @noindent @b{Version 4.06}
5339 @code{reftex-section-levels} can contain a function to compute the level
5340 of a sectioning command.
5342 Multiple @code{thebibliography} environments recognized.
5345 @noindent @b{Version 4.04}
5348 New option @code{reftex-index-default-tag} implements a default for queries.
5351 @noindent @b{Version 4.02}
5354 macros ending in @samp{refrange} are considered to contain references.
5356 Index entries made with @code{reftex-index-selection-or-word} in TeX
5357 math mode automatically get enclosing @samp{$} to preserve math mode. See
5358 new option @code{reftex-index-math-format}. Requires AUCTeX.
5361 @noindent @b{Version 4.01}
5364 New command @code{reftex-index-globally} to index a word in many
5365 places in the document. Also available from the index buffer with
5368 The first item in a @code{reftex-label-alist} entry may now also be a parser
5369 function to do non-standard parsing.
5371 @code{reftex-auto-view-crossref} no longer interferes with
5372 @code{pop-up-frames} (patch from Stefan Monnier).
5375 @noindent @b{Version 4.00}
5378 RefTeX has been split into several smaller files which are autoloaded on
5381 Index support, along with many new options.
5383 The selection of keys for @code{\ref} and @code{\cite} now allows to
5384 select multiple items by marking entries with the @kbd{m} key.
5389 @noindent @b{Version 3.43}
5392 Viewing cross-references generalized. Now works on @code{\label},
5393 @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5394 these, and from BibTeX buffers.
5396 New option @code{reftex-view-crossref-extra}.
5398 Support for the additional sectioning commands @code{\addchap} and
5399 @code{\addsec} which are defined in the LaTeX KOMA-Script classes.
5401 Files in @code{reftex-default-bibliography} will be searched along
5402 @code{BIBINPUTS} path.
5404 Reading a parse file now checks consistency.
5407 @noindent @b{Version 3.42}
5410 File search further refined. New option @code{reftex-file-extensions}.
5412 @file{*toc*} buffer can show the file boundaries of a multifile
5413 document, all labels and associated context. New keys @kbd{i}, @kbd{l},
5414 and @kbd{c}. New options @code{reftex-toc-include-labels},
5415 @code{reftex-toc-include-context},
5416 @code{reftex-toc-include-file-boundaries}.
5419 @noindent @b{Version 3.41}
5422 New options @code{reftex-texpath-environment-variables},
5423 @code{reftex-use-external-file-finders},
5424 @code{reftex-external-file-finders},
5425 @code{reftex-search-unrecursed-path-first}.
5427 @emph{kpathsearch} support. See new options and
5428 @code{reftex-bibpath-environment-variables}.
5431 @noindent @b{Version 3.38}
5434 @code{reftex-view-crossref} no longer moves to find a macro. Point has
5435 to be on the macro argument.
5438 @noindent @b{Version 3.36}
5441 New value @code{window} for option @code{reftex-auto-view-crossref}.
5444 @noindent @b{Version 3.35}
5447 ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5448 This takes back the related changes in 3.34 for safety reasons.
5451 @noindent @b{Version 3.34}
5454 Additional flag in @code{reftex-derive-label-parameters} do make only
5455 lowercase labels (default @code{t}).
5457 All @file{.rel} files have a final newline to avoid queries.
5459 Single byte representations of accented European letters (ISO-8859-1)
5460 are now valid in labels.
5463 @noindent @b{Version 3.33}
5466 Multiple selection buffers are now hidden buffers (they start with a
5469 Fixed bug with file search when TEXINPUTS environment variable is empty.
5472 @noindent @b{Version 3.30}
5475 In @code{reftex-citation}, the regular expression used to scan BibTeX
5476 files can be specified using completion on known citation keys.
5478 New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5481 New command @code{reftex-renumber-simple-labels} to renumber simple
5482 labels like @samp{eq:13} sequentially through a document.
5485 @noindent @b{Version 3.28}
5488 Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5489 timer, since itimer restart is not reliable.
5491 Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5493 Expansion of recursive tex and bib path rewritten.
5495 Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
5497 Fixed bug with section numbering after *-red sections.
5500 @noindent @b{Version 3.27}
5503 Macros can define @emph{neutral} labels, just like @code{\label}
5506 New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5509 @noindent @b{Version 3.26}
5512 [X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
5514 New hooks @code{reftex-translate-to-ascii-function},
5515 @code{reftex-string-to-label-function}.
5517 Made sure automatic crossref display will not visit/scan files.
5520 @noindent @b{Version 3.25}
5523 Echoing of citation info caches the info for displayed entries.
5524 New option @code{reftex-cache-cite-echo}.
5526 @kbd{M-x reftex-reset-mode} now also removes the file with parsing
5529 Default of @code{reftex-revisit-to-follow} changed to nil.
5532 @noindent @b{Version 3.24}
5535 New option @code{reftex-revisit-to-echo}.
5537 Interface with X-Symbol (>=2.6) is now complete and stable.
5539 Adapted to new outline, which uses overlays.
5541 File names in @code{\bibliography} may now have the @code{.bib}
5544 Fixed Bug with parsing "single file" from master file buffer.
5547 @noindent @b{Version 3.23}
5550 Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5552 @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
5555 The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5556 automatic display of crossref information in the echo area. See
5557 variable @code{reftex-auto-view-crossref}.
5559 AUCTeX interface updates:
5562 AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
5564 @b{Ref@TeX{}} notifies AUCTeX about new labels.
5566 @code{TeX-arg-ref} no longer used (introduction was unnecessary).
5568 @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5570 Settings added to @b{Ref@TeX{}} via style files remain local.
5573 Fixed bug with @code{reftex-citation} in non-latex buffers.
5575 Fixed bug with syntax table and context refontification.
5577 Safety-net for name change of @code{font-lock-reference-face}.
5580 @noindent @b{Version 3.22}
5583 Fixed bug with empty context strings.
5585 @code{reftex-mouse-view-crossref} is now bound by default at
5589 @noindent @b{Version 3.21}
5592 New options for all faces used by @b{Ref@TeX{}}. They're in the
5593 customization group @code{reftex-fontification-configurations}.
5596 @noindent @b{Version 3.19}
5599 Fixed bug with AUCTeX @code{TeX-master}.
5602 @noindent @b{Version 3.18}
5605 The selection now uses a recursive edit, much like minibuffer input.
5606 This removes all restrictions during selection. E.g. you can now
5607 switch buffers at will, use the mouse etc.
5609 New option @code{reftex-highlight-selection}.
5611 @kbd{mouse-2} can be used to select in selection and @file{*toc*}
5614 Fixed some problems regarding the interaction with VIPER mode.
5616 Follow-mode is now only used after point motion.
5618 @b{Ref@TeX{}} now finally does not fontify temporary files anymore.
5621 @noindent @b{Version 3.17}
5624 Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
5627 New command @code{reftex-save-all-document-buffers}.
5629 Magic word matching made more intelligent.
5631 Selection process can switch to completion (with @key{TAB}).
5633 @code{\appendix} is now recognized and influences section numbering.
5635 File commentary shortened considerably (use Info documentation).
5637 New option @code{reftex-no-include-regexps} to skip some include files.
5639 New option @code{reftex-revisit-to-follow}.
5642 @noindent @b{Version 3.16}
5645 New hooks @code{reftex-format-label-function},
5646 @code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
5648 TeXInfo documentation completed.
5650 Some restrictions in Label inserting and referencing removed.
5652 New variable @code{reftex-default-bibliography}.
5655 @noindent @b{Version 3.14}
5658 Selection buffers can be kept between selections: this is faster.
5659 See new variable @code{reftex-use-multiple-selection-buffers}.
5661 Prefix interpretation of reftex-view-crossref changed.
5663 Support for the @code{varioref} package (@kbd{v} key in selection
5667 @noindent @b{Version 3.12}
5670 There are 3 new keymaps for customization: @code{reftex-toc-map},
5671 @code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5673 Refontification uses more standard font-lock stuff.
5675 When no BibTeX database files are specified, citations can also use
5676 @code{\bibitem} entries from a @code{thebibliography} environment.
5679 @noindent @b{Version 3.11}
5682 Fixed bug which led to naked label in (e.g.) footnotes.
5684 Added scroll-other-window functions to RefTeX-Select.
5687 @noindent @b{Version 3.10}
5690 Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5692 Removed unimportant code which caused OS/2 Emacs to crash.
5694 All customization variables now accessible from menu.
5697 @noindent @b{Version 3.07}
5700 @code{Ref} menu improved.
5703 @noindent @b{Version 3.05}
5706 Compatibility code now first checks for XEmacs feature.
5709 @noindent @b{Version 3.04}
5712 Fixed BUG in the @emph{xr} support.
5715 @noindent @b{Version 3.03}
5718 Support for the LaTeX package @code{xr}, for inter-document
5721 A few (minor) Mule-related changes.
5723 Fixed bug which could cause @emph{huge} @file{.rel} files.
5725 Search for input and @file{.bib} files with recursive path definitions.
5728 @noindent @b{Version 3.00}
5731 @b{Ref@TeX{}} should work better for very large projects:
5733 The new parser works without creating a master buffer.
5735 Rescanning can be limited to a part of a multifile document.
5737 Information from the parser can be stored in a file.
5739 @b{Ref@TeX{}} can deal with macros having a naked label as an argument.
5741 Macros may have white space and newlines between arguments.
5743 Multiple identical section headings no longer confuse
5746 @b{Ref@TeX{}} should work correctly in combination with buffer-altering
5747 packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
5749 All labeled environments discussed in @emph{The LaTeX Companion} by
5750 Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
5751 @b{Ref@TeX{}}'s defaults.
5754 @noindent @b{Version 2.17}
5757 Label prefix expands % escapes with current file name and other stuff.
5759 Citation format now with % escapes. This is not backward
5762 TEXINPUTS variable recognized when looking for input files.
5764 Context can be the nth argument of a macro.
5766 Searching in the select buffer is now possible (@kbd{C-s} and
5769 Display and derive-label can use two different context methods.
5771 AMSmath @code{xalignat} and @code{xxalignat} added.
5774 @noindent @b{Version 2.14}
5777 Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
5781 @noindent @b{Version 2.11}
5784 Submitted for inclusion to Emacs and XEmacs.
5787 @noindent @b{Version 2.07}
5790 New functions @code{reftex-search-document},
5791 @code{reftex-query-replace-document}.
5794 @noindent @b{Version 2.05}
5797 Support for @file{custom.el}.
5799 New function @code{reftex-grep-document} (thanks to Stephen Eglen).
5802 @noindent @b{Version 2.03}
5805 @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
5806 default environments.
5808 @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
5810 New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
5811 @code{reftex-arg-cite}.
5813 Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
5816 @code{reftex-add-to-label-alist} (to be called from AUCTeX style
5819 Finding context with a hook function.
5821 Sorting BibTeX entries (new variable:
5822 @code{reftex-sort-bibtex-matches}).
5825 @noindent @b{Version 2.00}
5828 Labels can be derived from context (default for sections).
5830 Configuration of label insertion and label referencing revised.
5832 Crossref fields in BibTeX database entries.
5834 @code{reftex-toc} introduced (thanks to Stephen Eglen).
5837 @noindent @b{Version 1.09}
5840 Support for @code{tex-main-file}, an analogue for
5846 @noindent @b{Version 1.07}
5849 @b{Ref@TeX{}} gets its own menu.
5852 @noindent @b{Version 1.05}
5858 @noindent @b{Version 1.04}
5861 Macros as wrappers, AMSTeX support, delayed context parsing for
5866 @noindent @b{Version 1.00}
5869 released on 7 Jan 1997.
5876 @node Index, , , Top
5885 arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43