Mercurial > emacs
changeset 84312:9502afe20dfd
Move here from ../../man
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 05:01:53 +0000 |
| parents | 1c709b7e1512 |
| children | 0ae78db27d60 |
| files | doc/misc/reftex.texi |
| diffstat | 1 files changed, 5898 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/reftex.texi Thu Sep 06 05:01:53 2007 +0000 @@ -0,0 +1,5898 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../info/reftex +@settitle RefTeX User Manual +@synindex ky cp +@syncodeindex vr cp +@syncodeindex fn cp + +@c Version and Contact Info +@set VERSION 4.31 +@set EDITION 4.31 +@set DATE February 2006 +@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site} +@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page} +@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} +@set MAINTAINER the AUC@TeX{} project +@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org}) +@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org}) +@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org}) +@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site} +@c %**end of header + +@copying +This file documents @b{Ref@TeX{}}, a package to do labels, references, +citations and indices for LaTeX documents with Emacs. + +This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for +@b{Ref@TeX{}} @value{VERSION} + +Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, +2005, 2006, 2007 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations. +@end direntry + +@finalout + +@c Macro definitions + +@c Subheadings inside a table. Need a difference between info and the rest. +@macro tablesubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@titlepage +@title Ref@TeX{} User Manual +@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs +@subtitle Edition @value{EDITION}, @value{DATE} + +@author by Carsten Dominik +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top,,,(dir) + +@b{Ref@TeX{}} is a package for managing Labels, References, +Citations and index entries with GNU Emacs. + +Don't be discouraged by the size of this manual, which covers +@b{Ref@TeX{}} in great depth. All you need to know to use +@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a +Nutshell}). You can go back later to other parts of this document when +needed. + +@menu +* Introduction:: Quick-Start information. + +* Table of Contents:: A Tool to move around quickly. +* Labels and References:: Creating and referencing labels. +* Citations:: Creating Citations. +* Index Support:: Creating and Checking Index Entries. +* Viewing Cross-References:: Who references or cites what? + +* RefTeXs Menu:: The Ref menu in the menubar. +* Key Bindings:: The default key bindings. +* Faces:: Fontification of RefTeX's buffers. +* Multifile Documents:: Document spread over many files. +* Language Support:: How to support other languages. +* Finding Files:: Included TeX files and BibTeX .bib files. +* AUCTeX:: Cooperation with AUCTeX. +* Optimizations:: When RefTeX is too slow. +* Problems and Work-Arounds:: First Aid. +* Imprint:: Author, Web-site, Thanks + +* Commands:: Which are the available commands. +* Options:: How to extend and configure RefTeX. +* Keymaps and Hooks:: For customization. +* Changes:: A List of recent changes to RefTeX. +* GNU Free Documentation License:: The license for this documentation. + +The Index + +* Index:: The full index. + +@detailmenu + +Introduction + +* Installation:: How to install and activate RefTeX. +* RefTeX in a Nutshell:: A brief summary and quick guide. + +Labels and References + +* Creating Labels:: +* Referencing Labels:: +* Builtin Label Environments:: The environments RefTeX knows about. +* Defining Label Environments:: ... and environments it doesn't. +* Reference Info:: View the label corresponding to a \ref. +* xr (LaTeX package):: References to external documents. +* varioref (LaTeX package):: How to create \vref instead of \ref. +* fancyref (LaTeX package):: How to create \fref instead of \ref. + +Defining Label Environments + +* Theorem and Axiom:: Defined with @code{\newenvironment}. +* Quick Equation:: When a macro sets the label type. +* Figure Wrapper:: When a macro argument is a label. +* Adding Magic Words:: Other words for other languages. +* Using \eqref:: How to switch to this AMS-LaTeX macro. +* Non-Standard Environments:: Environments without \begin and \end +* Putting it Together:: How to combine many entries. + +Citations + +* Creating Citations:: How to create them. +* Citation Styles:: Natbib, Harvard, Chicago and Co. +* Citation Info:: View the corresponding database entry. +* Chapterbib and Bibunits:: Multiple bibliographies in a Document. +* Citations Outside LaTeX:: How to make citations in Emails etc. +* BibTeX Database Subsets:: Extract parts of a big database. + +Index Support + +* Creating Index Entries:: Macros and completion of entries. +* The Index Phrases File:: A special file for global indexing. +* Displaying and Editing the Index:: The index editor. +* Builtin Index Macros:: The index macros RefTeX knows about. +* Defining Index Macros:: ... and macros it doesn't. + +The Index Phrases File + +* Collecting Phrases:: Collecting from document or external. +* Consistency Checks:: Check for duplicates etc. +* Global Indexing:: The interactive indexing process. + +AUCTeX + +* AUCTeX-RefTeX Interface:: How both packages work together +* Style Files:: AUCTeX's style files can support RefTeX +* Bib-Cite:: Hypertext reading of a document + +Options, Keymaps, Hooks + +* Options (Table of Contents):: +* Options (Defining Label Environments):: +* Options (Creating Labels):: +* Options (Referencing Labels):: +* Options (Creating Citations):: +* Options (Index Support):: +* Options (Viewing Cross-References):: +* Options (Finding Files):: +* Options (Optimizations):: +* Options (Fontification):: +* Options (Misc):: + +@end detailmenu +@end menu + +@end ifnottex + +@node Introduction, Table of Contents, , Top +@chapter Introduction +@cindex Introduction + +@b{Ref@TeX{}} is a specialized package for support of labels, +references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps +itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, +and @code{\index}. Using these macros usually requires looking up +different parts of the document and searching through BibTeX database +files. @b{Ref@TeX{}} automates these time--consuming tasks almost +entirely. It also provides functions to display the structure of a +document and to move around in this structure quickly. + +@iftex +Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} +in great depth. All you need to know to use @b{Ref@TeX{}} can be +summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go +back later to other parts of this document when needed. +@end iftex + +@xref{Imprint}, for information about who to contact for help, bug +reports or suggestions. + +@menu +* Installation:: How to install and activate RefTeX. +* RefTeX in a Nutshell:: A brief summary and quick guide. +@end menu + +@node Installation, RefTeX in a Nutshell, , Introduction +@section Installation +@cindex Installation + +@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version +20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. +XEmacs 21.x users want to install the corresponding plug-in package +which is available from the @value{XEMACSFTP}. See the XEmacs 21.x +documentation on package installation for details. + +Users of earlier Emacs distributions (including Emacs 19) can get a copy +of the @b{Ref@TeX{}} distribution from the maintainers web-page. +@xref{Imprint}, for more information. + +@section Environment +@cindex Finding files +@cindex BibTeX database files, not found +@cindex TeX files, not found +@cindex @code{TEXINPUTS}, environment variable +@cindex @code{BIBINPUTS}, environment variable + +@b{Ref@TeX{}} needs to access all files which are part of a multifile +document, and the BibTeX database files requested by the +@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will +require a search path, i.e. a list of directories to check. Normally +this list is stored in the environment variables @code{TEXINPUTS} and +@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some +systems these variables do not contain the full search path. If +@b{Ref@TeX{}} does not work for you because it cannot find some files, +read @ref{Finding Files}. + +@section Entering @b{Ref@TeX{}} Mode + +@findex turn-on-reftex +@findex reftex-mode +@vindex LaTeX-mode-hook +@vindex latex-mode-hook +To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use +@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX +files, add the following lines to your @file{.emacs} file: + +@example +(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode +(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode +@end example + +@page +@node RefTeX in a Nutshell, , Installation, Introduction +@section @b{Ref@TeX{}} in a Nutshell +@cindex Quick-Start +@cindex Getting Started +@cindex RefTeX in a Nutshell +@cindex Nutshell, RefTeX in a + +@enumerate +@item +@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show +a table of contents of the document. This buffer can display sections, +labels and index entries defined in the document. From the buffer, you +can jump quickly to every part of your document. Press @kbd{?} to get +help. + +@item +@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels +and to find the correct key for references quickly. It distinguishes +labels for different environments, knows about all standard +environments (and many others), and can be configured to recognize any +additional labeled environments you have defined yourself (variable +@code{reftex-label-alist}). + +@itemize @bullet +@item +@b{Creating Labels}@* +Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. +@b{Ref@TeX{}} will either +@itemize @minus +@item +derive a label from context (default for section labels) +@item +prompt for a label string (default for figures and tables) or +@item +insert a simple label made of a prefix and a number (all other +environments) +@end itemize +@noindent +Which labels are created how is configurable with the variable +@code{reftex-insert-label-flags}. + +@item +@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} +(@code{reftex-reference}). This shows an outline of the document with +all labels of a certain type (figure, equation,...) and some label +context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro +into the original buffer. +@end itemize + +@item +@b{Citations}@* +Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a +regular expression to search in current BibTeX database files (as +specified in the @code{\bibliography} command) and pull out a list of +matches for you to choose from. The list is @emph{formatted} and +sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} +(see the variable @code{reftex-cite-format} if you want to insert +different macros). + +@item +@b{Index Support}@* +@b{Ref@TeX{}} helps to enter index entries. It also compiles all +entries into an alphabetically sorted @file{*Index*} buffer which you +can use to check and edit the entries. @b{Ref@TeX{}} knows about the +standard index macros and can be configured to recognize any additional +macros you have defined (@code{reftex-index-macros}). Multiple indices +are supported. + +@itemize @bullet +@item +@b{Creating Index Entries}@* +To index the current selection or the word at point, type @kbd{C-c /} +(@code{reftex-index-selection-or-word}). The default macro +@code{reftex-index-default-macro} will be used. For a more complex entry +type @kbd{C-c <} (@code{reftex-index}), select any of the index macros +and enter the arguments with completion. + +@item +@b{The Index Phrases File (Delayed Indexing)}@* +Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add +the current word or selection to a special @emph{index phrase file}. +@b{Ref@TeX{}} can later search the document for occurrences of these +phrases and let you interactively index the matches. + +@item +@b{Displaying and Editing the Index}@* +To display the compiled index in a special buffer, type @kbd{C-c >} +(@code{reftex-display-index}). From that buffer you can check and edit +all entries. +@end itemize + +@page +@item @b{Viewing Cross-References}@* +When point is on the @var{key} argument of a cross--referencing macro +(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, +@code{\index}, and variations) or inside a BibTeX database entry, you +can press @kbd{C-c &} (@code{reftex-view-crossref}) to display +corresponding locations in the document and associated BibTeX database +files. @* +When the enclosing macro is @code{\cite} or @code{\ref} and no other +message occupies the echo area, information about the citation or label +will automatically be displayed in the echo area. + +@item +@b{Multifile Documents}@* +Multifile Documents are fully supported. The included files must have a +file variable @code{TeX-master} or @code{tex-main-file} pointing to the +master file. @b{Ref@TeX{}} provides cross-referencing information from +all parts of the document, and across document borders +(@file{xr.sty}). + +@item +@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in +order to find labels and other information. It does it automatically +once and updates its list internally when @code{reftex-label} and +@code{reftex-index} are used. To enforce reparsing, call any of the +commands described above with a raw @kbd{C-u} prefix, or press the +@kbd{r} key in the label selection buffer, the table of contents +buffer, or the index buffer. + +@item +@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can +cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX +contains style files which trigger appropriate settings in +@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no +additional customizations will be necessary. + +@item +@b{Useful Settings}@* +To integrate RefTeX with AUCTeX, use +@lisp +(setq reftex-plug-into-AUCTeX t) +@end lisp + +To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, +customize the variables +@example +@code{reftex-label-alist} @r{(for label macros/environments)} +@code{reftex-section-levels} @r{(for sectioning commands)} +@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} +@code{reftex-index-macros} @r{(for @code{\index}-like macros)} +@code{reftex-index-default-macro} @r{(to set the default macro)} +@end example +If you have a large number of macros defined, you may want to write +an AUCTeX style file to support them with both AUCTeX and +@b{Ref@TeX{}}. + +@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus +until you have picked up the key bindings. For an overview of what you +can do in each of the different special buffers, press @kbd{?}. Read +the manual if you get stuck, of if you are curious what else might be +available. The first part of the manual explains in +a tutorial way how to use and customize @b{Ref@TeX{}}. The second +part is a command and variable reference. +@end enumerate + +@node Table of Contents, Labels and References, Introduction, Top +@chapter Table of Contents +@cindex @file{*toc*} buffer +@cindex Structure editing +@cindex Table of contents buffer +@findex reftex-toc +@kindex C-c = + +Pressing the keys @kbd{C-c =} pops up a buffer showing the table of +contents of the document. By default, this @file{*toc*} buffer shows +only the sections of a document. Using the @kbd{l} and @kbd{i} keys you +can display all labels and index entries defined in the document as +well. + +With the cursor in any of the lines denoting a location in the +document, simple key strokes will display the corresponding part in +another window, jump to that location, or perform other actions. + +@kindex ? +Here is a list of special commands in the @file{*toc*} buffer. A +summary of this information is always available by pressing +@kbd{?}. + +@table @kbd + +@tablesubheading{General} +@item ? +Display a summary of commands. + +@item 0-9, - +Prefix argument. + +@tablesubheading{Moving around} +@item n +Goto next entry in the table of context. + +@item p +Goto previous entry in the table of context. + +@item C-c C-n +Goto next section heading. Useful when many labels and index entries +separate section headings. + +@item C-c C-p +Goto previous section heading. + +@item N z +Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps +to section 3. + +@tablesubheading{Access to document locations} +@item @key{SPC} +Show the corresponding location in another window. This command does +@emph{not} select that other window. + +@item @key{TAB} +Goto the location in another window. + +@item @key{RET} +Go to the location and hide the @file{*toc*} buffer. This will restore +the window configuration before @code{reftex-toc} (@kbd{C-c =}) was +called. + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a line has the same effect as @key{RET}. +See also variable @code{reftex-highlight-selection}, @ref{Options +(Fontification)}. + +@item f +@vindex reftex-toc-follow-mode +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always show the location corresponding to the line at point in the +@file{*toc*} buffer. This is similar to pressing @key{SPC} after each +cursor motion. The default for this flag can be set with the variable +@code{reftex-toc-follow-mode}. Note that only context in files already +visited is shown. @b{Ref@TeX{}} will not visit a file just for follow +mode. See, however, the variable +@code{reftex-revisit-to-follow}. + +@item . +Show calling point in another window. This is the point from where +@code{reftex-toc} was last called. + +@page +@tablesubheading{Promotion and Demotion} + +@item < +Promote the current section. This will convert @code{\section} to +@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is +an active region, all sections in the region will be promoted, including +the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh +document scan before executing this command - if necessary, it will +automatically do this scan and ask the user to repeat the promotion +command. + +@item > +Demote the current section. This is the opposite of promotion. It will +convert @code{\chapter} to @code{\section} etc. If there is an active +region, all sections in the region will be demoted, including the one at +point. + +@item M-% +Rename the label at point. While generally not recommended, this can be +useful when a package like @file{fancyref} is used where the label +prefix determines the wording of a reference. After a +promotion/demotion it may be necessary to change a few labels from +@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be +used to do this - it launches a query replace to rename the definition +and all references of a label. + +@tablesubheading{Exiting} +@item q +Hide the @file{*toc*} buffer, return to the position where +@code{reftex-toc} was last called. + +@item k +Kill the @file{*toc*} buffer, return to the position where +@code{reftex-toc} was last called. + +@item C-c > +Switch to the @file{*Index*} buffer of this document. With prefix +@samp{2}, restrict the index to the section at point in the @file{*toc*} +buffer. + +@tablesubheading{Controlling what gets displayed} + +@item t +@vindex reftex-toc-max-level +Change the maximum level of toc entries displayed in the @file{*toc*} +buffer. Without prefix arg, all levels will be included. With prefix +arg (e.g @kbd{3 t}), ignore all toc entries with level greater than +@var{arg} (3 in this case). Chapters are level 1, sections are level 2. +The mode line @samp{T<>} indicator shows the current value. The default +depth can be configured with the variable +@code{reftex-toc-max-level}. + +@item F +@vindex reftex-toc-include-file-boundaries +Toggle the display of the file borders of a multifile document in the +@file{*toc*} buffer. The default for this flag can be set with the +variable @code{reftex-toc-include-file-boundaries}. + +@item l +@vindex reftex-toc-include-labels +Toggle the display of labels in the @file{*toc*} buffer. The default +for this flag can be set with the variable +@code{reftex-toc-include-labels}. When called with a prefix argument, +@b{Ref@TeX{}} will prompt for a label type and include only labels of +the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} +indicator shows which labels are included. + +@item i +@vindex reftex-toc-include-index-entries +Toggle the display of index entries in the @file{*toc*} buffer. The +default for this flag can be set with the variable +@code{reftex-toc-include-index-entries}. When called with a prefix +argument, @b{Ref@TeX{}} will prompt for a specific index and include +only entries in the selected index in the @file{*toc*} buffer. The mode +line @samp{I<>} indicator shows which index is used. + +@item c +@vindex reftex-toc-include-context +Toggle the display of label and index context in the @file{*toc*} +buffer. The default for this flag can be set with the variable +@code{reftex-toc-include-context}. + +@tablesubheading{Updating the buffer} + +@item g +Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the +document. + +@item r +@vindex reftex-enable-partial-scans +Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When +@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this +location is defined in, not the entire document. + +@item C-u r +Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} +buffer. + +@item x +Switch to the @file{*toc*} buffer of an external document. When the +current document is using the @code{xr} package (@pxref{xr (LaTeX +package)}), @b{Ref@TeX{}} will switch to one of the external +documents. + + +@tablesubheading{Automatic recentering} + +@item d +Toggle the display of a dedicated frame displaying just the @file{*toc*} +buffer. Follow mode and visiting locations will not work that frame, +but automatic recentering will make this frame always show your current +editing location in the document (see below). + +@item a +Toggle the automatic recentering of the @file{*toc*} buffer. When this +option is on, moving around in the document will cause the @file{*toc*} +to always highlight the current section. By default, this option is +active while the dedicated @file{*TOC*} frame exists. See also the +variable @code{reftex-auto-recenter-toc}. + +@end table + +@vindex reftex-toc-map +In order to define additional commands for the @file{*toc*} buffer, the +keymap @code{reftex-toc-map} may be used. + +@findex reftex-toc-recenter +@vindex reftex-auto-recenter-toc +@vindex reftex-idle-time +@cindex @file{*toc*} buffer, recentering +@cindex Table of contents buffer, recentering +@kindex C-c - +If you call @code{reftex-toc} while the @file{*toc*} buffer already +exists, the cursor will immediately jump to the right place, i.e. the +section from which @code{reftex-toc} was called will be highlighted. +The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay +the @file{*toc*} buffer and highlight the correct line without actually +selecting the @file{*toc*} window. This can be useful to quickly find +out where in the document you currently are. You can also automate this +by asking RefTeX to keep track of your current editing position in the +TOC. The TOC window will then be updated whenever you stop typing for +more than @code{reftex-idle-time} seconds. By default this works only +with the dedicated @file{*TOC*} frame. But you can also force automatic +recentering of the TOC window on the current frame with +@lisp +(setq reftex-auto-recenter-toc t) +@end lisp + + +@cindex Sectioning commands +@cindex KOMA-Script, LaTeX classes +@cindex LaTeX classes, KOMA-Script +@cindex TOC entries for environments +@vindex reftex-section-levels +The section macros recognized by @b{Ref@TeX{}} are all LaTeX section +macros (from @code{\part} to @code{\subsubparagraph}) and the commands +@code{\addchap} and @code{\addsec} from the KOMA-Script classes. +Additional macros can be configured with the variable +@code{reftex-section-levels}. It is also possible to add certain LaTeX +environments to the table of contents. This is probably only useful for +theorem-like environments. @xref{Defining Label Environments}, for an +example. + +@node Labels and References, Citations, Table of Contents, Top +@chapter Labels and References +@cindex Labels in LaTeX +@cindex References in LaTeX +@cindex Label category +@cindex Label environment +@cindex @code{\label} + +LaTeX provides a powerful mechanism to deal with cross--references in a +document. When writing a document, any part of it can be marked with a +label, like @samp{\label@{mark@}}. LaTeX records the current value of a +certain counter when a label is defined. Later references to this label +(like @samp{\ref@{mark@}}) will produce the recorded value of the +counter. + +Labels can be used to mark sections, figures, tables, equations, +footnotes, items in enumerate lists etc. LaTeX is context sensitive in +doing this: A label defined in a figure environment automatically +records the figure counter, not the section counter. + +Several different environments can share a common counter and therefore +a common label category. E.g. labels in both @code{equation} and +@code{eqnarray} environments record the value of the same counter - the +equation counter. + +@menu +* Creating Labels:: +* Referencing Labels:: +* Builtin Label Environments:: The environments RefTeX knows about. +* Defining Label Environments:: ... and environments it doesn't. +* Reference Info:: View the label corresponding to a \ref. +* xr (LaTeX package):: References to external documents. +* varioref (LaTeX package):: How to create \vref instead of \ref. +* fancyref (LaTeX package):: How to create \fref instead of \ref. +@end menu + +@node Creating Labels, Referencing Labels, , Labels and References +@section Creating Labels +@cindex Creating labels +@cindex Labels, creating +@cindex Labels, deriving from context +@kindex C-c ( +@findex reftex-label + +In order to create a label in a LaTeX document, press @kbd{C-c (} +(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive +and will figure out the environment it currently is in and adapt the +label to that environment. A label usually consists of a short prefix +indicating the type of the label and a unique mark. @b{Ref@TeX{}} has +3 different modes to create this mark. + +@enumerate +@item +@vindex reftex-translate-to-ascii-function +@vindex reftex-derive-label-parameters +@vindex reftex-label-illegal-re +@vindex reftex-abbrev-parameters +A label can be derived from context. This means, @b{Ref@TeX{}} takes +the context of the label definition and constructs a label from +that@footnote{Note that the context may contain constructs which are +invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from +accented Latin-1 characters and remove everything else which is not +valid in labels. This mechanism is safe, but may not be satisfactory +for non-western languages. Check the following variables if you need to +change things: @code{reftex-translate-to-ascii-function}, +@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, +@code{reftex-abbrev-parameters}.}. This works best for section labels, +where the section heading is used to construct a label. In fact, +@b{Ref@TeX{}}'s default settings use this method only for section +labels. You will be asked to confirm the derived label, or edit +it. + +@item +We may also use a simple unique number to identify a label. This is +mostly useful for labels where it is difficult to come up with a very +good descriptive name. @b{Ref@TeX{}}'s default settings use this method +for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} +tends to write documents with many equations and finds it impossible +to come up with good names for each of them. These simple labels are +inserted without query, and are therefore very fast. Good descriptive +names are not really necessary as @b{Ref@TeX{}} will provide context to +reference a label (@pxref{Referencing Labels}). + +@item +The third method is to ask the user for a label. This is most +useful for things which are easy to describe briefly and do not turn up +too frequently in a document. @b{Ref@TeX{}} uses this for figures and +tables. Of course, one can enter the label directly by typing the full +@samp{\label@{mark@}}. The advantage of using @code{reftex-label} +anyway is that @b{Ref@TeX{}} will know that a new label has been defined. +It will then not be necessary to rescan the document in order to access +this label later. +@end enumerate + +@vindex reftex-insert-label-flags +If you want to change the way certain labels are created, check out the +variable @code{reftex-insert-label-flags} (@pxref{Options (Creating +Labels)}). + +If you are using AUCTeX to write your LaTeX documents, you can +set it up to delegate the creation of labels to +@b{Ref@TeX{}}. @xref{AUCTeX}, for more information. + +@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References +@section Referencing Labels +@cindex Referencing labels +@cindex Labels, referencing +@cindex Selection buffer, labels +@cindex Selection process +@cindex @code{\ref} +@kindex C-c ) +@findex reftex-reference + +@vindex reftex-trust-label-prefix +@b{Ref@TeX{}} scans the document in order to find all labels. To make +referencing labels easier, it assigns to each label a category, the +@emph{label type} (for example section, table, figure, equation, etc.). +In order to determine the label type, RefTeX parses around each label +to see in what kind of environments it is located. You can speed up +the parsing by using type-specific prefixes for labels and configuring +the variable @code{reftex-trust-label-prefix}. + +Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c +)} in order to reference a label (reftex-reference). This will start a +selection process and finally insert the complete @samp{\ref@{label@}} +into the buffer. + +First, @b{Ref@TeX{}} will determine the label category which is required. +Often that can be figured out from context. For example, if you +write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows +that an equation label is going to be referenced. If it cannot figure +out what label category is needed, it will query for one. + +You will then be presented with a label selection menu. This is a +special buffer which contains an outline of the document along with all +labels of the given label category. In addition, next to the label +there will be one line of context of the label definition, which is some +text in the buffer near the label definition. Usually this is +sufficient to identify the label. If you are unsure about a certain +label, pressing @key{SPC} will show the label definition point in +another window. + +In order to reference a label, move to cursor to the correct label and +press @key{RET}. You can also reference several labels with a single +call to @code{reftex-reference} by marking entries with the @kbd{m} +key (see below). + +@kindex ? +Here is a list of special commands in the selection buffer. A summary +of this information is always available from the selection process by +pressing @kbd{?}. + + + +@table @kbd +@tablesubheading{General} +@item ? +Show a summary of available commands. + +@item 0-9,- +Prefix argument. + +@tablesubheading{Moving around} +@item n +Go to next label. + +@item p +Go to previous label. + +@item b +Jump back to the position where you last left the selection buffer. +Normally this should get you back to the last referenced label. + +@item C-c C-n +Goto next section heading. + +@item C-c C-p +Goto previous section heading. + +@item N z +Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to +section 3. + +@tablesubheading{Displaying Context} +@item @key{SPC} +Show the surroundings of the definition of the current label in another +window. See also the @kbd{f} key. + +@item f +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always display the full context of the current label. This is similar +to pressing @key{SPC} after each cursor motion. Note that only context +in files already visited is shown. @b{RefTeX} will not visit a file +just for follow mode. See, however, the variable +@code{reftex-revisit-to-follow}. + +@item . +Show insertion point in another window. This is the point from where you +called @code{reftex-reference}. + +@tablesubheading{Selecting a label and creating the reference} +@item @key{RET} +Insert a reference to the label at point into the buffer from which the +selection process was started. When entries have been marked, @key{RET} +references all marked labels. + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a label will accept it like @key{RET} +would. See also variable @code{reftex-highlight-selection}, @ref{Options +(Misc)}. + +@vindex reftex-multiref-punctuation +@item m - + , +Mark the current entry. When several entries have been marked, pressing +@kbd{RET} will accept all of them and place them into several +@code{\ref} macros. The special markers @samp{,-+} also store a +separator to be inserted before the corresponding reference. So marking +six entries with the keys @samp{m , , - , +} will give a reference list +like this (see the variable @code{reftex-multiref-punctuation}) +@example +In eqs. (1), (2), (3)--(4), (5) and (6) +@end example + +@item u +Unmark a marked entry. + +@c FIXME: Do we need `A' as well for consistency? +@cindex LaTeX packages, @code{saferef} +@cindex @code{saferef}, LaTeX package +@item a +Accept the marked entries and put all labels as a comma-separated list +into one @emph{single} @code{\ref} macro. Some packages like +@file{saferef.sty} support multiple references in this way. + +@item l +Use the last referenced label(s) again. This is equivalent to moving to +that label and pressing @key{RET}. + +@item @key{TAB} +Enter a label with completion. This may also be a label which does not +yet exist in the document. + +@item v +@cindex @code{varioref}, LaTeX package +@cindex @code{\vref} +@cindex LaTeX packages, @code{varioref} +Toggle between @code{\ref} and @code{\vref} macro for references. The +@code{\vref} macro is defined in the @code{varioref} LaTeX package. +With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} +macro. The current state of this flag is displayed by the @samp{S<>} +indicator in the mode line of the selection buffer. + +@item V +@cindex @code{fancyref}, LaTeX package +@cindex @code{\fref} +@cindex @code{\Fref} +@cindex LaTeX packages, @code{fancyref} +Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The +@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} +LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a +@code{\fref} or @code{\Fref} macro. The current state of this flag is +displayed by the @samp{S<>} indicator in the mode line of the +selection buffer. + +@tablesubheading{Exiting} + +@item q +Exit the selection process without inserting any reference into the +buffer. + +@tablesubheading{Controlling what gets displayed} +@vindex reftex-label-menu-flags +The defaults for the following flags can be configured with the variable +@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). + +@item c +Toggle the display of the one-line label definition context in the +selection buffer. + +@item F +Toggle the display of the file borders of a multifile document in the +selection buffer. + +@item t +Toggle the display of the table of contents in the selection buffer. +With prefix @var{arg}, change the maximum level of toc entries displayed +to @var{arg}. Chapters are level 1, section are level 2. + +@item # +Toggle the display of a label counter in the selection buffer. + +@item % +Toggle the display of labels hidden in comments in the selection +buffers. Sometimes, you may have commented out parts of your document. +If these parts contain label definitions, @b{Ref@TeX{}} can still display +and reference these labels. + +@tablesubheading{Updating the buffer} +@item g +Update the menu. This will rebuilt the menu from the internal label +list, but not reparse the document (see @kbd{r}). + +@item r +@vindex reftex-enable-partial-scans +Reparse the document to update the information on all labels and rebuild +the menu. If the variable @code{reftex-enable-partial-scans} is +non-@code{nil} and your document is a multifile document, this will +reparse only a part of the document (the file in which the label at +point was defined). + +@item C-u r +Reparse the @emph{entire} document. + +@item s +Switch the label category. After prompting for another label category, +a menu for that category will be shown. + +@item x +Reference a label from an external document. With the LaTeX package +@code{xr} it is possible to reference labels defined in another +document. This key will switch to the label menu of an external +document and let you select a label from there (@pxref{xr (LaTeX +package),,xr}). + +@end table + +@vindex reftex-select-label-map +In order to define additional commands for the selection process, the +keymap @code{reftex-select-label-map} may be used. + +@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References +@section Builtin Label Environments +@cindex Builtin label environments +@cindex Label environments, builtin +@cindex Environments, builtin +@vindex reftex-label-alist +@vindex reftex-label-alist-builtin + +@b{Ref@TeX{}} needs to be aware of the environments which can be referenced +with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} +recognizes all labeled environments and macros discussed in @cite{The +LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley +1994.}. These are: + +@itemize @minus +@item +@cindex @code{figure}, LaTeX environment +@cindex @code{figure*}, LaTeX environment +@cindex @code{table}, LaTeX environment +@cindex @code{table*}, LaTeX environment +@cindex @code{equation}, LaTeX environment +@cindex @code{eqnarray}, LaTeX environment +@cindex @code{enumerate}, LaTeX environment +@cindex @code{\footnote}, LaTeX macro +@cindex LaTeX macro @code{footnote} +@cindex LaTeX core +@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, +@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is +the LaTeX core stuff) +@item +@cindex AMS-LaTeX +@cindex @code{amsmath}, LaTeX package +@cindex LaTeX packages, @code{amsmath} +@cindex @code{align}, AMS-LaTeX environment +@cindex @code{gather}, AMS-LaTeX environment +@cindex @code{multline}, AMS-LaTeX environment +@cindex @code{flalign}, AMS-LaTeX environment +@cindex @code{alignat}, AMS-LaTeX environment +@cindex @code{xalignat}, AMS-LaTeX environment +@cindex @code{xxalignat}, AMS-LaTeX environment +@cindex @code{subequations}, AMS-LaTeX environment +@code{align}, @code{gather}, @code{multline}, @code{flalign}, +@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} +(from AMS-LaTeX's @file{amsmath.sty} package) +@item +@cindex @code{endnote}, LaTeX package +@cindex LaTeX packages, @code{endnote} +@cindex @code{\endnote}, LaTeX macro +the @code{\endnote} macro (from @file{endnotes.sty}) +@item +@cindex @code{fancybox}, LaTeX package +@cindex LaTeX packages, @code{fancybox} +@cindex @code{Beqnarray}, LaTeX environment +@code{Beqnarray} (@file{fancybox.sty}) +@item +@cindex @code{floatfig}, LaTeX package +@cindex LaTeX packages, @code{floatfig} +@cindex @code{floatingfig}, LaTeX environment +@code{floatingfig} (@file{floatfig.sty}) +@item +@cindex @code{longtable}, LaTeX package +@cindex LaTeX packages, @code{longtable} +@cindex @code{longtable}, LaTeX environment +@code{longtable} (@file{longtable.sty}) +@item +@cindex @code{picinpar}, LaTeX package +@cindex LaTeX packages, @code{picinpar} +@cindex @code{figwindow}, LaTeX environment +@cindex @code{tabwindow}, LaTeX environment +@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) +@item +@cindex @code{sidecap}, LaTeX package +@cindex LaTeX packages, @code{sidecap} +@cindex @code{SCfigure}, LaTeX environment +@cindex @code{SCtable}, LaTeX environment +@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) +@item +@cindex @code{rotating}, LaTeX package +@cindex LaTeX packages, @code{rotating} +@cindex @code{sidewaysfigure}, LaTeX environment +@cindex @code{sidewaystable}, LaTeX environment +@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) +@item +@cindex @code{subfig}, LaTeX package +@cindex LaTeX packages, @code{subfigure} +@cindex @code{subfigure}, LaTeX environment +@cindex @code{subfigure*}, LaTeX environment +@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro +(@file{subfigure.sty}) +@item +@cindex @code{supertab}, LaTeX package +@cindex LaTeX packages, @code{supertab} +@cindex @code{supertabular}, LaTeX environment +@code{supertabular} (@file{supertab.sty}) +@item +@cindex @code{wrapfig}, LaTeX package +@cindex LaTeX packages, @code{wrapfig} +@cindex @code{wrapfigure}, LaTeX environment +@code{wrapfigure} (@file{wrapfig.sty}) +@end itemize + +If you want to use other labeled environments, defined with +@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize +them (@pxref{Defining Label Environments}). + +@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References +@section Defining Label Environments +@cindex Label environments, defining + +@vindex reftex-label-alist +@b{Ref@TeX{}} can be configured to recognize additional labeled +environments and macros. This is done with the variable +@code{reftex-label-alist} (@pxref{Options (Defining Label +Environments)}). If you are not familiar with Lisp, you can use the +@code{custom} library to configure this rather complex variable. To do +this, use + +@example +@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} +@end example + +@vindex reftex-label-alist-builtin +Here we will discuss a few examples, in order to make things clearer. +It can also be instructive to look at the constant +@code{reftex-label-alist-builtin} which contains the entries for +all the builtin environments and macros (@pxref{Builtin Label +Environments}). + +@menu +* Theorem and Axiom:: Defined with @code{\newenvironment}. +* Quick Equation:: When a macro sets the label type. +* Figure Wrapper:: When a macro argument is a label. +* Adding Magic Words:: Other words for other languages. +* Using \eqref:: How to switch to this AMS-LaTeX macro. +* Non-Standard Environments:: Environments without \begin and \end +* Putting it Together:: How to combine many entries. +@end menu + +@node Theorem and Axiom, Quick Equation, , Defining Label Environments +@subsection Theorem and Axiom Environments +@cindex @code{theorem}, newtheorem +@cindex @code{axiom}, newtheorem +@cindex @code{\newtheorem} + +Suppose you are using @code{\newtheorem} in LaTeX in order to define two +new environments, @code{theorem} and @code{axiom} + +@example +\newtheorem@{axiom@}@{Axiom@} +\newtheorem@{theorem@}@{Theorem@} +@end example + +@noindent +to be used like this: + +@example +\begin@{axiom@} +\label@{ax:first@} + .... +\end@{axiom@} +@end example + +So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new +labeled environments which define their own label categories. We can +either use Lisp to do this (e.g. in @file{.emacs}) or use the custom +library. With Lisp it would look like this + +@lisp +(setq reftex-label-alist + '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) + ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) +@end lisp + +The type indicator characters @code{?a} and @code{?h} are used for +prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} +was chosen for @code{theorem} since @code{?t} is already taken by +@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, +@code{?i}, @code{?n} are already used for standard environments. + +@noindent +The labels for Axioms and Theorems will have the prefixes @samp{ax:} and +@samp{thr:}, respectively. @xref{AUCTeX}, for information on how +AUCTeX can use RefTeX to automatically create labels when a new environment +is inserted into a buffer. Additionally, the following needs to be +added to one's .emacs file before AUCTeX will automatically create +labels for the new environments. + +@lisp +(add-hook 'LaTeX-mode-hook + (lambda () + (LaTeX-add-environments + '("axiom" LaTeX-env-label) + '("theorem" LaTeX-env-label)))) +@end lisp + + +@noindent +The @samp{~\ref@{%s@}} is a format string indicating how to insert +references to these labels. + +@noindent +The next item indicates how to grab context of the label definition. +@itemize @minus +@item +@code{t} means to get it from a default location (from the beginning of +a @code{\macro} or after the @code{\begin} statement). @code{t} is +@emph{not} a good choice for eqnarray and similar environments. +@item +@code{nil} means to use the text right after the label definition. +@item +For more complex ways of getting context, see the variable +@code{reftex-label-alist} (@ref{Options (Defining Label +Environments)}). +@end itemize + +The following list of strings is used to guess the correct label type +from the word before point when creating a reference. E.g. if you +write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, +@b{Ref@TeX{}} will know that you are looking for a theorem label and +restrict the menu to only these labels without even asking. + +The final item in each entry is the level at which the environment +should produce entries in the table of context buffer. If the number is +positive, the environment will produce numbered entries (like +@code{\section}), if it is negative the entries will be unnumbered (like +@code{\section*}). Use this only for environments which structure the +document similar to sectioning commands. For everything else, omit the +item. + +To do the same configuration with @code{customize}, you need to click on +the @code{[INS]} button twice to create two templates and fill them in +like this: + +@example +Reftex Label Alist: [Hide] +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: axiom + Type specification : [Value Menu] Char : a + Label prefix string : [Value Menu] String: ax: + Label reference format: [Value Menu] String: ~\ref@{%s@} + Context method : [Value Menu] After label + Magic words: + [INS] [DEL] String: axiom + [INS] [DEL] String: ax. + [INS] + [X] Make TOC entry : [Value Menu] Level: -2 +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: theorem + Type specification : [Value Menu] Char : h + Label prefix string : [Value Menu] String: thr: + Label reference format: [Value Menu] String: ~\ref@{%s@} + Context method : [Value Menu] Default position + Magic words: + [INS] [DEL] String: theorem + [INS] [DEL] String: theor. + [INS] [DEL] String: th. + [INS] + [X] Make TOC entry : [Value Menu] Level: -3 +@end example + +@vindex reftex-insert-label-flags +@vindex reftex-label-menu-flags +Depending on how you would like the label insertion and selection for +the new environments to work, you might want to add the letters @samp{a} +and @samp{h} to some of the flags in the variables +@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) +and @code{reftex-label-menu-flags} (@pxref{Options (Referencing +Labels)}). + + +@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments +@subsection Quick Equation Macro +@cindex Quick equation macro +@cindex Macros as environment wrappers + +Suppose you would like to have a macro for quick equations. It +could be defined like this: + +@example +\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} +@end example + +@noindent +and used like this: + +@example +Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. +@end example + +We need to tell @b{Ref@TeX{}} that any label defined in the argument of the +@code{\quickeq} is an equation label. Here is how to do this with lisp: + +@lisp +(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) +@end lisp + +The first element in this list is now the macro with empty braces as an +@emph{image} of the macro arguments. @code{?e} indicates that this is +an equation label, the different @code{nil} elements indicate to use the +default values for equations. The @samp{1} as the fifth element +indicates that the context of the label definition should be the 1st +argument of the macro. + +Here is again how this would look in the customization buffer: + +@example +Reftex Label Alist: [Hide] +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: \quickeq@{@} + Type specification : [Value Menu] Char : e + Label prefix string : [Value Menu] Default + Label reference format: [Value Menu] Default + Context method : [Value Menu] Macro arg nr: 1 + Magic words: + [INS] + [ ] Make TOC entry : [Value Menu] No entry +@end example + +@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments +@subsection Figure Wrapping Macro +@cindex Macros as environment wrappers +@cindex Figure wrapping macro + +Suppose you want to make figures not directly with the figure +environment, but with a macro like + +@example +\newcommand@{\myfig@}[5][tbp]@{% + \begin@{figure@}[#1] + \epsimp[#5]@{#2@} + \caption@{#3@} + \label@{#4@} + \end@{figure@}@} +@end example + +@noindent +which would be called like + +@example +\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} +@end example + +Now we need to tell @b{Ref@TeX{}} that the 4th argument of the +@code{\myfig} macro @emph{is itself} a figure label, and where to find +the context. + +@lisp +(setq reftex-label-alist + '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) +@end lisp + +The empty pairs of brackets indicate the different arguments of the +@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} +indicates that this is a figure label which will be listed together with +labels from normal figure environments. The @code{nil} entries for +prefix and reference format mean to use the defaults for figure labels. +The @samp{3} for the context method means to grab the 3rd macro argument +- the caption. + +As a side effect of this configuration, @code{reftex-label} will now +insert the required naked label (without the @code{\label} macro) when +point is directly after the opening parenthesis of a @code{\myfig} macro +argument. + +Again, here the configuration in the customization buffer: + +@example +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} + Type specification : [Value Menu] Char : f + Label prefix string : [Value Menu] Default + Label reference format: [Value Menu] Default + Context method : [Value Menu] Macro arg nr: 3 + Magic words: + [INS] + [ ] Make TOC entry : [Value Menu] No entry +@end example + +@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments +@subsection Adding Magic Words +@cindex Magic words +@cindex German magic words +@cindex Label category + +Sometimes you don't want to define a new label environment or macro, but +just change the information associated with a label category. Maybe you +want to add some magic words, for another language. Changing only the +information associated with a label category is done by giving +@code{nil} for the environment name and then specify the items you want +to define. Here is an example which adds German magic words to all +predefined label categories. + +@lisp +(setq reftex-label-alist + '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) + (nil ?e nil nil nil ("Gleichung" "Gl.")) + (nil ?t nil nil nil ("Tabelle")) + (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) + (nil ?n nil nil nil ("Anmerkung" "Anm.")) + (nil ?i nil nil nil ("Punkt")))) +@end lisp + +@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments +@subsection Using @code{\eqref} +@cindex @code{\eqref}, AMS-LaTeX macro +@cindex AMS-LaTeX +@cindex Label category + +Another case where one only wants to change the information associated +with the label category is to change the macro which is used for +referencing the label. When working with the AMS-LaTeX stuff, you might +prefer @code{\eqref} for doing equation references. Here is how to +do this: + +@lisp +(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) +@end lisp + +@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The +following is equivalent to the line above. + +@lisp +(setq reftex-label-alist '(AMSTeX)) +@end lisp + +Note that this is automatically done by the @file{amsmath.el} style file +of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, +this configuration will not be necessary. + +@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments +@subsection Non-standard Environments +@cindex Non-standard environments +@cindex Environments without @code{\begin} +@cindex Special parser functions +@cindex Parser functions, for special environments + +Some LaTeX packages define environment-like structures without using the +standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse +these directly, but you can write your own special-purpose parser and +use it instead of the name of an environment in an entry for +@code{reftex-label-alist}. The function should check if point is +currently in the special environment it was written to detect. If so, +it must return a buffer position indicating the start of this +environment. The return value must be @code{nil} on failure to detect +the environment. The function is called with one argument @var{bound}. +If non-@code{nil}, @var{bound} is a boundary for backwards searches +which should be observed. We will discuss two examples. + +@cindex LaTeX commands, abbreviated + +Some people define abbreviations for +environments, like @code{\be} for @code{\begin@{equation@}}, and +@code{\ee} for @code{\end@{equation@}}. The parser function would have +to search backward for these macros. When the first match is +@code{\ee}, point is not in this environment. When the first match is +@code{\be}, point is in this environment and the function must return +the beginning of the match. To avoid scanning too far, we can also look +for empty lines which cannot occur inside an equation environment. +Here is the setup: + +@lisp +;; Setup entry in reftex-label-alist, using all defaults for equations +(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) + +(defun detect-be-ee (bound) + ;; Search backward for the macros or an empty line + (if (re-search-backward + "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) + (if (match-beginning 2) + (match-beginning 2) ; Return start of environment + nil) ; Return nil because env is closed + nil)) ; Return nil for not found +@end lisp + +@cindex @code{linguex}, LaTeX package +@cindex LaTeX packages, @code{linguex} +A more complex example is the @file{linguex.sty} package which defines +list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are +terminated by @samp{\z.} or by an empty line. + +@example +\ex. \label@{ex:12@} Some text in an exotic language ... + \a. \label@{ex:13@} more stuff + \b. \label@{ex:14@} still more stuff + \a. List on a deeper level + \b. Another item + \b. and the third one + \z. + \b. Third item on this level. + +... text after the empty line terminating all lists +@end example + +The difficulty is that the @samp{\a.} lists can nest and that an empty +line terminates all list levels in one go. So we have to count nesting +levels between @samp{\a.} and @samp{\z.}. Here is the implementation +for @b{Ref@TeX{}}. + +@lisp +(setq reftex-label-alist + '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) + +(defun detect-linguex (bound) + (let ((cnt 0)) + (catch 'exit + (while + ;; Search backward for all possible delimiters + (re-search-backward + (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" + "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") + nil t) + ;; Check which delimiter was matched. + (cond + ((match-beginning 1) + ;; empty line terminates all - return nil + (throw 'exit nil)) + ((match-beginning 2) + ;; \z. terminates one list level - decrease nesting count + (decf cnt)) + ((match-beginning 3) + ;; \ex. : return match unless there was a \z. on this level + (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) + ((match-beginning 4) + ;; \a. : return match when on level 0, otherwise + ;; increment nesting count + (if (>= cnt 0) + (throw 'exit (match-beginning 4)) + (incf cnt)))))))) +@end lisp + +@node Putting it Together, , Non-Standard Environments, Defining Label Environments +@subsection Putting it all together + +When you have to put several entries into @code{reftex-label-alist}, just +put them after each other in a list, or create that many templates in +the customization buffer. Here is a lisp example which uses several of +the entries described above: + +@lisp +(setq reftex-label-alist + '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) + ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) + ("\\quickeq@{@}" ?e nil nil 1 nil) + AMSTeX + ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) + (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) +@end lisp + +@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References +@section Reference Info +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref +@cindex Cross-references, displaying +@cindex Reference info +@cindex Displaying cross-references +@cindex Viewing cross-references +@kindex C-c & +@kindex S-mouse-2 + +When point is idle for more than @code{reftex-idle-time} seconds on the +argument of a @code{\ref} macro, the echo area will display some +information about the label referenced there. Note that the information +is only displayed if the echo area is not occupied by a different +message. + +@b{Ref@TeX{}} can also display the label definition corresponding to a +@code{\ref} macro, or all reference locations corresponding to a +@code{\label} macro. @xref{Viewing Cross-References}, for more +information. + +@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References +@section @code{xr}: Cross-Document References +@cindex @code{xr}, LaTeX package +@cindex LaTeX packages, @code{xr} +@cindex @code{\externaldocument} +@cindex External documents +@cindex References to external documents +@cindex Cross-document references + +The LaTeX package @code{xr} makes it possible to create references to +labels defined in external documents. The preamble of a document using +@code{xr} will contain something like this: + +@example +\usepackage@{xr@} +\externaldocument[V1-]@{volume1@} +\externaldocument[V3-]@{volume3@} +@end example + +@noindent +and we can make references to any labels defined in these +external documents by using the prefixes @samp{V1-} and @samp{V3-}, +respectively. + +@b{Ref@TeX{}} can be used to create such references as well. Start the +referencing process normally, by pressing @kbd{C-c )}. Select a label +type if necessary. When you see the label selection buffer, pressing +@kbd{x} will switch to the label selection buffer of one of the external +documents. You may then select a label as before and @b{Ref@TeX{}} will +insert it along with the required prefix. + +For this kind of inter-document cross-references, saving of parsing +information and the use of multiple selection buffers can mean a large +speed-up (@pxref{Optimizations}). + +@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References +@section @code{varioref}: Variable Page References +@cindex @code{varioref}, LaTeX package +@cindex @code{\vref} +@cindex LaTeX packages, @code{varioref} +@vindex reftex-vref-is-default +@code{varioref} is a frequently used LaTeX package to create +cross--references with page information. When you want to make a +reference with the @code{\vref} macro, just press the @kbd{v} key in the +selection buffer to toggle between @code{\ref} and @code{\vref} +(@pxref{Referencing Labels}). The mode line of the selection buffer +shows the current status of this switch. If you find that you almost +always use @code{\vref}, you may want to make it the default by +customizing the variable @code{reftex-vref-is-default}. If this +toggling seems too inconvenient, you can also use the command +@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. +Or use AUCTeX to create your macros (@pxref{AUCTeX}). + +@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References +@section @code{fancyref}: Fancy Cross References +@cindex @code{fancyref}, LaTeX package +@cindex @code{\fref} +@cindex @code{\Fref} +@cindex LaTeX packages, @code{fancyref} +@vindex reftex-fref-is-default +@code{fancyref} is a LaTeX package where a macro call like +@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of +the referenced counter but also the complete text around it, like +@samp{Figure 3 on the preceding page}. In order to make it work you +need to use label prefixes like @samp{fig:} consistently - something +@b{Ref@TeX{}} does automatically. When you want to make a reference +with the @code{\fref} macro, just press the @kbd{V} key in the selection +buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} +(@pxref{Referencing Labels}). The mode line of the selection buffer +shows the current status of this switch. If this cycling seems +inconvenient, you can also use the commands @code{reftex-fancyref-fref} +and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c +f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros +(@pxref{AUCTeX}). + +@node Citations, Index Support, Labels and References, Top +@chapter Citations +@cindex Citations +@cindex @code{\cite} + +Citations in LaTeX are done with the @code{\cite} macro or variations of +it. The argument of the macro is a citation key which identifies an +article or book in either a BibTeX database file or in an explicit +@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s +support for citations helps to select the correct key quickly. + +@menu +* Creating Citations:: How to create them. +* Citation Styles:: Natbib, Harvard, Chicago and Co. +* Citation Info:: View the corresponding database entry. +* Chapterbib and Bibunits:: Multiple bibliographies in a Document. +* Citations Outside LaTeX:: How to make citations in Emails etc. +* BibTeX Database Subsets:: Extract parts of a big database. +@end menu + +@node Creating Citations, Citation Styles, , Citations +@section Creating Citations +@cindex Creating citations +@cindex Citations, creating +@findex reftex-citation +@kindex C-c [ +@cindex Selection buffer, citations +@cindex Selection process + +In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then +prompts for a regular expression which will be used to search through +the database and present the list of matches to choose from in a +selection process similar to that for selecting labels +(@pxref{Referencing Labels}). + +The regular expression uses an extended syntax: @samp{&&} defines a +logic @code{and} for regular expressions. For example +@samp{Einstein&&Bose} will match all articles which mention +Bose-Einstein condensation, or which are co-authored by Bose and +Einstein. When entering the regular expression, you can complete on +known citation keys. RefTeX also offers a default when prompting for a +regular expression. This default is the word before the cursor or the +word before the current @samp{\cite} command. Sometimes this may be a +good search key. + +@cindex @code{\bibliography} +@cindex @code{thebibliography}, LaTeX environment +@cindex @code{BIBINPUTS}, environment variable +@cindex @code{TEXBIB}, environment variable +@b{Ref@TeX{}} prefers to use BibTeX database files specified with a +@code{\bibliography} macro to collect its information. Just like +BibTeX, it will search for the specified files in the current directory +and along the path given in the environment variable @code{BIBINPUTS}. +If you do not use BibTeX, but the document contains an explicit +@code{thebibliography} environment, @b{Ref@TeX{}} will collect its +information from there. Note that in this case the information +presented in the selection buffer will just be a copy of relevant +@code{\bibitem} entries, not the structured listing available with +BibTeX database files. + +@kindex ? +In the selection buffer, the following keys provide special commands. A +summary of this information is always available from the selection +process by pressing @kbd{?}. + +@table @kbd +@tablesubheading{General} +@item ? +Show a summary of available commands. + +@item 0-9,- +Prefix argument. + +@tablesubheading{Moving around} +@item n +Go to next article. + +@item p +Go to previous article. + +@tablesubheading{Access to full database entries} +@item @key{SPC} +Show the database entry corresponding to the article at point, in +another window. See also the @kbd{f} key. + +@item f +Toggle follow mode. When follow mode is active, the other window will +always display the full database entry of the current article. This is +equivalent to pressing @key{SPC} after each cursor motion. With BibTeX +entries, follow mode can be rather slow. + +@tablesubheading{Selecting entries and creating the citation} +@item @key{RET} +Insert a citation referencing the article at point into the buffer from +which the selection process was started. + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a citation will accept it like @key{RET} +would. See also variable @code{reftex-highlight-selection}, @ref{Options +(Misc)}. + +@item m +Mark the current entry. When one or several entries are marked, +pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, +@key{RET} behaves like the @kbd{a} key. + +@item u +Unmark a marked entry. + +@item a +Accept all (marked) entries in the selection buffer and create a single +@code{\cite} macro referring to them. + +@item A +Accept all (marked) entries in the selection buffer and create a +separate @code{\cite} macro for each of it. + +@item e +Create a new BibTeX database file which contains all @i{marked} entries +in the selection buffer. If no entries are marked, all entries are +selected. + +@item E +Create a new BibTeX database file which contains all @i{unmarked} +entries in the selection buffer. If no entries are marked, all entries +are selected. + +@item @key{TAB} +Enter a citation key with completion. This may also be a key which does +not yet exist. + +@item . +Show insertion point in another window. This is the point from where you +called @code{reftex-citation}. + +@tablesubheading{Exiting} +@item q +Exit the selection process without inserting a citation into the +buffer. + +@tablesubheading{Updating the buffer} + +@item g +Start over with a new regular expression. The full database will be +rescanned with the new expression (see also @kbd{r}). + +@c FIXME: Should we use something else here? r is usually rescan! +@item r +Refine the current selection with another regular expression. This will +@emph{not} rescan the entire database, but just the already selected +entries. + +@end table + +@vindex reftex-select-bib-map +In order to define additional commands for this selection process, the +keymap @code{reftex-select-bib-map} may be used. + +@node Citation Styles, Citation Info, Creating Citations, Citations +@section Citation Styles +@cindex Citation styles +@cindex Citation styles, @code{natbib} +@cindex Citation styles, @code{harvard} +@cindex Citation styles, @code{chicago} +@cindex Citation styles, @code{jurabib} +@cindex @code{natbib}, citation style +@cindex @code{harvard}, citation style +@cindex @code{chicago}, citation style +@cindex @code{jurabib}, citation style + +@vindex reftex-cite-format +The standard LaTeX macro @code{\cite} works well with numeric or simple +key citations. To deal with the more complex task of author-year +citations as used in many natural sciences, a variety of packages has +been developed which define derived forms of the @code{\cite} macro. +@b{Ref@TeX{}} can be configured to produce these citation macros as well +by setting the variable @code{reftex-cite-format}. For the most +commonly used packages (@code{natbib}, @code{harvard}, @code{chicago}, +@code{jurabib}) this may be done from the menu, under +@code{Ref->Citation Styles}. Since there are usually several macros to +create the citations, executing @code{reftex-citation} (@kbd{C-c [}) +starts by prompting for the correct macro. For the Natbib style, this +looks like this: + +@example +SELECT A CITATION FORMAT + +[^M] \cite@{%l@} +[t] \citet@{%l@} +[T] \citet*@{%l@} +[p] \citep@{%l@} +[P] \citep*@{%l@} +[e] \citep[e.g.][]@{%l@} +[s] \citep[see][]@{%l@} +[a] \citeauthor@{%l@} +[A] \citeauthor*@{%l@} +[y] \citeyear@{%l@} +@end example + +@vindex reftex-cite-prompt-optional-args +If cite formats contain empty paris of square brackets, RefTeX can +will prompt for values of these optional arguments if you call the +@code{reftex-citation} command with a @kbd{C-u} prefix. +Following the most generic of these packages, @code{natbib}, the builtin +citation packages always accept the @kbd{t} key for a @emph{textual} +citation (like: @code{Jones et al. (1997) have shown...}) as well as +the @kbd{p} key for a parenthetical citation (like: @code{As shown +earlier (Jones et al, 1997)}). + +To make one of these styles the default, customize the variable +@code{reftex-cite-format} or put into @file{.emacs}: + +@lisp +(setq reftex-cite-format 'natbib) +@end lisp + +You can also use AUCTeX style files to automatically set the +citation style based on the @code{usepackage} commands in a given +document. @xref{Style Files}, for information on how to set up the style +files correctly. + +@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top +@section Citation Info +@cindex Displaying citations +@cindex Citations, displaying +@cindex Citation info +@cindex Viewing citations +@kindex C-c & +@kindex S-mouse-2 +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref + +When point is idle for more than @code{reftex-idle-time} seconds on the +argument of a @code{\cite} macro, the echo area will display some +information about the article cited there. Note that the information is +only displayed if the echo area is not occupied by a different message. + +@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database +entry corresponding to a @code{\cite} macro, or all citation locations +corresponding to a @code{\bibitem} or BibTeX database entry. +@xref{Viewing Cross-References}. + +@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations +@section Chapterbib and Bibunits +@cindex @code{chapterbib}, LaTeX package +@cindex @code{bibunits}, LaTeX package +@cindex Bibliographies, multiple + +@code{chapterbib} and @code{bibunits} are two LaTeX packages which +produce multiple bibliographies in a document. This is no problem for +@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database +files. If they do not, it is best to have each document part in a +separate file (as it is required for @code{chapterbib} anyway). Then +@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If +you have multiple bibliographies within a @emph{single file}, this may +or may not be the case. + +@node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations +@section Citations outside LaTeX +@cindex Citations outside LaTeX +@vindex reftex-default-bibliography + +The command @code{reftex-citation} can also be executed outside a LaTeX +buffer. This can be useful to reference articles in the mail buffer and +other documents. You should @emph{not} enter @code{reftex-mode} for +this, just execute the command. The list of BibTeX files will in this +case be taken from the variable @code{reftex-default-bibliography}. +Setting the variable @code{reftex-cite-format} to the symbol +@code{locally} does a decent job of putting all relevant information +about a citation directly into the buffer. Here is the lisp code to add +the @kbd{C-c [} binding to the mail buffer. It also provides a local +binding for @code{reftex-cite-format}. + +@lisp +(add-hook 'mail-setup-hook + (lambda () (define-key mail-mode-map "\C-c[" + (lambda () + (interactive) + (let ((reftex-cite-format 'locally)) + (reftex-citation)))))) +@end lisp + +@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations +@section Database Subsets +@cindex BibTeX database subsets +@findex reftex-create-bibtex-file + +@b{Ref@TeX{}} offers two ways to create a new BibTeX database file. + +The first option produces a file which contains only the entries +actually referenced in the current document. This can be useful if +the database in only meant for a single document and you want to clean +it of old and unused ballast. It can also be useful while writing a +document together with collaborators, in order to avoid sending around +the entire (possibly very large) database. To create the file, use +@kbd{M-x reftex-create-bibtex-file}, also available from the menu +under @code{Ref->Global Actions->Create Bibtex File}. The command will +prompt for a BibTeX file name and write the extracted entries to that +file. + +The second option makes use of the selection process started by the +command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a +regular expression to select entries, and lists them in a formatted +selection buffer. After pressing the @kbd{e} key (mnemonics: Export), +the command will prompt for the name of a new BibTeX file and write +the selected entries to that file. You can also first mark some +entries in the selection buffer with the @kbd{m} key and then export +either the @i{marked} entries (with the @kbd{e} key) or the +@i{unmarked} entries (with the @kbd{E} key). + +@node Index Support, Viewing Cross-References, Citations, Top +@chapter Index Support +@cindex Index Support +@cindex @code{\index} + +LaTeX has builtin support for creating an Index. The LaTeX core +supports two different indices, the standard index and a glossary. With +the help of special LaTeX packages (@file{multind.sty} or +@file{index.sty}), any number of indices can be supported. + +Index entries are created with the @code{\index@{@var{entry}@}} macro. +All entries defined in a document are written out to the @file{.aux} +file. A separate tool must be used to convert this information into a +nicely formatted index. Tools used with LaTeX include @code{MakeIndex} +and @code{xindy}. + +Indexing is a very difficult task. It must follow strict conventions to +make the index consistent and complete. There are basically two +approaches one can follow, and both have their merits. + +@enumerate +@item +Part of the indexing should already be done with the markup. The +document structure should be reflected in the index, so when starting +new sections, the basic topics of the section should be indexed. If the +document contains definitions, theorems or the like, these should all +correspond to appropriate index entries. This part of the index can +very well be developed along with the document. Often it is worthwhile +to define special purpose macros which define an item and at the same +time make an index entry, possibly with special formatting to make the +reference page in the index bold or underlined. To make @b{Ref@TeX{}} +support for indexing possible, these special macros must be added to +@b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}). + +@item +The rest of the index is often just a collection of where in the +document certain words or phrases are being used. This part is +difficult to develop along with the document, because consistent entries +for each occurrence are needed and are best selected when the document +is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file} +which collects phrases and helps indexing the phrases globally. +@end enumerate + +Before you start, you need to make sure that @b{Ref@TeX{}} knows about +the index style being used in the current document. @b{Ref@TeX{}} has +builtin support for the default @code{\index} and @code{\glossary} +macros. Other LaTeX packages, like the @file{multind} or @file{index} +package, redefine the @code{\index} macro to have an additional +argument, and @b{Ref@TeX{}} needs to be configured for those. A +sufficiently new version of AUCTeX (9.10c or later) will do this +automatically. If you really don't use AUCTeX (you should!), this +configuration needs to be done by hand with the menu (@code{Ref->Index +Style}), or globally for all your documents with + +@lisp +(setq reftex-index-macros '(multind)) @r{or} +(setq reftex-index-macros '(index)) +@end lisp + +@menu +* Creating Index Entries:: Macros and completion of entries. +* The Index Phrases File:: A special file for global indexing. +* Displaying and Editing the Index:: The index editor. +* Builtin Index Macros:: The index macros RefTeX knows about. +* Defining Index Macros:: ... and macros it doesn't. +@end menu + +@node Creating Index Entries, The Index Phrases File, , Index Support +@section Creating Index Entries +@cindex Creating index entries +@cindex Index entries, creating +@kindex C-c < +@findex reftex-index +@kindex C-c / +@findex reftex-index-selection-or-word + +In order to index the current selection or the word at the cursor press +@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the +selection or word @samp{@var{word}} to be replaced with +@samp{\index@{@var{word}@}@var{word}}. The macro which is used +(@code{\index} by default) can be configured with the variable +@code{reftex-index-default-macro}. When the command is called with a +prefix argument (@kbd{C-u C-c /}), you get a chance to edit the +generated index entry. Use this to change the case of the word or to +make the entry a subentry, for example by entering +@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes +(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. +When there is nothing selected and no word at point, this command will +just call @code{reftex-index}, described below. + +In order to create a general index entry, press @kbd{C-c <} +(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the +available index macros and for its arguments. Completion will be +available for the index entry and, if applicable, the index tag. The +index tag is a string identifying one of multiple indices. With the +@file{multind} and @file{index} packages, this tag is the first argument +to the redefined @code{\index} macro. + +@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support +@section The Index Phrases File +@cindex Index phrase file +@cindex Phrase file +@kindex C-c | +@findex reftex-index-visit-phrases-buffer +@cindex Macro definition lines, in phrase buffer + +@b{Ref@TeX{}} maintains a file in which phrases can be collected for +later indexing. The file is located in the same directory as the master +file of the document and has the extension @file{.rip} (@b{R}eftex +@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c +|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it +is initialized by inserting a file header which contains the definition +of the available index macros. This list is initialized from +@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can +edit the header as needed, but if you define new LaTeX indexing macros, +don't forget to add them to @code{reftex-index-macros} as well. Here is +a phrase file header example: + +@example +% -*- mode: reftex-index-phrases -*- +% Key Macro Format Repeat +%---------------------------------------------------------- +>>>INDEX_MACRO_DEFINITION: i \index@{%s@} t +>>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil +>>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t +>>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil +%---------------------------------------------------------- +@end example + +The macro definition lines consist of a unique letter identifying a +macro, a format string and the @var{repeat} flag, all separated by +@key{TAB}. The format string shows how the macro is to be applied, the +@samp{%s} will be replaced with the index entry. The repeat flag +indicates if @var{word} is indexed by the macro as +@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as +@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the +above example it is assumed that the macro @code{\index*@{@var{word}@}} +already typesets its argument in the text, so that it is unnecessary to +repeat @var{word} outside the macro. + +@menu +* Collecting Phrases:: Collecting from document or external. +* Consistency Checks:: Check for duplicates etc. +* Global Indexing:: The interactive indexing process. +@end menu + +@node Collecting Phrases, Consistency Checks, , The Index Phrases File +@subsection Collecting Phrases +@cindex Collecting index phrases +@cindex Index phrases, collection +@cindex Phrases, collecting + +Phrases for indexing can be collected while writing the document. The +command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) +copies the current selection (if active) or the word near point into the +phrases buffer. It then selects this buffer, so that the phrase line +can be edited. To return to the LaTeX document, press @kbd{C-c C-c} +(@code{reftex-index-phrases-save-and-return}). + +You can also prepare the list of index phrases in a different way and +copy it into the phrases file. For example you might want to start from +a word list of the document and remove all words which should not be +indexed. + +The phrase lines in the phrase buffer must have a specific format. +@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper +format. A phrase line looks like this: + +@example +[@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...] +@end example + +@code{<TABs>} stands for white space containing at least one @key{TAB}. +@var{key} must be at the start of the line and is the character +identifying one of the macros defined in the file header. It is +optional - when omitted, the first macro definition line in the file +will be used for this phrase. The @var{phrase} is the phrase to be +searched for when indexing. It may contain several words separated by +spaces. By default the search phrase is also the text entered as +argument of the index macro. If you want the index entry to be +different from the search phrase, enter another @key{TAB} and the index +argument @var{arg}. If you want to have each match produce several +index entries, separate the different index arguments with @samp{ && +}@footnote{@samp{&&} with optional spaces, see +@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be +able to choose at each match between several different index arguments, +separate them with @samp{ || }@footnote{@samp{||} with optional spaces, +see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an +example: + +@example +%-------------------------------------------------------------------- +I Sun +i Planet Planets +i Vega Stars!Vega + Jupiter Planets!Jupiter +i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars +i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto +@end example + + +So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while +@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. +@samp{Vega} will be indexed as a subitem of @samp{Stars}. The +@samp{Jupiter} line will also use the @samp{i} macro as it was the first +macro definition in the file header (see above example). At each +occurrence of @samp{Mars} you will be able choose between indexing it as +a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. +Finally, every occurrence of @samp{Pluto} will be indexed as +@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} +and will therefore create two different index entries. + +@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File +@subsection Consistency Checks +@cindex Index phrases, consistency checks +@cindex Phrases, consistency checks +@cindex Consistency check for index phrases + +@kindex C-c C-s +Before indexing the phrases in the phrases buffer, they should be +checked carefully for consistency. A first step is to sort the phrases +alphabetically - this is done with the command @kbd{C-c C-s} +(@code{reftex-index-sort-phrases}). It will sort all phrases in the +buffer alphabetically by search phrase. If you want to group certain +phrases and only sort within the groups, insert empty lines between the +groups. Sorting will only change the sequence of phrases within each +group (see the variable @code{reftex-index-phrases-sort-in-blocks}). + +@kindex C-c C-i +A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) +which lists information about the phrase at point, including an example +of how the index entry will look like and the number of expected matches +in the document. + +@kindex C-c C-t +Another important check is to find out if there are double or +overlapping entries in the buffer. For example if you are first +searching and indexing @samp{Mars} and then @samp{Planet Mars}, the +second phrase will not match because of the index macro inserted before +@samp{Mars} earlier. The command @kbd{C-c C-t} +(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in +the buffer which is either duplicate or a subphrase of another phrase. +In order to check the whole buffer like this, start at the beginning and +execute this command repeatedly. + +@node Global Indexing, , Consistency Checks, The Index Phrases File +@subsection Global Indexing +@cindex Global indexing +@cindex Indexing, global +@cindex Indexing, from @file{phrases} buffer + +Once the index phrases have been collected and organized, you are set +for global indexing. I recommend to do this only on an otherwise +finished document. Global indexing starts from the phrases buffer. +There are several commands which start indexing: @kbd{C-c C-x} acts on +the current phrase line, @kbd{C-c C-r} on all lines in the current +region and @kbd{C-c C-a} on all phrase lines in the buffer. It is +probably good to do indexing in small chunks since your concentration +may not last long enough to do everything in one go. + +@b{Ref@TeX{}} will start at the first phrase line and search the phrase +globally in the whole document. At each match it will stop, compute the +replacement string and offer you the following choices@footnote{Windows +users: Restrict yourself to the described keys during indexing. Pressing +@key{Help} at the indexing prompt can apparently hang Emacs.}: + +@table @kbd +@item y +Replace this match with the proposed string. +@item n +Skip this match. +@item ! +Replace this and all further matches in this file. +@item q +Skip this match, start with next file. +@item Q +Skip this match, start with next phrase. +@item o +Select a different indexing macro for this match. +@item 1-9 +Select one of multiple index keys (those separated with @samp{||}). +@item e +Edit the replacement text. +@item C-r +Recursive edit. Use @kbd{C-M-c} to return to the indexing process. +@item s +Save this buffer and ask again about the current match. +@item S +Save all document buffers and ask again about the current match. +@item C-g +Abort the indexing process. +@end table + +The @samp{Find and Index in Document} menu in the phrases buffer also +lists a few options for the indexing process. The options have +associated customization variables to set the defaults (@pxref{Options +(Index Support)}). Here is a short explanation of what the options do: + +@table @i +@item Match Whole Words +When searching for index phrases, make sure whole words are matched. +This should probably always be on. +@item Case Sensitive Search +Search case sensitively for phrases. I recommend to have this setting +off, in order to match the capitalized words at the beginning of a +sentence, and even typos. You can always say @emph{no} at a match you +do not like. +@item Wrap Long Lines +Inserting index macros increases the line length. Turn this option on +to allow @b{Ref@TeX{}} to wrap long lines. +@item Skip Indexed Matches +When this is on, @b{Ref@TeX{}} will at each match try to figure out if +this match is already indexed. A match is considered indexed if it is +either the argument of an index macro, or if an index macro is directly +(without whitespace separation) before or after the match. Index macros +are those configured in @code{reftex-index-macros}. Intended for +re-indexing a documents after changes have been made. +@end table + +Even though indexing should be the last thing you do to a document, you +are bound to make changes afterwards. Indexing then has to be applied +to the changed regions. The command +@code{reftex-index-phrases-apply-to-region} is designed for this +purpose. When called from a LaTeX document with active region, it will +apply @code{reftex-index-all-phrases} to the current region. + +@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support +@section Displaying and Editing the Index +@cindex Displaying the Index +@cindex Editing the Index +@cindex Index entries, creating +@cindex Index, displaying +@cindex Index, editing +@kindex C-c > +@findex reftex-display-index + +In order to compile and display the index, press @kbd{C-c >}. If the +document uses multiple indices, @b{Ref@TeX{}} will ask you to select +one. Then, all index entries will be sorted alphabetically and +displayed in a special buffer, the @file{*Index*} buffer. From that +buffer you can check and edit each entry. + +The index can be restricted to the current section or the region. Then +only entries in that part of the document will go into the compiled +index. To restrict to the current section, use a numeric prefix +@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current +region, make the region active and use a numeric prefix @samp{3} (press +@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the +restriction can be moved from one section to the next by pressing the +@kbd{<} and @kbd{>} keys. + +One caveat: @b{Ref@TeX{}} finds the definition point of an index entry +by searching near the buffer position where it had found to macro during +scanning. If you have several identical index entries in the same +buffer and significant changes have shifted the entries around, you must +rescan the buffer to ensure the correspondence between the +@file{*Index*} buffer and the definition locations. It is therefore +advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) +frequently while editing the index from the @file{*Index*} +buffer. + +@kindex ? +Here is a list of special commands available in the @file{*Index*} buffer. A +summary of this information is always available by pressing +@kbd{?}. + +@table @kbd +@tablesubheading{General} +@item ? +Display a summary of commands. + +@item 0-9, - +Prefix argument. + +@tablesubheading{Moving around} +@item ! A..Z +Pressing any capital letter will jump to the corresponding section in +the @file{*Index*} buffer. The exclamation mark is special and jumps to +the first entries alphabetically sorted below @samp{A}. These are +usually non-alphanumeric characters. +@item n +Go to next entry. +@item p +Go to previous entry. + +@tablesubheading{Access to document locations} +@item @key{SPC} +Show the place in the document where this index entry is defined. + +@item @key{TAB} +Go to the definition of the current index entry in another +window. + +@item @key{RET} +Go to the definition of the current index entry and hide the +@file{*Index*} buffer window. + +@item f +@vindex reftex-index-follow-mode +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always show the location corresponding to the line in the @file{*Index*} +buffer at point. This is similar to pressing @key{SPC} after each +cursor motion. The default for this flag can be set with the variable +@code{reftex-index-follow-mode}. Note that only context in files +already visited is shown. @b{Ref@TeX{}} will not visit a file just for +follow mode. See, however, the variable +@code{reftex-revisit-to-follow}. + +@tablesubheading{Entry editing} +@item e +Edit the current index entry. In the minibuffer, you can edit the +index macro which defines this entry. + +@item C-k +Kill the index entry. Currently not implemented because I don't know +how to implement an @code{undo} function for this. + +@item * +Edit the @var{key} part of the entry. This is the initial part of the +entry which determines the location of the entry in the index. + +@item | +Edit the @var{attribute} part of the entry. This is the part after the +vertical bar. With @code{MakeIndex}, this part is an encapsulating +macro. With @code{xindy}, it is called @emph{attribute} and is a +property of the index entry that can lead to special formatting. When +called with @kbd{C-u} prefix, kill the entire @var{attribute} +part. + +@item @@ +Edit the @var{visual} part of the entry. This is the part after the +@samp{@@} which is used by @code{MakeIndex} to change the visual +appearance of the entry in the index. When called with @kbd{C-u} +prefix, kill the entire @var{visual} part. + +@item ( +Toggle the beginning of page range property @samp{|(} of the +entry. + +@item ) +Toggle the end of page range property @samp{|)} of the entry. + +@item _ +Make the current entry a subentry. This command will prompt for the +superordinate entry and insert it. + +@item ^ +Remove the highest superordinate entry. If the current entry is a +subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy +(@samp{bbb!ccc}). + +@tablesubheading{Exiting} +@item q +Hide the @file{*Index*} buffer. + +@item k +Kill the @file{*Index*} buffer. + +@item C-c = +Switch to the Table of Contents buffer of this document. + +@tablesubheading{Controlling what gets displayed} +@item c +@vindex reftex-index-include-context +Toggle the display of short context in the @file{*Index*} buffer. The +default for this flag can be set with the variable +@code{reftex-index-include-context}. + +@item @} +Restrict the index to a single document section. The corresponding +section number will be displayed in the @code{R<>} indicator in the +mode line and in the header of the @file{*Index*} buffer. + +@item @{ +Widen the index to contain all entries of the document. + +@item < +When the index is currently restricted, move the restriction to the +previous section. + +@item > +When the index is currently restricted, move the restriction to the +next section. + +@tablesubheading{Updating the buffer} +@item g +Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the +document. However, it sorts the entries again, so that edited entries +will move to the correct position. + +@item r +@vindex reftex-enable-partial-scans +Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When +@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this +location is defined in, not the entire document. + +@item C-u r +Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} +buffer. + +@item s +Switch to a different index (for documents with multiple +indices). +@end table + + +@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support +@section Builtin Index Macros +@cindex Builtin index macros +@cindex Index macros, builtin +@vindex reftex-index-macros +@cindex @code{multind}, LaTeX package +@cindex @code{index}, LaTeX package +@cindex LaTeX packages, @code{multind} +@cindex LaTeX packages, @code{index} + +@b{Ref@TeX{}} by default recognizes the @code{\index} and +@code{\glossary} macros which are defined in the LaTeX core. It has +also builtin support for the re-implementations of @code{\index} +in the @file{multind} and @file{index} packages. However, since +the different definitions of the @code{\index} macro are incompatible, +you will have to explicitly specify the index style used. +@xref{Creating Index Entries}, for information on how to do that. + +@node Defining Index Macros, , Builtin Index Macros, Index Support +@section Defining Index Macros +@cindex Defining Index Macros +@cindex Index macros, defining +@vindex reftex-index-macros + +When writing a document with an index you will probably define +additional macros which make entries into the index. +Let's look at an example. + +@example +\newcommand@{\ix@}[1]@{#1\index@{#1@}@} +\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} +\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} +@end example + +The first macro @code{\ix} typesets its argument in the text and places +it into the index. The second macro @code{\nindex} typesets its +argument in the text and places it into a separate index with the tag +@samp{name}@footnote{We are using the syntax of the @file{index} package +here.}. The last macro also places its argument into the index, but as +subitems under the main index entry @samp{Astronomical Objects}. Here +is how to make @b{Ref@TeX{}} recognize and correctly interpret these +macros, first with Emacs Lisp. + +@lisp +(setq reftex-index-macros + '(("\\ix@{*@}" "idx" ?x "" nil nil) + ("\\nindex@{*@}" "name" ?n "" nil nil) + ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) +@end lisp + +Note that the index tag is @samp{idx} for the main index, and +@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved +for the default index and for the glossary. + +The character arguments @code{?x}, @code{?n}, and @code{?o} are for +quick identification of these macros when @b{Ref@TeX{}} inserts new +index entries with @code{reftex-index}. These codes need to be +unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the +@code{\index}, @code{\index*}, and @code{\glossary} macros, +respectively. + +The following string is empty unless your macro adds a superordinate +entry to the index key - this is the case for the @code{\astobj} macro. + +The next entry can be a hook function to exclude certain matches, it +almost always can be @code{nil}. + +The final element in the list indicates if the text being indexed needs +to be repeated outside the macro. For the normal index macros, this +should be @code{t}. Only if the macro typesets the entry in the text +(like @code{\ix} and @code{\nindex} in the example do), this should be +@code{nil}. + +To do the same thing with customize, you need to fill in the templates +like this: + +@example +Repeat: +[INS] [DEL] List: + Macro with args: \ix@{*@} + Index Tag : [Value Menu] String: idx + Access Key : x + Key Prefix : + Exclusion hook : nil + Repeat Outside : [Toggle] off (nil) +[INS] [DEL] List: + Macro with args: \nindex@{*@} + Index Tag : [Value Menu] String: name + Access Key : n + Key Prefix : + Exclusion hook : nil + Repeat Outside : [Toggle] off (nil) +[INS] [DEL] List: + Macro with args: \astobj@{*@} + Index Tag : [Value Menu] String: idx + Access Key : o + Key Prefix : Astronomical Objects! + Exclusion hook : nil + Repeat Outside : [Toggle] on (non-nil) +[INS] +@end example + +With the macro @code{\ix} defined, you may want to change the default +macro used for indexing a text phrase (@pxref{Creating Index Entries}). +This would be done like this + +@lisp +(setq reftex-index-default-macro '(?x "idx")) +@end lisp + +which specifies that the macro identified with the character @code{?x} (the +@code{\ix} macro) should be used for indexing phrases and words already +in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). +The index tag is "idx". + +@node Viewing Cross-References, RefTeXs Menu, Index Support, Top +@chapter Viewing Cross--References +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref +@kindex C-c & +@kindex S-mouse-2 + +@b{Ref@TeX{}} can display cross--referencing information. This means, +if two document locations are linked, @b{Ref@TeX{}} can display the +matching location(s) in another window. The @code{\label} and @code{\ref} +macros are one way of establishing such a link. Also, a @code{\cite} +macro is linked to the corresponding @code{\bibitem} macro or a BibTeX +database entry. + +The feature is invoked by pressing @kbd{C-c &} +(@code{reftex-view-crossref}) while point is on the @var{key} argument +of a macro involved in cross--referencing. You can also click with +@kbd{S-mouse-2} on the macro argument. Here is what will happen for +individual classes of macros: + +@table @asis + +@item @code{\ref} +@cindex @code{\ref} +Display the corresponding label definition. All usual +variants@footnote{all macros that start with @samp{ref} or end with +@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for +cross--reference display. This works also for labels defined in an +external document when the current document refers to them through the +@code{xr} interface (@pxref{xr (LaTeX package)}). + +@item @code{\label} +@cindex @code{\label} +@vindex reftex-label-alist +Display a document location which references this label. Pressing +@kbd{C-c &} several times moves through the entire document and finds +all locations. Not only the @code{\label} macro but also other macros +with label arguments (as configured with @code{reftex-label-alist}) are +active for cross--reference display. + +@item @code{\cite} +@cindex @code{\cite} +Display the corresponding BibTeX database entry or @code{\bibitem}. +All usual variants@footnote{all macros that either start or end with +@samp{cite}} of the @code{\cite} macro are active for cross--reference +display. + +@item @code{\bibitem} +@cindex @code{\bibitem} +Display a document location which cites this article. Pressing +@kbd{C-c &} several times moves through the entire document and finds +all locations. + +@item BibTeX +@cindex BibTeX buffer, viewing cite locations from +@cindex Viewing cite locations from BibTeX buffer +@kbd{C-c &} is also active in BibTeX buffers. All locations in a +document where the database entry at point is cited will be displayed. +On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to +the document you want to search. Subsequent calls will use the same +document, until you break this link with a prefix argument to @kbd{C-c +&}. + +@item @code{\index} +@cindex @code{\index} +Display other locations in the document which are marked by an index +macro with the same key argument. Along with the standard @code{\index} +and @code{\glossary} macros, all macros configured in +@code{reftex-index-macros} will be recognized. +@end table + +@vindex reftex-view-crossref-extra +While the display of cross referencing information for the above +mentioned macros is hard--coded, you can configure additional relations +in the variable @code{reftex-view-crossref-extra}. + +@iftex +@chapter All the Rest +@end iftex + +@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top +@section @b{Ref@TeX{}}'s Menu +@cindex RefTeXs Menu +@cindex Menu, in the menu bar + +@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems +which support this. From this menu you can access all of +@b{Ref@TeX{}}'s commands and a few of its options. There is also a +@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s +entire set of options. + +@node Key Bindings, Faces, RefTeXs Menu, Top +@section Default Key Bindings +@cindex Key Bindings, summary + +Here is a summary of the available key bindings. + +@kindex C-c = +@kindex C-c - +@kindex C-c ( +@kindex C-c ) +@kindex C-c [ +@kindex C-c & +@kindex S-mouse-2 +@kindex C-c / +@kindex C-c \ +@kindex C-c | +@kindex C-c < +@kindex C-c > +@example +@kbd{C-c =} @code{reftex-toc} +@kbd{C-c -} @code{reftex-toc-recenter} +@kbd{C-c (} @code{reftex-label} +@kbd{C-c )} @code{reftex-reference} +@kbd{C-c [} @code{reftex-citation} +@kbd{C-c &} @code{reftex-view-crossref} +@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} +@kbd{C-c /} @code{reftex-index-selection-or-word} +@kbd{C-c \} @code{reftex-index-phrase-selection-or-word} +@kbd{C-c |} @code{reftex-index-visit-phrases-buffer} +@kbd{C-c <} @code{reftex-index} +@kbd{C-c >} @code{reftex-display-index} +@end example + +Note that the @kbd{S-mouse-2} binding is only provided if this key is +not already used by some other package. @b{Ref@TeX{}} will not override an +existing binding to @kbd{S-mouse-2}. + +Personally, I also bind some functions in the users @kbd{C-c} map for +easier access. + +@c FIXME: Do we need bindings for the Index macros here as well? +@c C-c i C-c I or so???? +@c How about key bindings for reftex-reset-mode and reftex-parse-document? +@kindex C-c t +@kindex C-c l +@kindex C-c r +@kindex C-c c +@kindex C-c v +@kindex C-c s +@kindex C-c g +@example +@kbd{C-c t} @code{reftex-toc} +@kbd{C-c l} @code{reftex-label} +@kbd{C-c r} @code{reftex-reference} +@kbd{C-c c} @code{reftex-citation} +@kbd{C-c v} @code{reftex-view-crossref} +@kbd{C-c s} @code{reftex-search-document} +@kbd{C-c g} @code{reftex-grep-document} +@end example + +@noindent These keys are reserved for the user, so I cannot bind them by +default. If you want to have these key bindings available, set in your +@file{.emacs} file: + +@vindex reftex-extra-bindings +@lisp +(setq reftex-extra-bindings t) +@end lisp + +@vindex reftex-load-hook +Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook +@code{reftex-load-hook}. For information on the keymaps +which should be used to add keys, see @ref{Keymaps and Hooks}. + +@node Faces, AUCTeX, Key Bindings, Top +@section Faces +@cindex Faces + +@b{Ref@TeX{}} uses faces when available to structure the selection and +table of contents buffers. It does not create its own faces, but uses +the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will +use faces only when @code{font-lock} is loaded. This seems to be +reasonable because people who like faces will very likely have it +loaded. If you wish to turn off fontification or change the involved +faces, see @ref{Options (Fontification)}. + +@node Multifile Documents, Language Support, AUCTeX, Top +@section Multifile Documents +@cindex Multifile documents +@cindex Documents, spread over files + +The following is relevant when working with documents spread over many +files: + +@itemize @bullet +@item +@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of +several (multifile) documents at the same time without conflicts. +@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and +@code{query-replace} on all files which are part of a multifile +document. + +@item +@vindex tex-main-file +@vindex TeX-master +All files belonging to a multifile document should define a File +Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the +standard Emacs LaTeX mode) containing the name of the master file. For +example, to set the file variable @code{TeX-master}, include something +like the following at the end of each TeX file: + +@example +%%% Local Variables: *** +%%% mode:latex *** +%%% TeX-master: "thesis.tex" *** +%%% End: *** +@end example + +AUCTeX with the setting + +@lisp +(setq-default TeX-master nil) +@end lisp + +will actually ask you for each new file about the master file and insert +this comment automatically. For more details see the documentation of +the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the +documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, +The GNU Emacs Manual}) and the Emacs documentation on File Variables +(@pxref{File Variables,,,emacs, The GNU Emacs Manual}). + +@item +The context of a label definition must be found in the same file as the +label itself in order to be processed correctly by @b{Ref@TeX{}}. The only +exception is that section labels referring to a section statement +outside the current file can still use that section title as +context. +@end itemize + +@node Language Support, Finding Files, Multifile Documents, Top +@section Language Support +@cindex Language support + +Some parts of @b{Ref@TeX{}} are language dependent. The default +settings work well for English. If you are writing in a different +language, the following hints may be useful: + +@itemize @bullet +@item +@vindex reftex-derive-label-parameters +@vindex reftex-abbrev-parameters +The mechanism to derive a label from context includes the abbreviation +of words and omission of unimportant words. These mechanisms may have +to be changed for other languages. See the variables +@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. + +@item +@vindex reftex-translate-to-ascii-function +@vindex reftex-label-illegal-re +Also, when a label is derived from context, @b{Ref@TeX{}} clears the +context string from non-ASCII characters in order to make a valid label. +If there should ever be a version of @TeX{} which allows extended +characters @emph{in labels}, then we will have to look at the +variables @code{reftex-translate-to-ascii-function} and +@code{reftex-label-illegal-re}. + +@item +When a label is referenced, @b{Ref@TeX{}} looks at the word before point +to guess which label type is required. These @emph{magic words} are +different in every language. For an example of how to add magic words, +see @ref{Adding Magic Words}. + +@vindex reftex-multiref-punctuation +@vindex reftex-cite-punctuation +@item +@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and +for the author list in citations. Some of this may be language +dependent. See the variables @code{reftex-multiref-punctuation} and +@code{reftex-cite-punctuation}. +@end itemize + +@node Finding Files, Optimizations, Language Support, Top +@section Finding Files +@cindex Finding files + +In order to find files included in a document via @code{\input} or +@code{\include}, @b{Ref@TeX{}} searches all directories specified in the +environment variable @code{TEXINPUTS}. Similarly, it will search the +path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for +BibTeX database files. + +When searching, @b{Ref@TeX{}} will also expand recursive path +definitions (directories ending in @samp{//} or @samp{!!}). But it will +only search and expand directories @emph{explicitly} given in these +variables. This may cause problems under the following circumstances: + +@itemize @bullet +@item +Most TeX system have a default search path for both TeX files and BibTeX +files which is defined in some setup file. Usually this default path is +for system files which @b{Ref@TeX{}} does not need to see. But if your +document needs TeX files or BibTeX database files in a directory only +given in the default search path, @b{Ref@TeX{}} will fail to find them. +@item +Some TeX systems do not use environment variables at all in order to +specify the search path. Both default and user search path are then +defined in setup files. +@end itemize + +@noindent +There are three ways to solve this problem: + +@itemize @bullet +@item +Specify all relevant directories explicitly in the environment +variables. If for some reason you don't want to mess with the default +variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own +variables and configure @b{Ref@TeX{}} to use them instead: + +@lisp +(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) +(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) +@end lisp + +@item +Specify the full search path directly in @b{Ref@TeX{}}'s variables. + +@lisp +(setq reftex-texpath-environment-variables + '("./inp:/home/cd/tex//:/usr/local/tex//")) +(setq reftex-bibpath-environment-variables + '("/home/cd/tex/lit/")) +@end lisp + +@item +Some TeX systems provide stand--alone programs to do the file search just +like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the +@code{kpathsearch} library which provides the command @code{kpsewhich} +to search for files. @b{Ref@TeX{}} can be configured to use this +program. Note that the exact syntax of the @code{kpsewhich} +command depends upon the version of that program. + +@lisp +(setq reftex-use-external-file-finders t) +(setq reftex-external-file-finders + '(("tex" . "kpsewhich -format=.tex %f") + ("bib" . "kpsewhich -format=.bib %f"))) +@end lisp +@end itemize + +@cindex Noweb files +@vindex reftex-file-extensions +@vindex TeX-file-extensions +Some people like to use RefTeX with noweb files, which usually have the +extension @file{.nw}. In order to deal with such files, the new +extension must be added to the list of valid extensions in the variable +@code{reftex-file-extensions}. When working with AUCTeX as major mode, +the new extension must also be known to AUCTeX via the variable +@code{TeX-file-extension}. For example: + +@lisp +(setq reftex-file-extensions + '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) +(setq TeX-file-extensions + '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) +@end lisp + +@node Optimizations, Problems and Work-Arounds, Finding Files, Top +@section Optimizations +@cindex Optimizations + +@b{Note added 2002. Computers have gotten a lot faster, so most of the +optimizations discussed below will not be necessary on new machines. I +am leaving this stuff in the manual for people who want to write thick +books, where some of it still might be useful.} + +Implementing the principle of least surprises, the default settings of +@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, +when using @b{Ref@TeX{}} for a large project and/or on a small computer, +there are ways to improve speed or memory usage. + +@itemize @bullet +@item +@b{Removing Lookup Buffers}@* +@cindex Removing lookup buffers +@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX +database files for lookup purposes. These buffers are kept, so that +subsequent use of the same files is fast. If you can't afford keeping +these buffers around, and if you can live with a speed penalty, try + +@vindex reftex-keep-temporary-buffers +@lisp +(setq reftex-keep-temporary-buffers nil) +@end lisp + +@item +@b{Partial Document Scans}@* +@cindex Partial documents scans +@cindex Document scanning, partial +A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} +(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), +@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c +=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates +re-parsing of the entire document in order to update the parsing +information. For a large document this can be unnecessary, in +particular if only one file has changed. @b{Ref@TeX{}} can be configured +to do partial scans instead of full ones. @kbd{C-u} re-parsing then +does apply only to the current buffer and files included from it. +Likewise, the @kbd{r} key in both the label selection buffer and the +table-of-contents buffer will only prompt scanning of the file in which +the label or section macro near the cursor was defined. Re-parsing of +the entire document is still available by using @kbd{C-u C-u} as a +prefix, or the capital @kbd{R} key in the menus. To use this feature, +try + +@vindex reftex-enable-partial-scans +@lisp +(setq reftex-enable-partial-scans t) +@end lisp + +@item +@b{Saving Parser Information}@* +@cindex Saving parser information +@cindex Parse information, saving to a file +@vindex reftex-parse-file-extension +Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full +scan, when you start working with a document. To avoid this, parsing +information can be stored in a file. The file @file{MASTER.rel} is used +for storing information about a document with master file +@file{MASTER.tex}. It is written automatically when you kill a buffer +in @code{reftex-mode} or when you exit Emacs. The information is +restored when you begin working with a document in a new editing +session. To use this feature, put into @file{.emacs}: + +@vindex reftex-save-parse-info +@lisp +(setq reftex-save-parse-info t) +@end lisp + +@item +@b{Identifying label types by prefix}@* +@cindex Parse information, saving to a file +@vindex reftex-trust-label-prefix +@b{Ref@TeX{}} normally parses around each label to check in which +environment this label is located, in order to assign a label type to +the label. If your document contains thousands of labels, document +parsing will take considerable time. If you have been using label prefixes +like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the +label type directly from the prefix, without additional parsing. This +will be faster and also allow labels to end up in the correct category +if for some reason it is not possible to derive the correct type from +context. For example, to enable this feature for footnote and +equation labels, use + +@lisp +(setq reftex-trust-label-prefix '("fn:" "eq:")) +@end lisp + +@item +@b{Automatic Document Scans}@* +@cindex Automatic document scans +@cindex Document scanning, automatic +At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the +document. If this gets into your way, it can be turned off with + +@vindex reftex-allow-automatic-rescan +@lisp +(setq reftex-allow-automatic-rescan nil) +@end lisp + +@b{Ref@TeX{}} will then occasionally annotate new labels in the selection +buffer, saying that their position in the label list in uncertain. A +manual document scan will fix this. + +@item +@b{Multiple Selection Buffers}@* +@cindex Multiple selection buffers +@cindex Selection buffers, multiple +Normally, the selection buffer @file{*RefTeX Select*} is re-created for +every selection process. In documents with very many labels this can +take several seconds. @b{Ref@TeX{}} provides an option to create a +separate selection buffer for each label type and to keep this buffer +from one selection to the next. These buffers are updated automatically +only when a new label has been added in the buffers category with +@code{reftex-label}. Updating the buffer takes as long as recreating it +- so the time saving is limited to cases where no new labels of that +category have been added. To turn on this feature, use + +@vindex reftex-use-multiple-selection-buffers +@lisp +(setq reftex-use-multiple-selection-buffers t) +@end lisp + +@noindent +@cindex Selection buffers, updating +You can also inhibit the automatic updating entirely. Then the +selection buffer will always pop up very fast, but may not contain the +most recently defined labels. You can always update the buffer by hand, +with the @kbd{g} key. To get this behavior, use instead + +@vindex reftex-auto-update-selection-buffers +@lisp +(setq reftex-use-multiple-selection-buffers t + reftex-auto-update-selection-buffers nil) +@end lisp +@end itemize + +@need 2000 +@noindent +@b{As a summary}, here are the settings I recommend for heavy use of +@b{Ref@TeX{}} with large documents: + +@lisp +@group +(setq reftex-enable-partial-scans t + reftex-save-parse-info t + reftex-use-multiple-selection-buffers t) +@end group +@end lisp + +@node AUCTeX, Multifile Documents, Faces, Top +@section AUC@TeX{} +@cindex @code{AUCTeX}, Emacs package +@cindex Emacs packages, @code{AUCTeX} + +AUCTeX is without doubt the best major mode for editing TeX and LaTeX +files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). +If AUCTeX is not part of your Emacs distribution, you can get +it@footnote{XEmacs 21.x users may want to install the corresponding +XEmacs package.} by ftp from the @value{AUCTEXSITE}. + +@menu +* AUCTeX-RefTeX Interface:: How both packages work together +* Style Files:: AUCTeX's style files can support RefTeX +* Bib-Cite:: Hypertext reading of a document +@end menu + +@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX +@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface + +@b{Ref@TeX{}} contains code to interface with AUCTeX. When this +interface is turned on, both packages will interact closely. Instead of +using @b{Ref@TeX{}}'s commands directly, you can then also use them +indirectly as part of the AUCTeX +environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be +needed for all of this to work. Parts of it work also with earlier +versions.}. The interface is turned on with + +@lisp +(setq reftex-plug-into-AUCTeX t) +@end lisp + +If you need finer control about which parts of the interface are used +and which not, read the docstring of the variable +@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x +customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. + +The following list describes the individual parts of the interface. + +@itemize @bullet +@item +@findex reftex-label +@vindex LaTeX-label-function, @r{AUCTeX} +@kindex C-c C-e +@kindex C-c C-s +@findex LaTeX-section, @r{AUCTeX} +@findex TeX-insert-macro, @r{AUCTeX} +@b{AUCTeX calls @code{reftex-label} to insert labels}@* +When a new section is created with @kbd{C-c C-s}, or a new environment +is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to +go with it. With the interface, @code{reftex-label} is called instead. +For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and +@b{Ref@TeX{}} will insert + +@example +\begin@{equation@} +\label@{eq:1@} + +\end@{equation@} +@end example + +@noindent +without further prompts. + +Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} +will offer its default label which is derived from the section title. + +@item +@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* +When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not +have to rescan the buffer in order to see it. + +@item +@findex reftex-arg-label +@findex TeX-arg-label, @r{AUCTeX function} +@findex reftex-arg-ref +@findex TeX-arg-ref, @r{AUCTeX function} +@findex reftex-arg-cite +@findex TeX-arg-cite, @r{AUCTeX function} +@findex reftex-arg-index +@findex TeX-arg-index, @r{AUCTeX function} +@findex TeX-insert-macro, @r{AUCTeX function} +@kindex C-c @key{RET} +@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro +interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for +macro arguments. Internally, it uses the functions +@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to +prompt for arguments which are labels, citation keys and index entries. +The interface takes over these functions@footnote{@code{fset} is used to +do this, which is not reversible. However, @b{Ref@TeX{}} implements the +old functionality when you later decide to turn off the interface.} and +supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For +example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} +will supply its label selection process (@pxref{Referencing +Labels}). + +@item +@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* +@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. +@end itemize + +@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX +@subsection Style Files +@cindex Style files, AUCTeX +@findex TeX-add-style-hook, @r{AUCTeX} +Style files are Emacs Lisp files which are evaluated by AUCTeX in +association with the @code{\documentclass} and @code{\usepackage} +commands of a document (@pxref{Style Files,,,auctex}). Support for +@b{Ref@TeX{}} in such a style file is useful when the LaTeX style +defines macros or environments connected with labels, citations, or the +index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el}) +distributed with AUCTeX already support @b{Ref@TeX{}} in this +way. + +Before calling a @b{Ref@TeX{}} function, the style hook should always +test for the availability of the function, so that the style file will +also work for people who do not use @b{Ref@TeX{}}. + +Additions made with style files in the way described below remain local +to the current document. For example, if one package uses AMSTeX, the +style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but +this will not affect other documents. + +@findex reftex-add-label-environments +@findex reftex-add-to-label-alist +A style hook may contain calls to +@code{reftex-add-label-environments}@footnote{This used to be the +function @code{reftex-add-to-label-alist} which is still available as an +alias for compatibility.} which defines additions to +@code{reftex-label-alist}. The argument taken by this function must have +the same format as @code{reftex-label-alist}. The @file{amsmath.el} +style file of AUCTeX for example contains the following: + +@lisp +@group +(TeX-add-style-hook "amsmath" + (lambda () + (if (fboundp 'reftex-add-label-environments) + (reftex-add-label-environments '(AMSTeX))))) +@end group +@end lisp + +@noindent +@findex LaTeX-add-environments, @r{AUCTeX} +while a package @code{myprop} defining a @code{proposition} environment +with @code{\newtheorem} might use + +@lisp +@group +(TeX-add-style-hook "myprop" + (lambda () + (LaTeX-add-environments '("proposition" LaTeX-env-label)) + (if (fboundp 'reftex-add-label-environments) + (reftex-add-label-environments + '(("proposition" ?p "prop:" "~\\ref@{%s@}" t + ("Proposition" "Prop.") -3)))))) +@end group +@end lisp + +@findex reftex-set-cite-format +Similarly, a style hook may contain a call to +@code{reftex-set-cite-format} to set the citation format. The style +file @file{natbib.el} for the Natbib citation style does switch +@b{Ref@TeX{}}'s citation format like this: + +@lisp +(TeX-add-style-hook "natbib" + (lambda () + (if (fboundp 'reftex-set-cite-format) + (reftex-set-cite-format 'natbib)))) +@end lisp + +@findex reftex-add-index-macros +The hook may contain a call to @code{reftex-add-index-macros} to +define additional @code{\index}-like macros. The argument must have +the same format as @code{reftex-index-macros}. It may be a symbol, to +trigger support for one of the builtin index packages. For example, +the style @file{multind.el} contains + +@lisp +(TeX-add-style-hook "multind" + (lambda () + (and (fboundp 'reftex-add-index-macros) + (reftex-add-index-macros '(multind))))) +@end lisp + +If you have your own package @file{myindex} which defines the +following macros to be used with the LaTeX @file{index.sty} file +@example +\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} +\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} +@end example + +you could write this in the style file @file{myindex.el}: + +@lisp +(TeX-add-style-hook "myindex" + (lambda () + (TeX-add-symbols + '("molec" TeX-arg-index) + '("aindex" TeX-arg-index)) + (if (fboundp 'reftex-add-index-macros) + (reftex-add-index-macros + '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) + ("aindex@{*@}" "author" ?a "" nil nil)))))) +@end lisp + +@findex reftex-add-section-levels +Finally the hook may contain a call to @code{reftex-add-section-levels} +to define additional section statements. For example, the FoilTeX class +has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here +is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: + +@lisp +(TeX-add-style-hook "foils" + (lambda () + (if (fboundp 'reftex-add-section-levels) + (reftex-add-section-levels '(("foilhead" . 3) + ("rotatefoilhead" . 3)))))) +@end lisp + +@node Bib-Cite, , Style Files, AUCTeX +@subsection Bib-Cite +@cindex @code{bib-cite}, Emacs package +@cindex Emacs packages, @code{bib-cite} + +Once you have written a document with labels, references and citations, +it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has +support for that: @code{reftex-view-crossref} (bound to @kbd{C-c +&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and +@code{reftex-search-document}. A somewhat fancier interface with mouse +highlighting is provided (among other things) by Peter S. Galbraith's +@file{bib-cite.el}. There is some overlap in the functionalities of +Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with +AUCTeX. + +Bib-cite version 3.06 and later can be configured so that bib-cite's +mouse functions use @b{Ref@TeX{}} for displaying references and citations. +This can be useful in particular when working with the LaTeX @code{xr} +package or with an explicit @code{thebibliography} environment (rather +than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To +make use of this feature, try + +@vindex bib-cite-use-reftex-view-crossref +@lisp +(setq bib-cite-use-reftex-view-crossref t) +@end lisp + +@page +@node Problems and Work-Arounds, Imprint, Optimizations, Top +@section Problems and Work-arounds +@cindex Problems and work-arounds + +@itemize @bullet +@item +@b{LaTeX commands}@* +@cindex LaTeX commands, not found +@code{\input}, @code{\include}, and @code{\section} (etc.) statements +have to be first on a line (except for white space). + +@item +@b{Commented regions}@* +@cindex Labels, commented out +@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to +make duplicates of such labels. This is considered to be a feature. + +@item +@b{Wrong section numbers}@* +@cindex Section numbers, wrong +@vindex reftex-enable-partial-scans +When using partial scans (@code{reftex-enable-partial-scans}), the section +numbers in the table of contents may eventually become wrong. A full +scan will fix this. + +@item +@b{Local settings}@* +@cindex Settings, local +@findex reftex-add-label-environments +@findex reftex-set-cite-format +@findex reftex-add-section-levels +The label environment definitions in @code{reftex-label-alist} are +global and apply to all documents. If you need to make definitions +local to a document, because they would interfere with settings in other +documents, you should use AUCTeX and set up style files with calls to +@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, +@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. +Settings made with these functions remain local to the current +document. @xref{AUCTeX}. + +@item +@b{Funny display in selection buffer}@* +@cindex @code{x-symbol}, Emacs package +@cindex Emacs packages, @code{x-symbol} +@cindex @code{isotex}, Emacs package +@cindex Emacs packages, @code{isotex} +@cindex @code{iso-cvt}, Emacs package +@cindex Emacs packages, @code{iso-cvt} +When using packages which make the buffer representation of a file +different from its disk representation (e.g. x-symbol, isotex, +iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes +reflects the disk state of a file. This happens only in @emph{unvisited} +parts of a multifile document, because @b{Ref@TeX{}} visits these files +literally for speed reasons. Then both short context and section +headings may look different from what you usually see on your screen. +In rare cases @code{reftex-toc} may have problems to jump to an affected +section heading. There are three possible ways to deal with +this: +@itemize @minus +@item +@vindex reftex-keep-temporary-buffers +@code{(setq reftex-keep-temporary-buffers t)}@* +This implies that @b{Ref@TeX{}} will load all parts of a multifile +document into Emacs (i.e. there won't be any temporary buffers). +@item +@vindex reftex-initialize-temporary-buffers +@code{(setq reftex-initialize-temporary-buffers t)}@* +This means full initialization of temporary buffers. It involves +a penalty when the same unvisited file is used for lookup often. +@item +Set @code{reftex-initialize-temporary-buffers} to a list of hook +functions doing a minimal initialization. +@end itemize +@vindex reftex-refontify-context +See also the variable @code{reftex-refontify-context}. + +@item +@b{Labels as arguments to \begin}@* +@cindex @code{pf}, LaTeX package +@cindex LaTeX packages, @code{pf} +Some packages use an additional argument to a @code{\begin} macro +to specify a label. E.g. Lamport's @file{pf.sty} uses both +@example +\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} + @var{claim} + \end@{step+@} +@end example + +@noindent +We need to trick @b{Ref@TeX{}} into swallowing this: + +@lisp +@group +;; Configuration for Lamport's pf.sty +(setq reftex-label-alist + '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) + ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) +@end group +@end lisp + +@noindent +The first line is just a normal configuration for a macro. For the +@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the +@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} +argument (which really is a second argument to the macro @code{\begin}) +as a label of type @code{?p}. Argument count for this macro starts only +after the @samp{@{step+@}}, also when specifying how to get +context. + +@item +@b{Idle timers in XEmacs}@* +@cindex Idle timer restart +@vindex reftex-use-itimer-in-xemacs +In XEmacs, idle timer restart does not work reliably after fast +keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command +hook to start the timer used for automatic crossref information. When +this bug gets fixed, a real idle timer can be requested with +@lisp +(setq reftex-use-itimer-in-xemacs t) +@end lisp + +@item +@b{Viper mode}@* +@cindex Viper mode +@cindex Key bindings, problems with Viper mode +@findex viper-harness-minor-mode +With @i{Viper} mode prior to Vipers version 3.01, you need to protect +@b{Ref@TeX{}}'s keymaps with + +@lisp +(viper-harness-minor-mode "reftex") +@end lisp + +@end itemize + +@page +@node Imprint, Commands, Problems and Work-Arounds, Top +@section Imprint +@cindex Imprint +@cindex Maintainer +@cindex Acknowledgments +@cindex Thanks +@cindex Bug reports +@cindex @code{http}, @b{Ref@TeX{}} home page +@cindex @code{ftp}, @b{Ref@TeX{}} site + +Ref@TeX{} was written by @i{Carsten Dominik} +@email{dominik@@science.uva.nl}, with contributions by @i{Stephen +Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see +the @value{MAINTAINERSITE} for detailed information. + +If you have questions about Ref@TeX{}, you can send email to the +@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write +to the @value{DEVELADDRESS}. And in the rare case of finding a bug, +please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a +bug report with useful information about your setup. Remember to add +essential information like a recipe for reproducing the bug, what you +expected to happen, and what actually happened. Send the bug report to +the @value{BUGADDRESS}. + +There are also several Usenet groups which have competent readers who +might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, +@code{comp.emacs.xemacs}, and @code{comp.text.tex}. + +@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. +It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs +21.x users want to install the corresponding plugin package which is +available from the @value{XEMACSFTP}. See the XEmacs 21.x +documentation on package installation for details. + +Users of earlier Emacs distributions (including Emacs 19) can get a +@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that +the Emacs 19 version supports many but not all features described in +this manual. + +Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped +developing it with their reports. In particular thanks to @i{Ralf +Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, +Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai +Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan +Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, +Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan +Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, +Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan +Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}. + + +The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} +@file{bib-cite.el}. + +Finally thanks to @i{Uwe Bolick} who first got me interested in +supporting LaTeX labels and references with an editor (which was +MicroEmacs at the time). + +@node Commands, Options, Imprint, Top +@chapter Commands +@cindex Commands, list of + +Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from +LaTeX files. Command which are executed from the special buffers are +not described here. All commands are available from the @code{Ref} +menu. See @xref{Key Bindings}. + +@deffn Command reftex-toc +Show the table of contents for the current document. When called with +one ore two @kbd{C-u} prefixes, rescan the document first. +@end deffn + +@deffn Command reftex-label +Insert a unique label. With one or two @kbd{C-u} prefixes, enforce +document rescan first. +@end deffn + +@deffn Command reftex-reference +Start a selection process to select a label, and insert a reference to +it. With one or two @kbd{C-u} prefixes, enforce document rescan first. +@end deffn + +@deffn Command reftex-citation +Make a citation using BibTeX database files. After prompting for a regular +expression, scans the buffers with BibTeX entries (taken from the +@code{\bibliography} command or a @code{thebibliography} environment) +and offers the matching entries for selection. The selected entry is +formatted according to @code{reftex-cite-format} and inserted into the +buffer. @* +When called with a @kbd{C-u} prefix, prompt for optional arguments in +cite macros. When called with a numeric prefix, make that many citations. +When called with point inside the braces of a @code{\cite} command, it +will add another key, ignoring the value of +@code{reftex-cite-format}. @* +The regular expression uses an expanded syntax: @samp{&&} is interpreted +as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain +both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion +on knows citation keys is possible. @samp{=} is a good regular +expression to match all entries in all files. +@end deffn + +@deffn Command reftex-index +Query for an index macro and insert it along with its arguments. The +index macros available are those defined in @code{reftex-index-macro} or +by a call to @code{reftex-add-index-macros}, typically from an AUCTeX +style file. @b{Ref@TeX{}} provides completion for the index tag and the +index key, and will prompt for other arguments. +@end deffn + +@deffn Command reftex-index-selection-or-word +Put current selection or the word near point into the default index +macro. This uses the information in @code{reftex-index-default-macro} +to make an index entry. The phrase indexed is the current selection or +the word near point. When called with one @kbd{C-u} prefix, let the +user have a chance to edit the index entry. When called with 2 +@kbd{C-u} as prefix, also ask for the index macro and other stuff. When +called inside TeX math mode as determined by the @file{texmathp.el} +library which is part of AUCTeX, the string is first processed with the +@code{reftex-index-math-format}, which see. +@end deffn + +@deffn Command reftex-index-phrase-selection-or-word +Add current selection or the word at point to the phrases buffer. +When you are in transient-mark-mode and the region is active, the +selection will be used - otherwise the word at point. +You get a chance to edit the entry in the phrases buffer - to save the +buffer and return to the LaTeX document, finish with @kbd{C-c C-c}. +@end deffn + +@deffn Command reftex-index-visit-phrases-buffer +Switch to the phrases buffer, initialize if empty. +@end deffn + +@deffn Command reftex-index-phrases-apply-to-region +Index all index phrases in the current region. +This works exactly like global indexing from the index phrases buffer, +but operation is restricted to the current region. +@end deffn + +@deffn Command reftex-display-index +Display a buffer with an index compiled from the current document. +When the document has multiple indices, first prompts for the correct one. +When index support is turned off, offer to turn it on. +With one or two @kbd{C-u} prefixes, rescan document first. +With prefix 2, restrict index to current document section. +With prefix 3, restrict index to active region. +@end deffn + +@deffn Command reftex-view-crossref +View cross reference of macro at point. Point must be on the @var{key} +argument. Works with the macros @code{\label}, @code{\ref}, +@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of +these. Where it makes sense, subsequent calls show additional +locations. See also the variable @code{reftex-view-crossref-extra} and +the command @code{reftex-view-crossref-from-bibtex}. With one or two +@kbd{C-u} prefixes, enforce rescanning of the document. With argument +2, select the window showing the cross reference. +@end deffn + +@deffn Command reftex-view-crossref-from-bibtex +View location in a LaTeX document which cites the BibTeX entry at point. +Since BibTeX files can be used by many LaTeX documents, this function +prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this +link to a document, call the function with a prefix arg. Calling +this function several times find successive citation locations. +@end deffn + +@deffn Command reftex-create-tags-file +Create TAGS file by running @code{etags} on the current document. The +TAGS file is also immediately visited with +@code{visit-tags-table}. +@end deffn + +@deffn Command reftex-grep-document +Run grep query through all files related to this document. +With prefix arg, force to rescan document. +No active TAGS table is required. +@end deffn + +@deffn Command reftex-search-document +Regexp search through all files of the current document. +Starts always in the master file. Stops when a match is found. +No active TAGS table is required. +@end deffn + +@deffn Command reftex-query-replace-document +Run a query-replace-regexp of @var{from} with @var{to} over the entire +document. With prefix arg, replace only word-delimited matches. No +active TAGS table is required. +@end deffn + +@deffn Command reftex-isearch-minor-mode +Toggle a minor mode which enables incremental search to work globally +on the entire multifile document. Files will be searched in th +sequence they appear in the document. +@end deffn + +@deffn Command reftex-goto-label +Prompt for a label (with completion) and jump to the location of this +label. Optional prefix argument @var{other-window} goes to the label in +another window. +@end deffn + + +@deffn Command reftex-change-label +Query replace @var{from} with @var{to} in all @code{\label} and +@code{\ref} commands. Works on the entire multifile document. No +active TAGS table is required. +@end deffn + +@deffn Command reftex-renumber-simple-labels +Renumber all simple labels in the document to make them sequentially. +Simple labels are the ones created by RefTeX, consisting only of the +prefix and a number. After the command completes, all these labels will +have sequential numbers throughout the document. Any references to the +labels will be changed as well. For this, @b{Ref@TeX{}} looks at the +arguments of any macros which either start or end with the string +@samp{ref}. This command should be used with care, in particular in +multifile documents. You should not use it if another document refers +to this one with the @code{xr} package. +@end deffn + +@deffn Command reftex-find-duplicate-labels +Produce a list of all duplicate labels in the document. +@end deffn + +@deffn Command reftex-create-bibtex-file +Create a new BibTeX database file with all entries referenced in document. +The command prompts for a filename and writes the collected entries to +that file. Only entries referenced in the current document with +any @code{\cite}-like macros are used. +The sequence in the new file is the same as it was in the old database. +@end deffn + +@deffn Command reftex-customize +Run the customize browser on the @b{Ref@TeX{}} group. +@end deffn +@deffn Command reftex-show-commentary +Show the commentary section from @file{reftex.el}. +@end deffn +@deffn Command reftex-info +Run info on the top @b{Ref@TeX{}} node. +@end deffn +@deffn Command reftex-parse-document +Parse the entire document in order to update the parsing information. +@end deffn +@deffn Command reftex-reset-mode +Enforce rebuilding of several internal lists and variables. Also +removes the parse file associated with the current document. +@end deffn + +@node Options, Keymaps and Hooks, Commands, Top +@chapter Options, Keymaps, Hooks +@cindex Options, list of + +Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All +variables have customize support - so if you are not familiar with Emacs +Lisp (and even if you are) you might find it more comfortable to use +@code{customize} to look at and change these variables. @kbd{M-x +reftex-customize} will get you there. + +@menu +* Options (Table of Contents):: +* Options (Defining Label Environments):: +* Options (Creating Labels):: +* Options (Referencing Labels):: +* Options (Creating Citations):: +* Options (Index Support):: +* Options (Viewing Cross-References):: +* Options (Finding Files):: +* Options (Optimizations):: +* Options (Fontification):: +* Options (Misc):: +@end menu + +@node Options (Table of Contents), Options (Defining Label Environments), , Options +@section Table of Contents +@cindex Options, table of contents +@cindex Table of contents, options + +@defopt reftex-include-file-commands +List of LaTeX commands which input another file. +The file name is expected after the command, either in braces or separated +by whitespace. +@end defopt + +@defopt reftex-max-section-depth +Maximum depth of section levels in document structure. +Standard LaTeX needs 7, default is 12. +@end defopt + +@defopt reftex-section-levels +Commands and levels used for defining sections in the document. The +@code{car} of each cons cell is the name of the section macro. The +@code{cdr} is a number indicating its level. A negative level means the +same as the positive value, but the section will never get a number. +The @code{cdr} may also be a function which then has to return the +level. This list is also used for promotion and demotion of sectioning +commands. If you are using a document class which has several sets of +sectioning commands, promotion only works correctly if this list is +sorted first by set, then within each set by level. The promotion +commands always select the nearest entry with the correct new level. + +@end defopt + +@defopt reftex-toc-max-level +The maximum level of toc entries which will be included in the TOC. +Section headings with a bigger level will be ignored. In RefTeX, +chapters are level 1, sections level 2 etc. This variable can be +changed from within the @file{*toc*} buffer with the @kbd{t} key. +@end defopt + +@defopt reftex-part-resets-chapter +Non-@code{nil} means, @code{\part} is like any other sectioning command. +This means, part numbers will be included in the numbering of chapters, and +chapter counters will be reset for each part. +When @code{nil} (the default), parts are special, do not reset the +chapter counter and also do not show up in chapter numbers. +@end defopt + +@defopt reftex-auto-recenter-toc +Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. +When active, the @file{*TOC*} window will always show the section you +are currently working in. Recentering happens whenever Emacs is idle for +more than @code{reftex-idle-time} seconds. + +Value @code{t} means, turn on immediately when RefTeX gets started. Then, +recentering will work for any toc window created during the session. + +Value @code{frame} (the default) means, turn automatic recentering on +only while the dedicated TOC frame does exist, and do the recentering +only in that frame. So when creating that frame (with @kbd{d} key in an +ordinary TOC window), the automatic recentering is turned on. When the +frame gets destroyed, automatic recentering is turned off again. + +This feature can be turned on and off from the menu +(Ref->Options). +@end defopt + +@defopt reftex-toc-split-windows-horizontally +Non-@code{nil} means, create TOC window by splitting window +horizontally. The default is to split vertically. +@end defopt + +@defopt reftex-toc-split-windows-fraction +Fraction of the width or height of the frame to be used for TOC window. +@end defopt + +@defopt reftex-toc-keep-other-windows +Non-@code{nil} means, split the selected window to display the +@file{*toc*} buffer. This helps to keep the window configuration, but +makes the @file{*toc*} small. When @code{nil}, all other windows except +the selected one will be deleted, so that the @file{*toc*} window fills +half the frame. +@end defopt + +@defopt reftex-toc-include-file-boundaries +Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{i} key. +@end defopt + +@defopt reftex-toc-include-labels +Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag +can be toggled from within the @file{*toc*} buffer with the @kbd{l} +key. +@end defopt + +@defopt reftex-toc-include-index-entries +Non-@code{nil} means, include index entries in @file{*toc*} buffer. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{i} key. +@end defopt + +@defopt reftex-toc-include-context +Non-@code{nil} means, include context with labels in the @file{*toc*} +buffer. Context will only be shown if the labels are visible as well. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{c} key. +@end defopt + +@defopt reftex-toc-follow-mode +Non-@code{nil} means, point in @file{*toc*} buffer (the +table-of-contents buffer) will cause other window to follow. The other +window will show the corresponding part of the document. This flag can +be toggled from within the @file{*toc*} buffer with the @kbd{f} +key. +@end defopt + +@deffn {Normal Hook} reftex-toc-mode-hook +Normal hook which is run when a @file{*toc*} buffer is +created. +@end deffn + +@deffn Keymap reftex-toc-map +The keymap which is active in the @file{*toc*} buffer. +(@pxref{Table of Contents}). +@end deffn + +@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options +@section Defining Label Environments +@cindex Options, defining label environments +@cindex Defining label environments, options + +@defopt reftex-default-label-alist-entries +Default label alist specifications. It is a list of symbols with +associations in the constant @code{reftex-label-alist-builtin}. +@code{LaTeX} should always be the last entry. +@end defopt + +@defopt reftex-label-alist +Set this variable to define additions and changes to the defaults in +@code{reftex-default-label-alist-entries}. The only things you +@emph{must not} change is that @code{?s} is the type indicator for +section labels, and @key{SPC} for the @code{any} label type. These are +hard-coded at other places in the code. + +The value of the variable must be a list of items. Each item is a list +itself and has the following structure: + +@example + (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} + @var{context-method} (@var{magic-word} ... ) @var{toc-level}) +@end example + +Each list entry describes either an environment carrying a counter for +use with @code{\label} and @code{\ref}, or a LaTeX macro defining a +label as (or inside) one of its arguments. The elements of each list +entry are: + +@table @asis +@item @var{env-or-macro} +Name of the environment (like @samp{table}) or macro (like +@samp{\myfig}). For macros, indicate the arguments, as in +@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional +arguments, a star to mark the label argument, if any. The macro does +not have to have a label argument - you could also use +@samp{\label@{...@}} inside one of its arguments. + +Special names: @code{section} for section labels, @code{any} to define a +group which contains all labels. + +This may also be a function to do local parsing and identify point to be +in a non-standard label environment. The function must take an +argument @var{bound} and limit backward searches to this value. It +should return either nil or a cons cell @code{(@var{function} +. @var{position})} with the function symbol and the position where the +special environment starts. See the Info documentation for an +example. + +Finally this may also be @code{nil} if the entry is only meant to change +some settings associated with the type indicator character (see +below). + +@item @var{type-key} +Type indicator character, like @code{?t}, must be a printable ASCII +character. The type indicator is a single character which defines a +label type. Any label inside the environment or macro is assumed to +belong to this type. The same character may occur several times in this +list, to cover cases in which different environments carry the same +label type (like @code{equation} and @code{eqnarray}). If the type +indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, +the macro defines neutral labels just like @code{\label}. In this case +the reminder of this entry is ignored. + +@item @var{label-prefix} +Label prefix string, like @samp{tab:}. The prefix is a short string +used as the start of a label. It may be the empty string. The prefix +may contain the following @samp{%} escapes: + +@example +%f Current file name, directory and extension stripped. +%F Current file name relative to master file directory. +%m Master file name, directory and extension stripped. +%M Directory name (without path) where master file is located. +%u User login name, on systems which support this. +%S A section prefix derived with variable @code{reftex-section-prefixes}. +@end example + +@noindent +Example: In a file @file{intro.tex}, @samp{eq:%f:} will become +@samp{eq:intro:}. + +@item @var{reference-format} +Format string for reference insert in buffer. @samp{%s} will be +replaced by the label. When the format starts with @samp{~}, this +@samp{~} will only be inserted when the character before point is +@emph{not} a whitespace. + +@item @var{context-method} +Indication on how to find the short context. +@itemize @minus +@item +If @code{nil}, use the text following the @samp{\label@{...@}} macro. +@item +If @code{t}, use +@itemize @minus +@item +the section heading for section labels. +@item +text following the @samp{\begin@{...@}} statement of environments (not +a good choice for environments like eqnarray or enumerate, where one has +several labels in a single environment). +@item +text after the macro name (starting with the first arg) for +macros. +@end itemize +@item +If an integer, use the nth argument of the macro. As a special case, +1000 means to get text after the last macro argument. +@item +If a string, use as regexp to search @emph{backward} from the label. +Context is then the text following the end of the match. E.g. putting +this to @samp{\\caption[[@{]} will use the caption in a figure or table +environment. @samp{\\begin@{eqnarray@}\|\\\\} works for +eqnarrays. +@item +If any of @code{caption}, @code{item}, @code{eqnarray-like}, +@code{alignat-like}, this symbol will internally be translated into an +appropriate regexp (see also the variable +@code{reftex-default-context-regexps}). +@item +If a function, call this function with the name of the environment/macro +as argument. On call, point will be just after the @code{\label} macro. +The function is expected to return a suitable context string. It should +throw an exception (error) when failing to find context. As an example, +here is a function returning the 10 chars following the label macro as +context: + +@example +(defun my-context-function (env-or-mac) + (if (> (point-max) (+ 10 (point))) + (buffer-substring (point) (+ 10 (point))) + (error "Buffer too small"))) +@end example +@end itemize + +Label context is used in two ways by @b{Ref@TeX{}}: For display in the label +menu, and to derive a label string. If you want to use a different +method for each of these, specify them as a dotted pair. +E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for +display, and text from the default position (@code{t}) to derive a label +string. This is actually used for section labels. + +@item @var{magic-word-list} +List of magic words which identify a reference to be of this type. If +the word before point is equal to one of these words when calling +@code{reftex-reference}, the label list offered will be automatically +restricted to labels of the correct type. If the first element of this +word--list is the symbol `regexp', the strings are interpreted as regular +expressions. + +@item @var{toc-level} +The integer level at which this environment should be added to the table +of contents. See also @code{reftex-section-levels}. A positive value +will number the entries mixed with the sectioning commands of the same +level. A negative value will make unnumbered entries. Useful only for +theorem-like environments which structure the document. Will be ignored +for macros. When omitted or @code{nil}, no TOC entries will be +made. +@end table + +If the type indicator characters of two or more entries are the same, +@b{Ref@TeX{}} will use +@itemize @minus +@item +the first non-@code{nil} format and prefix +@item +the magic words of all involved entries. +@end itemize + +Any list entry may also be a symbol. If that has an association in +@code{reftex-label-alist-builtin}, the @code{cddr} of that association is +spliced into the list. However, builtin defaults should normally be set +with the variable @code{reftex-default-label-alist-entries}. +@end defopt + +@defopt reftex-section-prefixes +Prefixes for section labels. When the label prefix given in an entry in +@code{reftex-label-alist} contains @samp{%S}, this list is used to +determine the correct prefix string depending on the current section +level. The list is an alist, with each entry of the form +@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro +names like @samp{chapter}, integer section levels (as given in +@code{reftex-section-levels}), and @code{t} for the default. +@end defopt + +@defopt reftex-default-context-regexps +Alist with default regular expressions for finding context. The emacs +lisp form @w{@code{(format regexp (regexp-quote environment))}} is used +to calculate the final regular expression - so @samp{%s} will be +replaced with the environment or macro. +@end defopt + +@defopt reftex-trust-label-prefix +Non-@code{nil} means, trust the label prefix when determining label type. +It is customary to use special label prefixes to distinguish different label +types. The label prefixes have no syntactic meaning in LaTeX (unless +special packages like fancyref) are being used. RefTeX can and by +default does parse around each label to detect the correct label type, +but this process can be slow when a document contains thousands of +labels. If you use label prefixes consistently, you may speed up +document parsing by setting this variable to a non-nil value. RefTeX +will then compare the label prefix with the prefixes found in +`reftex-label-alist' and derive the correct label type in this way. +Possible values for this option are: + +@example +t @r{This means to trust any label prefixes found.} +regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} +list @r{List of accepted prefixes, as strings. The colon is part of} + @r{the prefix, e.g. ("fn:" "eqn:" "item:").} +nil @r{Never trust a label prefix.} +@end example +The only disadvantage of using this feature is that the label context +displayed in the label selection buffer along with each label is +simply some text after the label definition. This is no problem if you +place labels keeping this in mind (e.g. @i{before} the equation, @i{at +the beginning} of a fig/tab caption ...). Anyway, it is probably best +to use the regexp or the list value types to fine-tune this feature. +For example, if your document contains thousands of footnotes with +labels fn:xxx, you may want to set this variable to the value "^fn:$" or +("fn:"). Then RefTeX will still do extensive parsing for any +non-footnote labels. +@end defopt + +@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options +@section Creating Labels +@cindex Options, creating labels +@cindex Creating labels, options + +@defopt reftex-insert-label-flags +Flags governing label insertion. The value has the form + +@example +(@var{derive} @var{prompt}) +@end example + +If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible +label from context. A section label for example will be derived from +the section heading. The conversion of the context to a valid label is +governed by the specifications given in +@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, +the default label will consist of the prefix and a unique number, like +@samp{eq:23}. + +If @var{prompt} is @code{t}, the user will be prompted for a label +string. When @var{prompt} is @code{nil}, the default label will be +inserted without query. + +So the combination of @var{derive} and @var{prompt} controls label +insertion. Here is a table describing all four possibilities: + +@example +@group +@var{derive} @var{prompt} @var{action} +----------------------------------------------------------- +nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} +nil t @r{Prompt for label.} +t nil @r{Derive a label from context and insert. No query.} +t t @r{Derive a label from context, prompt for confirmation.} +@end group +@end example + +Each flag may be set to @code{t}, @code{nil}, or a string of label type +letters indicating the label types for which it should be true. Thus, +the combination may be set differently for each label type. The default +settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from +headings (with confirmation). Prompt for figure and table labels. Use +simple labels without confirmation for everything else. + +The available label types are: @code{s} (section), @code{f} (figure), +@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} +(footnote), @code{N} (endnote) plus any definitions in +@code{reftex-label-alist}. +@end defopt + +@deffn Hook reftex-format-label-function +If non-@code{nil}, should be a function which produces the string to +insert as a label definition. The function will be called with two +arguments, the @var{label} and the @var{default-format} (usually +@samp{\label@{%s@}}). It should return the string to insert into the +buffer. +@end deffn + +@deffn Hook reftex-string-to-label-function +Function to turn an arbitrary string into a valid label. +@b{Ref@TeX{}}'s default function uses the variable +@code{reftex-derive-label-parameters}. +@end deffn + +@deffn Hook reftex-translate-to-ascii-function +Filter function which will process a context string before it is used to +derive a label from it. The intended application is to convert ISO or +Mule characters into something valid in labels. The default function +@code{reftex-latin1-to-ascii} removes the accents from Latin-1 +characters. X-Symbol (>=2.6) sets this variable to the much more +general @code{x-symbol-translate-to-ascii}. +@end deffn + +@defopt reftex-derive-label-parameters +Parameters for converting a string into a label. This variable is a +list of the following items: +@table @asis +@item @var{nwords} +Number of words to use. +@item @var{maxchar} +Maximum number of characters in a label string. +@item @var{invalid} +@code{nil}: Throw away any words containing characters invalid in labels.@* +@code{t}: Throw away only the invalid characters, not the whole word. +@item @var{abbrev} +@code{nil}: Never abbreviate words.@* +@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* +@code{1}: Abbreviate words if necessary to shorten label string. +@item @var{separator} +String separating different words in the label. +@item @var{ignorewords} +List of words which should not be part of labels. +@item @var{downcase} +@code{t}: Downcase words before putting them into the label.@* +@end table +@end defopt + +@defopt reftex-label-illegal-re +Regexp matching characters not valid in labels. +@end defopt + +@defopt reftex-abbrev-parameters +Parameters for abbreviation of words. A list of four parameters. +@table @asis +@item @var{min-chars} +Minimum number of characters remaining after abbreviation. +@item @var{min-kill} +Minimum number of characters to remove when abbreviating words. +@item @var{before} +Character class before abbrev point in word. +@item @var{after} +Character class after abbrev point in word. +@end table +@end defopt + +@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options +@section Referencing Labels +@cindex Options, referencing labels +@cindex Referencing labels, options + +@defopt reftex-label-menu-flags +List of flags governing the label menu makeup. The flags are: +@table @asis +@item @var{table-of-contents} +Show the labels embedded in a table of context. +@item @var{section-numbers} +Include section numbers (like 4.1.3) in table of contents. +@item @var{counters} +Show counters. This just numbers the labels in the menu. +@item @var{no-context} +Non-@code{nil} means do @emph{not} show the short context. +@item @var{follow} +Follow full context in other window. +@item @var{show-commented} +Show labels from regions which are commented out. +@item @var{match-everywhere} +Obsolete flag. +@item @var{show-files} +Show begin and end of included files. +@end table + +Each of these flags can be set to @code{t} or @code{nil}, or to a string +of type letters indicating the label types for which it should be true. +These strings work like character classes in regular expressions. Thus, +setting one of the flags to @samp{"sf"} makes the flag true for section +and figure labels, @code{nil} for everything else. Setting it to +@samp{"^sf"} makes it the other way round. + +The available label types are: @code{s} (section), @code{f} (figure), +@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} +(footnote), plus any definitions in @code{reftex-label-alist}. + +Most options can also be switched from the label menu itself - so if you +decide here to not have a table of contents in the label menu, you can +still get one interactively during selection from the label menu. +@end defopt + +@defopt reftex-multiref-punctuation +Punctuation strings for multiple references. When marking is used in +the selection buffer to select several references, this variable +associates the 3 marking characters @samp{,-+} with prefix strings to be +inserted into the buffer before the corresponding @code{\ref} macro. +This is used to string together whole reference sets, like +@samp{eqs. 1,2,3-5,6 and 7} in a single call to +@code{reftex-reference}. +@end defopt + +@defopt reftex-vref-is-default +Non-@code{nil} means, the varioref macro @code{\vref} is used as +default. In the selection buffer, the @kbd{v} key toggles the reference +macro between @code{\ref} and @code{\vref}. The value of this variable +determines the default which is active when entering the selection +process. Instead of @code{nil} or @code{t}, this may also be a string +of type letters indicating the label types for which it should be +true. +@end defopt + +@defopt reftex-fref-is-default +Non-@code{nil} means, the fancyref macro @code{\fref} is used as +default. In the selection buffer, the @kbd{V} key toggles the reference +macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of +this variable determines the default which is active when entering the +selection process. Instead of @code{nil} or @code{t}, this may also be +a string of type letters indicating the label types for which it should +be true. +@end defopt + +@deffn Hook reftex-format-ref-function +If non-@code{nil}, should be a function which produces the string to +insert as a reference. Note that the insertion format can also be +changed with @code{reftex-label-alist}. This hook also is used by the +special commands to insert @code{\vref} and @code{\fref} references, so +even if you set this, your setting will be ignored by the special +commands. The function will be called with two arguments, the +@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). +It should return the string to insert into the buffer. +@end deffn + +@defopt reftex-level-indent +Number of spaces to be used for indentation per section level. +@end defopt + +@defopt reftex-guess-label-type +Non-@code{nil} means, @code{reftex-reference} will try to guess the +label type. To do that, @b{Ref@TeX{}} will look at the word before the +cursor and compare it with the magic words given in +@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will +immediately offer the correct label menu - otherwise it will prompt you +for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} +will always prompt for a label type. +@end defopt + +@deffn {Normal Hook} reftex-display-copied-context-hook +Normal Hook which is run before context is displayed anywhere. Designed +for @w{@code{X-Symbol}}, but may have other uses as well. +@end deffn + +@deffn Hook reftex-pre-refontification-functions +@code{X-Symbol} specific hook. Probably not useful for other purposes. +The functions get two arguments, the buffer from where the command +started and a symbol indicating in what context the hook is +called. +@end deffn + +@deffn {Normal Hook} reftex-select-label-mode-hook +Normal hook which is run when a selection buffer enters +@code{reftex-select-label-mode}. +@end deffn + +@deffn Keymap reftex-select-label-map +The keymap which is active in the labels selection process +(@pxref{Referencing Labels}). +@end deffn + +@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options +@section Creating Citations +@cindex Options, creating citations +@cindex Creating citations, options + +@defopt reftex-bibliography-commands +LaTeX commands which specify the BibTeX databases to use with the document. +@end defopt + +@defopt reftex-bibfile-ignore-regexps +List of regular expressions to exclude files in +@code{\\bibliography@{..@}}. File names matched by any of these regexps +will not be parsed. Intended for files which contain only +@code{@@string} macro definitions and the like, which are ignored by +@b{Ref@TeX{}} anyway. +@end defopt + +@defopt reftex-default-bibliography +List of BibTeX database files which should be used if none are specified. +When @code{reftex-citation} is called from a document with neither +a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} +environment, @b{Ref@TeX{}} will scan these files instead. Intended for +using @code{reftex-citation} in non-LaTeX files. The files will be +searched along the BIBINPUTS or TEXBIB path. +@end defopt + +@defopt reftex-sort-bibtex-matches +Sorting of the entries found in BibTeX databases by reftex-citation. +Possible values: +@example +nil @r{Do not sort entries.} +author @r{Sort entries by author name.} +year @r{Sort entries by increasing year.} +reverse-year @r{Sort entries by decreasing year.} +@end example +@end defopt + +@defopt reftex-cite-format +The format of citations to be inserted into the buffer. It can be a +string, an alist or a symbol. In the simplest case this is just the string +@samp{\cite@{%l@}}, which is also the default. See the definition of +@code{reftex-cite-format-builtin} for more complex examples. + +If @code{reftex-cite-format} is a string, it will be used as the format. +In the format, the following percent escapes will be expanded. + +@table @code +@item %l +The BibTeX label of the citation. +@item %a +List of author names, see also @code{reftex-cite-punctuation}. +@item %2a +Like %a, but abbreviate more than 2 authors like Jones et al. +@item %A +First author name only. +@item %e +Works like @samp{%a}, but on list of editor names. (@samp{%2e} and +@samp{%E} work a well). +@end table + +It is also possible to access all other BibTeX database fields: + +@example +%b booktitle %c chapter %d edition %h howpublished +%i institution %j journal %k key %m month +%n number %o organization %p pages %P first page +%r address %s school %u publisher %t title +%v volume %y year +%B booktitle, abbreviated %T title, abbreviated +@end example + +@noindent +Usually, only @samp{%l} is needed. The other stuff is mainly for the +echo area display, and for @code{(setq reftex-comment-citations t)}. + +@samp{%<} as a special operator kills punctuation and space around it +after the string has been formatted. + +A pair of square brackets indicates an optional argument, and RefTeX +will prompt for the values of these arguments. + +Beware that all this only works with BibTeX database files. When +citations are made from the @code{\bibitems} in an explicit +@code{thebibliography} environment, only @samp{%l} is available. + +If @code{reftex-cite-format} is an alist of characters and strings, the +user will be prompted for a character to select one of the possible +format strings. + +In order to configure this variable, you can either set +@code{reftex-cite-format} directly yourself or set it to the +@emph{symbol} of one of the predefined styles. The predefined symbols +are those which have an association in the constant +@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format +'natbib)}. +@end defopt + +@deffn Hook reftex-format-cite-function +If non-@code{nil}, should be a function which produces the string to +insert as a citation. Note that the citation format can also be changed +with the variable @code{reftex-cite-format}. The function will be +called with two arguments, the @var{citation-key} and the +@var{default-format} (taken from @code{reftex-cite-format}). It should +return the string to insert into the buffer. +@end deffn + +@defopt reftex-cite-prompt-optional-args +Non-@code{nil} means, prompt for empty optional arguments in cite macros. +When an entry in @code{reftex-cite-format} ist given with square brackets to +indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can +prompt for values. Possible values are: +@example +nil @r{Never prompt for optional arguments} +t @r{Always prompt} +maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example +Unnecessary empty optional arguments are removed before insertion into +the buffer. See @code{reftex-cite-cleanup-optional-args}. +@end defopt + +@defopt reftex-cite-cleanup-optional-args +Non-@code{nil} means, remove empty optional arguments from cite macros +if possible. +@end defopt + +@defopt reftex-comment-citations +Non-@code{nil} means add a comment for each citation describing the full +entry. The comment is formatted according to +@code{reftex-cite-comment-format}. +@end defopt + +@defopt reftex-cite-comment-format +Citation format used for commented citations. Must @emph{not} contain +@samp{%l}. See the variable @code{reftex-cite-format} for possible +percent escapes. +@end defopt + +@defopt reftex-cite-punctuation +Punctuation for formatting of name lists in citations. This is a list +of 3 strings. +@enumerate +@item +normal names separator, like @samp{, } in Jones, Brown and Miller +@item +final names separator, like @samp{ and } in Jones, Brown and Miller +@item +The @samp{et al.} string, like @samp{ @{\it et al.@}} in +Jones @{\it et al.@} +@end enumerate +@end defopt + +@deffn {Normal Hook} reftex-select-bib-mode-hook +Normal hook which is run when a selection buffer enters +@code{reftex-select-bib-mode}. +@end deffn + +@deffn Keymap reftex-select-bib-map +The keymap which is active in the citation-key selection process +(@pxref{Creating Citations}). +@end deffn + +@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options +@section Index Support +@cindex Options, Index support +@cindex Index support, options + +@defopt reftex-support-index +Non-@code{nil} means, index entries are parsed as well. Index support +is resource intensive and the internal structure holding the parsed +information can become quite big. Therefore it can be turned off. When +this is @code{nil} and you execute a command which requires index +support, you will be asked for confirmation to turn it on and rescan the +document. +@end defopt + +@defopt reftex-index-special-chars +List of special characters in index entries, given as strings. These +correspond to the @code{MakeIndex} keywords +@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. +@end defopt + +@defopt reftex-index-macros +List of macros which define index entries. The structure of each entry +is +@lisp +(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) +@end lisp + +@var{macro} is the macro. Arguments should be denoted by empty braces, +as for example in @samp{\index[]@{*@}}. Use square brackets to denote +optional arguments. The star marks where the index key is. + +@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} +are reserved for the default index and the glossary. Other indices can +be defined as well. If this is an integer, the Nth argument of the +macro holds the index tag. + +@var{key} is a character which is used to identify the macro for input +with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are +reserved for default index and glossary. + +@var{prefix} can be a prefix which is added to the @var{key} part of the +index entry. If you have a macro +@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix +should be @samp{Molecules!}. + +@var{exclude} can be a function. If this function exists and returns a +non-@code{nil} value, the index entry at point is ignored. This was +implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts +in the LaTeX2e @code{index} package. + +@var{repeat}, if non-@code{nil}, means the index macro does not typeset +the entry in the text, so that the text has to be repeated outside the +index macro. Needed for @code{reftex-index-selection-or-word} and for +indexing from the phrase buffer. + +The final entry may also be a symbol. It must have an association in +the variable @code{reftex-index-macros-builtin} to specify the main +indexing package you are using. Valid values are currently +@example +default @r{The LaTeX default - unnecessary to specify this one} +multind @r{The multind.sty package} +index @r{The index.sty package} +index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} + @r{Should not be used - only for old documents} +@end example +Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, +so with a sufficiently new version of AUCTeX, you should not set the +package here. +@end defopt + +@defopt reftex-index-default-macro +The default index macro for @code{reftex-index-selection-or-word}. +This is a list with @code{(@var{macro-key} @var{default-tag})}. + +@var{macro-key} is a character identifying an index macro - see +@code{reftex-index-macros}. + +@var{default-tag} is the tag to be used if the macro requires a +@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, +@b{Ref@TeX{}} will ask for it. When this is the empty string and the +TAG argument of the index macro is optional, the TAG argument will be +omitted. +@end defopt + +@defopt reftex-index-default-tag +Default index tag. When working with multiple indexes, RefTeX queries +for an index tag when creating index entries or displaying a specific +index. This variable controls the default offered for these queries. +The default can be selected with @key{RET} during selection or +completion. Valid values of this variable are: +@example +nil @r{Do not provide a default index} +"tag" @r{The default index tag given as a string, e.g. "idx"} +last @r{The last used index tag will be offered as default} +@end example +@end defopt + +@defopt reftex-index-math-format +Format of index entries when copied from inside math mode. When +@code{reftex-index-selection-or-word} is executed inside TeX math mode, +the index key copied from the buffer is processed with this format +string through the @code{format} function. This can be used to add the +math delimiters (e.g. @samp{$}) to the string. Requires the +@file{texmathp.el} library which is part of AUCTeX. +@end defopt + +@defopt reftex-index-phrase-file-extension +File extension for the index phrase file. This extension will be added +to the base name of the master file. +@end defopt + +@defopt reftex-index-phrases-logical-and-regexp +Regexp matching the @samp{and} operator for index arguments in phrases +file. When several index arguments in a phrase line are separated by +this operator, each part will generate an index macro. So each match of +the search phrase will produce @emph{several} different index entries. +Make sure this does no match things which are not separators. This +logical @samp{and} has higher priority than the logical @samp{or} +specified in @code{reftex-index-phrases-logical-or-regexp}. +@end defopt + +@defopt reftex-index-phrases-logical-or-regexp +Regexp matching the @samp{or} operator for index arguments in phrases +file. When several index arguments in a phrase line are separated by +this operator, the user will be asked to select one of them at each +match of the search phrase. The first index arg will be the default. A +number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make +sure this does no match things which are not separators. The logical +@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} +has higher priority than this logical @samp{or}. +@end defopt + +@defopt reftex-index-phrases-search-whole-words +Non-@code{nil} means phrases search will look for whole words, not subwords. +This works by requiring word boundaries at the beginning and end of +the search string. When the search phrase already has a non-word-char +at one of these points, no word boundary is required there. +@end defopt + +@defopt reftex-index-phrases-case-fold-search +Non-@code{nil} means, searching for index phrases will ignore +case. +@end defopt + +@defopt reftex-index-verify-function +A function which is called at each match during global indexing. +If the function returns nil, the current match is skipped. +@end defopt + +@defopt reftex-index-phrases-skip-indexed-matches +Non-@code{nil} means, skip matches which appear to be indexed already. +When doing global indexing from the phrases buffer, searches for some +phrases may match at places where that phrase was already indexed. In +particular when indexing an already processed document again, this +will even be the norm. When this variable is non-@code{nil}, +@b{Ref@TeX{}} checks if the match is an index macro argument, or if an +index macro is directly before or after the phrase. If that is the +case, that match will be ignored. +@end defopt + +@defopt reftex-index-phrases-wrap-long-lines +Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. +Inserting indexing commands in a line makes the line longer - often +so long that it does not fit onto the screen. When this variable is +non-@code{nil}, newlines will be added as necessary before and/or after the +indexing command to keep lines short. However, the matched text +phrase and its index command will always end up on a single line. +@end defopt + +@defopt reftex-index-phrases-sort-prefers-entry +Non-@code{nil} means when sorting phrase lines, the explicit index entry +is used. Phrase lines in the phrases buffer contain a search phrase, and +sorting is normally based on these. Some phrase lines also have +an explicit index argument specified. When this variable is +non-@code{nil}, the index argument will be used for sorting. +@end defopt + +@defopt reftex-index-phrases-sort-in-blocks +Non-@code{nil} means, empty and comment lines separate phrase buffer +into blocks. Sorting will then preserve blocks, so that lines are +re-arranged only within blocks. +@end defopt + +@defopt reftex-index-phrases-map +Keymap for the Index Phrases buffer. +@end defopt + +@defopt reftex-index-phrases-mode-hook +Normal hook which is run when a buffer is put into +@code{reftex-index-phrases-mode}. +@end defopt + +@defopt reftex-index-section-letters +The letters which denote sections in the index. Usually these are all +capital letters. Don't use any downcase letters. Order is not +significant, the index will be sorted by whatever the sort function +thinks is correct. In addition to these letters, @b{Ref@TeX{}} will +create a group @samp{!} which contains all entries sorted below the +lowest specified letter. In the @file{*Index*} buffer, pressing any of +these capital letters or @kbd{!} will jump to that section. +@end defopt + +@defopt reftex-index-include-context +Non-@code{nil} means, display the index definition context in the +@file{*Index*} buffer. This flag may also be toggled from the +@file{*Index*} buffer with the @kbd{c} key. +@end defopt + +@defopt reftex-index-follow-mode +Non-@code{nil} means, point in @file{*Index*} buffer will cause other +window to follow. The other window will show the corresponding part of +the document. This flag can be toggled from within the @file{*Index*} +buffer with the @kbd{f} key. +@end defopt + +@deffn Keymap reftex-index-map +The keymap which is active in the @file{*Index*} buffer +(@pxref{Index Support}). +@end deffn + +@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options +@section Viewing Cross-References +@cindex Options, viewing cross-references +@cindex Viewing cross-references, options + +@defopt reftex-view-crossref-extra +Macros which can be used for the display of cross references. +This is used when `reftex-view-crossref' is called with point in an +argument of a macro. Note that crossref viewing for citations, +references (both ways) and index entries is hard-coded. This variable +is only to configure additional structures for which crossreference +viewing can be useful. Each entry has the structure +@example +(@var{macro-re} @var{search-re} @var{highlight}). +@end example +@var{macro-re} is matched against the macro. @var{search-re} is the +regexp used to search for cross references. @samp{%s} in this regexp is +replaced with the macro argument at point. @var{highlight} is an +integer indicating which subgroup of the match should be highlighted. +@end defopt + +@defopt reftex-auto-view-crossref +Non-@code{nil} means, initially turn automatic viewing of crossref info +on. Automatic viewing of crossref info normally uses the echo area. +Whenever point is idle for more than @code{reftex-idle-time} seconds on +the argument of a @code{\ref} or @code{\cite} macro, and no other +message is being displayed, the echo area will display information about +that cross reference. You can also set the variable to the symbol +@code{window}. In this case a small temporary window is used for the +display. This feature can be turned on and off from the menu +(Ref->Options). +@end defopt + +@defopt reftex-idle-time +Time (secs) Emacs has to be idle before automatic crossref display +or toc recentering is done. +@end defopt + +@defopt reftex-cite-view-format +Citation format used to display citation info in the message area. See +the variable @code{reftex-cite-format} for possible percent +escapes. +@end defopt + +@defopt reftex-revisit-to-echo +Non-@code{nil} means, automatic citation display will revisit files if +necessary. When nil, citation display in echo area will only be active +for cached echo strings (see @code{reftex-cache-cite-echo}), or for +BibTeX database files which are already visited by a live associated +buffers. +@end defopt + +@defopt reftex-cache-cite-echo +Non-@code{nil} means, the information displayed in the echo area for +cite macros (see variable @code{reftex-auto-view-crossref}) is cached and +saved along with the parsing information. The cache survives document +scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. +@end defopt + +@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options +@section Finding Files +@cindex Options, Finding Files +@cindex Finding files, options + +@defopt reftex-texpath-environment-variables +List of specifications how to retrieve the search path for TeX files. +Several entries are possible. +@itemize @minus +@item +If an element is the name of an environment variable, its content is +used. +@item +If an element starts with an exclamation mark, it is used as a command +to retrieve the path. A typical command with the kpathsearch library +would be @w{@code{"!kpsewhich -show-path=.tex"}}. +@item +Otherwise the element itself is interpreted as a path. +@end itemize +Multiple directories can be separated by the system dependent +@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will +be expanded recursively. See also @code{reftex-use-external-file-finders}. +@end defopt + +@defopt reftex-bibpath-environment-variables +List of specifications how to retrieve the search path for BibTeX +files. Several entries are possible. +@itemize @minus +@item +If an element is the name of an environment variable, its content is +used. +@item +If an element starts with an exclamation mark, it is used as a command +to retrieve the path. A typical command with the kpathsearch library +would be @w{@code{"!kpsewhich -show-path=.bib"}}. +@item +Otherwise the element itself is interpreted as a path. +@end itemize +Multiple directories can be separated by the system dependent +@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will +be expanded recursively. See also @code{reftex-use-external-file-finders}. +@end defopt + +@defopt reftex-file-extensions +Association list with file extensions for different file types. +This is a list of items, each item is like: +@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} +@example +@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} +@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} +@var{other-ext}: @r{Any number of other valid extensions for this file type.} +@end example +When a files is searched and it does not have any of the valid extensions, +we try the default extension first, and then the naked file name. +@end defopt + +@defopt reftex-search-unrecursed-path-first +Non-@code{nil} means, search all specified directories before trying +recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, +then @samp{/tex/}, and then all subdirectories of @samp{./}. If this +option is @code{nil}, the subdirectories of @samp{./} are searched +before @samp{/tex/}. This is mainly for speed - most of the time the +recursive path is for the system files and not for the user files. Set +this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with +equal names in wrong sequence. +@end defopt + +@defopt reftex-use-external-file-finders +Non-@code{nil} means, use external programs to find files. Normally, +@b{Ref@TeX{}} searches the paths given in the environment variables +@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX +database files. With this option turned on, it calls an external +program specified in the option @code{reftex-external-file-finders} +instead. As a side effect, the variables +@code{reftex-texpath-environment-variables} and +@code{reftex-bibpath-environment-variables} will be ignored. +@end defopt + +@defopt reftex-external-file-finders +Association list with external programs to call for finding files. Each +entry is a cons cell @w{@code{(@var{type} . @var{program})}}. +@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a +string containing the external program to use with any arguments. +@code{%f} will be replaced by the name of the file to be found. Note +that these commands will be executed directly, not via a shell. Only +relevant when @code{reftex-use-external-file-finders} is +non-@code{nil}. +@end defopt + +@page +@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options +@section Optimizations +@cindex Options, optimizations +@cindex Optimizations, options + +@defopt reftex-keep-temporary-buffers +Non-@code{nil} means, keep buffers created for parsing and lookup. +@b{Ref@TeX{}} sometimes needs to visit files related to the current +document. We distinguish files visited for +@table @asis +@item PARSING +Parts of a multifile document loaded when (re)-parsing the +document. +@item LOOKUP +BibTeX database files and TeX files loaded to find a reference, to +display label context, etc. +@end table +The created buffers can be kept for later use, or be thrown away +immediately after use, depending on the value of this variable: + +@table @code +@item nil +Throw away as much as possible. +@item t +Keep everything. +@item 1 +Throw away buffers created for parsing, but keep the ones created for +lookup. +@end table + +If a buffer is to be kept, the file is visited normally (which is +potentially slow but will happen only once). If a buffer is to be thrown +away, the initialization of the buffer depends upon the variable +@code{reftex-initialize-temporary-buffers}. +@end defopt + +@defopt reftex-initialize-temporary-buffers +Non-@code{nil} means do initializations even when visiting file +temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and +other stuff to briefly visit a file. When @code{t}, the full default +initializations are done (@code{find-file-hook} etc.). Instead of +@code{t} or @code{nil}, this variable may also be a list of hook +functions to do a minimal initialization. +@end defopt + +@defopt reftex-no-include-regexps +List of regular expressions to exclude certain input files from parsing. +If the name of a file included via @code{\include} or @code{\input} is +matched by any of the regular expressions in this list, that file is not +parsed by @b{Ref@TeX{}}. +@end defopt + +@defopt reftex-enable-partial-scans +Non-@code{nil} means, re-parse only 1 file when asked to re-parse. +Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} +commands, or with the @kbd{r} key in menus. When this option is +@code{t} in a multifile document, we will only parse the current buffer, +or the file associated with the label or section heading near point in a +menu. Requesting re-parsing of an entire multifile document then +requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in +menus. +@end defopt + +@defopt reftex-save-parse-info +Non-@code{nil} means, save information gathered with parsing in files. +The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is +used to save the information. When this variable is @code{t}, +@itemize @minus +@item +accessing the parsing information for the first time in an editing +session will read that file (if available) instead of parsing the +document. +@item +exiting Emacs or killing a buffer in reftex-mode will cause a new +version of the file to be written. +@end itemize +@end defopt + +@defopt reftex-parse-file-extension +File extension for the file in which parser information is stored. +This extension is added to the base name of the master file. +@end defopt + +@defopt reftex-allow-automatic-rescan +Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems +necessary. Applies (currently) only in rare cases, when a new label +cannot be placed with certainty into the internal label list. +@end defopt + +@defopt reftex-use-multiple-selection-buffers +Non-@code{nil} means use a separate selection buffer for each label +type. These buffers are kept from one selection to the next and need +not to be created for each use - so the menu generally comes up faster. +The selection buffers will be erased (and therefore updated) +automatically when new labels in its category are added. See the +variable @code{reftex-auto-update-selection-buffers}. +@end defopt + +@defopt reftex-auto-update-selection-buffers +Non-@code{nil} means, selection buffers will be updated automatically. +When a new label is defined with @code{reftex-label}, all selection +buffers associated with that label category are emptied, in order to +force an update upon next use. When @code{nil}, the buffers are left +alone and have to be updated by hand, with the @kbd{g} key from the +label selection process. The value of this variable will only have any +effect when @code{reftex-use-multiple-selection-buffers} is +non-@code{nil}. +@end defopt + +@node Options (Fontification), Options (Misc), Options (Optimizations), Options +@section Fontification +@cindex Options, fontification +@cindex Fontification, options + +@defopt reftex-use-fonts +Non-@code{nil} means, use fonts in label menu and on-the-fly help. +Font-lock must be loaded as well to actually get fontified +display. After changing this option, a rescan may be necessary to +activate it. +@end defopt + +@defopt reftex-refontify-context +Non-@code{nil} means, re-fontify the context in the label menu with +font-lock. This slightly slows down the creation of the label menu. It +is only necessary when you definitely want the context fontified. + +This option may have 3 different values: +@table @code +@item nil +Never refontify. +@item t +Always refontify. +@item 1 +Refontify when necessary, e.g. with old versions of the x-symbol +package. +@end table +The option is ignored when @code{reftex-use-fonts} is @code{nil}. +@end defopt + +@defopt reftex-highlight-selection +Non-@code{nil} means, highlight selected text in selection and +@file{*toc*} buffers. Normally, the text near the cursor is the +@emph{selected} text, and it is highlighted. This is the entry most +keys in the selection and @file{*toc*} buffers act on. However, if you +mainly use the mouse to select an item, you may find it nice to have +mouse-triggered highlighting @emph{instead} or @emph{as well}. The +variable may have one of these values: + +@example +nil @r{No highlighting.} +cursor @r{Highlighting is cursor driven.} +mouse @r{Highlighting is mouse driven.} +both @r{Both cursor and mouse trigger highlighting.} +@end example + +Changing this variable requires to rebuild the selection and *toc* +buffers to become effective (keys @kbd{g} or @kbd{r}). +@end defopt + +@defopt reftex-cursor-selected-face +Face name to highlight cursor selected item in toc and selection buffers. +See also the variable @code{reftex-highlight-selection}. +@end defopt +@defopt reftex-mouse-selected-face +Face name to highlight mouse selected item in toc and selection buffers. +See also the variable @code{reftex-highlight-selection}. +@end defopt +@defopt reftex-file-boundary-face +Face name for file boundaries in selection buffer. +@end defopt +@defopt reftex-label-face +Face name for labels in selection buffer. +@end defopt +@defopt reftex-section-heading-face +Face name for section headings in toc and selection buffers. +@end defopt +@defopt reftex-toc-header-face +Face name for the header of a toc buffer. +@end defopt +@defopt reftex-bib-author-face +Face name for author names in bib selection buffer. +@end defopt +@defopt reftex-bib-year-face +Face name for year in bib selection buffer. +@end defopt +@defopt reftex-bib-title-face +Face name for article title in bib selection buffer. +@end defopt +@defopt reftex-bib-extra-face +Face name for bibliographic information in bib selection buffer. +@end defopt +@defopt reftex-select-mark-face +Face name for marked entries in the selection buffers. +@end defopt +@defopt reftex-index-header-face +Face name for the header of an index buffer. +@end defopt +@defopt reftex-index-section-face +Face name for the start of a new letter section in the index. +@end defopt +@defopt reftex-index-tag-face +Face name for index names (for multiple indices). +@end defopt +@defopt reftex-index-face +Face name for index entries. +@end defopt + +@node Options (Misc), , Options (Fontification), Options +@section Miscellaneous +@cindex Options, misc + +@defopt reftex-extra-bindings +Non-@code{nil} means, make additional key bindings on startup. These +extra bindings are located in the users @samp{C-c letter} +map. @xref{Key Bindings}. +@end defopt + +@defopt reftex-plug-into-AUCTeX +Plug-in flags for AUCTeX interface. This variable is a list of +5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} +will + +@example +- supply labels in new sections and environments (flag 1) +- supply arguments for macros like @code{\label} (flag 2) +- supply arguments for macros like @code{\ref} (flag 3) +- supply arguments for macros like @code{\cite} (flag 4) +- supply arguments for macros like @code{\index} (flag 5) +@end example + +You may also set the variable itself to t or nil in order to turn all +options on or off, respectively.@* +Supplying labels in new sections and environments applies when creating +sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* +Supplying macro arguments applies when you insert such a macro +interactively with @kbd{C-c @key{RET}}.@* +See the AUCTeX documentation for more information. +@end defopt + +@defopt reftex-revisit-to-follow +Non-@code{nil} means, follow-mode will revisit files if necessary. +When nil, follow-mode will be suspended for stuff in unvisited files. +@end defopt + +@defopt reftex-allow-detached-macro-args +Non-@code{nil} means, allow arguments of macros to be detached by +whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb +[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that +this will be the case even if @code{\bb} is defined with zero or one +argument. +@end defopt + +@node Keymaps and Hooks, Changes, Options, Top +@section Keymaps and Hooks +@cindex Keymaps + +@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. + +@deffn Keymap reftex-mode-map +The keymap for @b{Ref@TeX{}} mode. +@end deffn + +@deffn {Normal Hook} reftex-load-hook +Normal hook which is being run when loading @file{reftex.el}. +@end deffn + +@deffn {Normal Hook} reftex-mode-hook +Normal hook which is being run when turning on @b{Ref@TeX{}} mode. +@end deffn + +Furthermore, the 4 modes used for referencing labels, creating +citations, the table of contents buffer and the phrases buffer have +their own keymaps and mode hooks. See the respective sections. There +are many more hooks which are described in the relevant sections about +options for a specific part of @b{Ref@TeX{}}. + +@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top +@chapter Changes +@cindex Changes + +Here is a list of recent changes to @b{Ref@TeX{}}. + +@noindent @b{Version 4.28} +@itemize @bullet +@item Support for the Jurabib package. +@item Improvements when selecting several items in a selection buffer. +@end itemize + +@noindent @b{Version 4.26} +@itemize @bullet +@item +Support for global incremental search. +@item +Some improvements for XEmacs compatibility. +@end itemize + +@noindent @b{Version 4.25} +@itemize @bullet +@item +Fixed bug with @samp{%F} in a label prefix. Added new escapes +@samp{%m} and @samp{%M} for mater file name and master directory. +@end itemize + +@noindent @b{Version 4.24} +@itemize @bullet +@item +Inserting citation commands now prompts for optional arguments +when called with a prefix argument. Related new options are +@code{reftex-cite-prompt-optional-args} and +@code{reftex-cite-cleanup-optional-args}. +@item +New option @code{reftex-trust-label-prefix}. Configure this variable +if you'd like RefTeX to base its classification of labels on prefixes. +This can speed-up document parsing, but may in some cases reduce the +quality of the context used by RefTeX to describe a label. +@item +Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} +is non-nil. +@item +Fixed bugs in indexing: Case-sensitive search, quotes before and/or +after words. Disabled indexing in comment lines. +@end itemize + +@noindent @b{Version 4.22} +@itemize @bullet +@item +New command @code{reftex-create-bibtex-file} to create a new database +with all entries referenced in the current document. +@item +New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file +from entries marked in a citation selection buffer. +@end itemize + +@noindent @b{Version 4.21} +@itemize @bullet +@item +Renaming labels from the toc buffer with key @kbd{M-%}. +@end itemize + +@noindent @b{Version 4.20} +@itemize @bullet +@item +Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in +the TOC buffer promote/demote the section at point or all sections in +the current region. +@item +New option @code{reftex-toc-split-windows-fraction} to set the size of +the window used by the TOC. This makes the old variable +@code{reftex-toc-split-windows-horizontally-fraction} obsolete. +@item +A dedicated frame can show the TOC with the current section +always automatically highlighted. The frame is created and +deleted from the toc buffer with the @kbd{d} key. +@end itemize + +@noindent @b{Version 4.19} +@itemize @bullet +@item +New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current +section in the TOC buffer without selecting the TOC window. +@item +Recentering happens automatically in idle time when the option +@code{reftex-auto-recenter-toc} is turned on. +@item +Fixed several bugs related to automatic cursor positioning in the TOC +buffer. +@item +The highlight in the TOC buffer stays when the focus moves to a +different window. +@item +New command `reftex-goto-label'. +@item +Part numbers are no longer included in chapter numbers, and a new +part does not reset the chapter counter. See new option +@code{reftex-part-resets-chapter}. +@end itemize + +@noindent @b{Version 4.18} +@itemize @bullet +@item +@code{reftex-citation} uses the word before the cursor as a default +search string. +@item +Simplified several regular expressions for speed. +@item +Better support for chapterbib. +@end itemize + +@noindent @b{Version 4.17} +@itemize @bullet +@item +The toc window can be split off horizontally. See new options +@code{reftex-toc-split-windows-horizontally}, +@code{reftex-toc-split-windows-horizontally-fraction}. +@item +It is possible to specify a function which verifies an index match +during global indexing. See new option @code{reftex-index-verify-function}. +@item +The macros which input a file in LaTeX (like \input, \include) can +be configured. See new option @code{reftex-include-file-commands}. +@item +The macros which specify the bibliography file (like \bibliography) can +be configured. See new option @code{reftex-bibliography-commands}. +@item +The regular expression used to search for the \bibliography macro has +been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by +chapterbib. +@item +Small bug fixes. +@end itemize + +@noindent @b{Version 4.15} +@itemize @bullet +@item +Fixed bug with parsing of BibTeX files, when fields contain quotes or +unmatched parenthesis. +@item +Small bug fixes. +@item +Improved interaction with Emacs LaTeX mode. +@end itemize + +@noindent @b{Version 4.12} +@itemize @bullet +@item +Support for @file{bibentry} citation style. +@end itemize + +@noindent @b{Version 4.11} +@itemize @bullet +@item +Fixed bug which would parse @samp{\Section} just like @samp{\section}. +@end itemize + +@noindent @b{Version 4.10} +@itemize @bullet +@item +Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict +with @file{reftex-vars.el} on DOS machines. +@item +New options @code{reftex-parse-file-extension} and +@code{reftex-index-phrase-file-extension}. +@end itemize + +@noindent [.....] +@ignore +@noindent @b{Version 4.09} +@itemize @bullet +@item +New option @code{reftex-toc-max-level} to limit the depth of the toc. +New key binding @kbd{t} in the @file{*toc*} buffer to change this +setting. +@item +RefTeX maintains an @file{Index Phrases} file in which phrases can be +collected. When the document is ready, RefTeX can search all +these phrases and assist indexing all matches. +@item +The variables @code{reftex-index-macros} and +@code{reftex-index-default-macro} have changed their syntax slightly. +The @var{repeat} parameter has move from the latter to the former. +Also calls to @code{reftex-add-index-macros} from AUCTeX style files +need to be adapted. +@item +The variable @code{reftex-section-levels} no longer contains the +default stuff which has been moved to a constant. +@item +Environments like theorems can be placed into the TOC by putting +entries for @samp{"begin@{theorem@}"} in +@code{reftex-setion-levels}. +@end itemize + +@noindent @b{Version 4.06} +@itemize @bullet +@item +@code{reftex-section-levels} can contain a function to compute the level +of a sectioning command. +@item +Multiple @code{thebibliography} environments recognized. +@end itemize + +@noindent @b{Version 4.04} +@itemize @bullet +@item +New option @code{reftex-index-default-tag} implements a default for queries. +@end itemize + +@noindent @b{Version 4.02} +@itemize @bullet +@item +macros ending in @samp{refrange} are considered to contain references. +@item +Index entries made with @code{reftex-index-selection-or-word} in TeX +math mode automatically get enclosing @samp{$} to preserve math mode. See +new option @code{reftex-index-math-format}. Requires AUCTeX. +@end itemize + +@noindent @b{Version 4.01} +@itemize @bullet +@item +New command @code{reftex-index-globally} to index a word in many +places in the document. Also available from the index buffer with +@kbd{&}. +@item +The first item in a @code{reftex-label-alist} entry may now also be a parser +function to do non-standard parsing. +@item +@code{reftex-auto-view-crossref} no longer interferes with +@code{pop-up-frames} (patch from Stefan Monnier). +@end itemize + +@noindent @b{Version 4.00} +@itemize @bullet +@item +RefTeX has been split into several smaller files which are autoloaded on +demand. +@item +Index support, along with many new options. +@item +The selection of keys for @code{\ref} and @code{\cite} now allows to +select multiple items by marking entries with the @kbd{m} key. +@item +Fancyref support. +@end itemize + +@noindent @b{Version 3.43} +@itemize @bullet +@item +Viewing cross-references generalized. Now works on @code{\label}, +@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of +these, and from BibTeX buffers. +@item +New option @code{reftex-view-crossref-extra}. +@item +Support for the additional sectioning commands @code{\addchap} and +@code{\addsec} which are defined in the LaTeX KOMA-Script classes. +@item +Files in @code{reftex-default-bibliography} will be searched along +@code{BIBINPUTS} path. +@item +Reading a parse file now checks consistency. +@end itemize + +@noindent @b{Version 3.42} +@itemize @bullet +@item +File search further refined. New option @code{reftex-file-extensions}. +@item +@file{*toc*} buffer can show the file boundaries of a multifile +document, all labels and associated context. New keys @kbd{i}, @kbd{l}, +and @kbd{c}. New options @code{reftex-toc-include-labels}, +@code{reftex-toc-include-context}, +@code{reftex-toc-include-file-boundaries}. +@end itemize + +@noindent @b{Version 3.41} +@itemize @bullet +@item +New options @code{reftex-texpath-environment-variables}, +@code{reftex-use-external-file-finders}, +@code{reftex-external-file-finders}, +@code{reftex-search-unrecursed-path-first}. +@item +@emph{kpathsearch} support. See new options and +@code{reftex-bibpath-environment-variables}. +@end itemize + +@noindent @b{Version 3.38} +@itemize @bullet +@item +@code{reftex-view-crossref} no longer moves to find a macro. Point has +to be on the macro argument. +@end itemize + +@noindent @b{Version 3.36} +@itemize @bullet +@item +New value @code{window} for option @code{reftex-auto-view-crossref}. +@end itemize + +@noindent @b{Version 3.35} +@itemize @bullet +@item +ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. +This takes back the related changes in 3.34 for safety reasons. +@end itemize + +@noindent @b{Version 3.34} +@itemize @bullet +@item +Additional flag in @code{reftex-derive-label-parameters} do make only +lowercase labels (default @code{t}). +@item +All @file{.rel} files have a final newline to avoid queries. +@item +Single byte representations of accented European letters (ISO-8859-1) +are now valid in labels. +@end itemize + +@noindent @b{Version 3.33} +@itemize @bullet +@item +Multiple selection buffers are now hidden buffers (they start with a +SPACE). +@item +Fixed bug with file search when TEXINPUTS environment variable is empty. +@end itemize + +@noindent @b{Version 3.30} +@itemize @bullet +@item +In @code{reftex-citation}, the regular expression used to scan BibTeX +files can be specified using completion on known citation keys. +@item +New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} +entries. +@item +New command @code{reftex-renumber-simple-labels} to renumber simple +labels like @samp{eq:13} sequentially through a document. +@end itemize + +@noindent @b{Version 3.28} +@itemize @bullet +@item +Auto view crossref for XEmacs uses @code{post-command-hook} to restart the +timer, since itimer restart is not reliable. +@item +Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. +@item +Expansion of recursive tex and bib path rewritten. +@item +Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. +@item +Fixed bug with section numbering after *-red sections. +@end itemize + +@noindent @b{Version 3.27} +@itemize @bullet +@item +Macros can define @emph{neutral} labels, just like @code{\label} +itself. +@item +New option @code{reftex-allow-detached-macro-args}, default @code{nil}! +@end itemize + +@noindent @b{Version 3.26} +@itemize @bullet +@item +[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. +@item +New hooks @code{reftex-translate-to-ascii-function}, +@code{reftex-string-to-label-function}. +@item +Made sure automatic crossref display will not visit/scan files. +@end itemize + +@noindent @b{Version 3.25} +@itemize @bullet +@item +Echoing of citation info caches the info for displayed entries. +New option @code{reftex-cache-cite-echo}. +@item +@kbd{M-x reftex-reset-mode} now also removes the file with parsing +info. +@item +Default of @code{reftex-revisit-to-follow} changed to nil. +@end itemize + +@noindent @b{Version 3.24} +@itemize @bullet +@item +New option @code{reftex-revisit-to-echo}. +@item +Interface with X-Symbol (>=2.6) is now complete and stable. +@item +Adapted to new outline, which uses overlays. +@item +File names in @code{\bibliography} may now have the @code{.bib} +extension. +@item +Fixed Bug with parsing "single file" from master file buffer. +@end itemize + +@noindent @b{Version 3.23} +@itemize @bullet +@item +Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. +@item +@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse +file. +@item +The cursor inside a @code{\ref} or @code{\cite} macro can now trigger +automatic display of crossref information in the echo area. See +variable @code{reftex-auto-view-crossref}. +@item +AUCTeX interface updates: +@itemize @minus +@item +AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. +@item +@b{Ref@TeX{}} notifies AUCTeX about new labels. +@item +@code{TeX-arg-ref} no longer used (introduction was unnecessary). +@item +@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. +@item +Settings added to @b{Ref@TeX{}} via style files remain local. +@end itemize +@item +Fixed bug with @code{reftex-citation} in non-latex buffers. +@item +Fixed bug with syntax table and context refontification. +@item +Safety-net for name change of @code{font-lock-reference-face}. +@end itemize + +@noindent @b{Version 3.22} +@itemize @bullet +@item +Fixed bug with empty context strings. +@item +@code{reftex-mouse-view-crossref} is now bound by default at +@kbd{S-mouse-2}. +@end itemize + +@noindent @b{Version 3.21} +@itemize @bullet +@item +New options for all faces used by @b{Ref@TeX{}}. They're in the +customization group @code{reftex-fontification-configurations}. +@end itemize + +@noindent @b{Version 3.19} +@itemize @bullet +@item +Fixed bug with AUCTeX @code{TeX-master}. +@end itemize + +@noindent @b{Version 3.18} +@itemize @bullet +@item +The selection now uses a recursive edit, much like minibuffer input. +This removes all restrictions during selection. E.g. you can now +switch buffers at will, use the mouse etc. +@item +New option @code{reftex-highlight-selection}. +@item +@kbd{mouse-2} can be used to select in selection and @file{*toc*} +buffers. +@item +Fixed some problems regarding the interaction with VIPER mode. +@item +Follow-mode is now only used after point motion. +@item +@b{Ref@TeX{}} now finally does not fontify temporary files anymore. +@end itemize + +@noindent @b{Version 3.17} +@itemize @bullet +@item +Additional bindings in selection and @file{*toc*} buffers. @kbd{g} +redefined. +@item +New command @code{reftex-save-all-document-buffers}. +@item +Magic word matching made more intelligent. +@item +Selection process can switch to completion (with @key{TAB}). +@item +@code{\appendix} is now recognized and influences section numbering. +@item +File commentary shortened considerably (use Info documentation). +@item +New option @code{reftex-no-include-regexps} to skip some include files. +@item +New option @code{reftex-revisit-to-follow}. +@end itemize + +@noindent @b{Version 3.16} +@itemize @bullet +@item +New hooks @code{reftex-format-label-function}, +@code{reftex-format-ref-function}, @code{reftex-format-cite-function}. +@item +TeXInfo documentation completed. +@item +Some restrictions in Label inserting and referencing removed. +@item +New variable @code{reftex-default-bibliography}. +@end itemize + +@noindent @b{Version 3.14} +@itemize @bullet +@item +Selection buffers can be kept between selections: this is faster. +See new variable @code{reftex-use-multiple-selection-buffers}. +@item +Prefix interpretation of reftex-view-crossref changed. +@item +Support for the @code{varioref} package (@kbd{v} key in selection +buffer). +@end itemize + +@noindent @b{Version 3.12} +@itemize @bullet +@item +There are 3 new keymaps for customization: @code{reftex-toc-map}, +@code{reftex-select-label-map}, @code{reftex-select-bib-map}. +@item +Refontification uses more standard font-lock stuff. +@item +When no BibTeX database files are specified, citations can also use +@code{\bibitem} entries from a @code{thebibliography} environment. +@end itemize + +@noindent @b{Version 3.11} +@itemize @bullet +@item +Fixed bug which led to naked label in (e.g.) footnotes. +@item +Added scroll-other-window functions to RefTeX-Select. +@end itemize + +@noindent @b{Version 3.10} +@itemize @bullet +@item +Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. +@item +Removed unimportant code which caused OS/2 Emacs to crash. +@item +All customization variables now accessible from menu. +@end itemize + +@noindent @b{Version 3.07} +@itemize @bullet +@item +@code{Ref} menu improved. +@end itemize + +@noindent @b{Version 3.05} +@itemize @bullet +@item +Compatibility code now first checks for XEmacs feature. +@end itemize + +@noindent @b{Version 3.04} +@itemize @bullet +@item +Fixed BUG in the @emph{xr} support. +@end itemize + +@noindent @b{Version 3.03} +@itemize @bullet +@item +Support for the LaTeX package @code{xr}, for inter-document +references. +@item +A few (minor) Mule-related changes. +@item +Fixed bug which could cause @emph{huge} @file{.rel} files. +@item +Search for input and @file{.bib} files with recursive path definitions. +@end itemize + +@noindent @b{Version 3.00} +@itemize @bullet +@item +@b{Ref@TeX{}} should work better for very large projects: +@item +The new parser works without creating a master buffer. +@item +Rescanning can be limited to a part of a multifile document. +@item +Information from the parser can be stored in a file. +@item +@b{Ref@TeX{}} can deal with macros having a naked label as an argument. +@item +Macros may have white space and newlines between arguments. +@item +Multiple identical section headings no longer confuse +@code{reftex-toc}. +@item +@b{Ref@TeX{}} should work correctly in combination with buffer-altering +packages like outline, folding, x-symbol, iso-cvt, isotex, etc. +@item +All labeled environments discussed in @emph{The LaTeX Companion} by +Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of +@b{Ref@TeX{}}'s defaults. +@end itemize + +@noindent @b{Version 2.17} +@itemize @bullet +@item +Label prefix expands % escapes with current file name and other stuff. +@item +Citation format now with % escapes. This is not backward +compatible! +@item +TEXINPUTS variable recognized when looking for input files. +@item +Context can be the nth argument of a macro. +@item +Searching in the select buffer is now possible (@kbd{C-s} and +@kbd{C-r}). +@item +Display and derive-label can use two different context methods. +@item +AMSmath @code{xalignat} and @code{xxalignat} added. +@end itemize + +@noindent @b{Version 2.14} +@itemize @bullet +@item +Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with +AUCTeX. +@end itemize + +@noindent @b{Version 2.11} +@itemize @bullet +@item +Submitted for inclusion to Emacs and XEmacs. +@end itemize + +@noindent @b{Version 2.07} +@itemize @bullet +@item +New functions @code{reftex-search-document}, +@code{reftex-query-replace-document}. +@end itemize + +@noindent @b{Version 2.05} +@itemize @bullet +@item +Support for @file{custom.el}. +@item +New function @code{reftex-grep-document} (thanks to Stephen Eglen). +@end itemize + +@noindent @b{Version 2.03} +@itemize @bullet +@item +@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to +default environments. +@item +@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). +@item +New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, +@code{reftex-arg-cite}. +@item +Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is +required. +@item +@code{reftex-add-to-label-alist} (to be called from AUCTeX style +files). +@item +Finding context with a hook function. +@item +Sorting BibTeX entries (new variable: +@code{reftex-sort-bibtex-matches}). +@end itemize + +@noindent @b{Version 2.00} +@itemize @bullet +@item +Labels can be derived from context (default for sections). +@item +Configuration of label insertion and label referencing revised. +@item +Crossref fields in BibTeX database entries. +@item +@code{reftex-toc} introduced (thanks to Stephen Eglen). +@end itemize + +@noindent @b{Version 1.09} +@itemize @bullet +@item +Support for @code{tex-main-file}, an analogue for +@code{TeX-master}. +@item +MS-DOS support. +@end itemize + +@noindent @b{Version 1.07} +@itemize @bullet +@item +@b{Ref@TeX{}} gets its own menu. +@end itemize + +@noindent @b{Version 1.05} +@itemize @bullet +@item +XEmacs port. +@end itemize + +@noindent @b{Version 1.04} +@itemize @bullet +@item +Macros as wrappers, AMSTeX support, delayed context parsing for +new labels. +@end itemize +@end ignore + +@noindent @b{Version 1.00} +@itemize @bullet +@item +released on 7 Jan 1997. +@end itemize + +@node GNU Free Documentation License, Index, Changes, Top +@appendix GNU Free Documentation License +@include doclicense.texi + +@node Index, , GNU Free Documentation License, Top +@unnumbered Index +@printindex cp + +@summarycontents +@contents +@bye + +@ignore + arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43 +@end ignore