\input texinfo @c -*-texinfo-*-@c %**start of header@setfilename ../info/reftex@settitle RefTeX User Manual@dircategory Emacs@direntry* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.@end direntry@synindex ky cp@syncodeindex vr cp@syncodeindex fn cp@set VERSION 4.16@set EDITION 4.16@set DATE June 2001@set AUTHOR Carsten Dominik@set AUTHOR-EMAIL dominik@@astro.uva.nl@set MAINTAINER Carsten Dominik@set MAINTAINER-EMAIL dominik@@astro.uva.nl@c %**end of header@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@ifinfoThis file documents @b{Ref@TeX{}}, a package to do labels, references,citations and indices for LaTeX documents with Emacs.@refillThis is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for@b{Ref@TeX{}} @value{VERSION}@refillCopyright (c) 1997, 1998, 1999, 2000 2001 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end ifinfo@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@pageCopyright @copyright{} 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.@sp 2This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for@b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill@sp 2Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end titlepage@page@ifnottex@node Top,,,(dir)@b{Ref@TeX{}} is a package for managing Labels, References,Citations and index entries with GNU Emacs.@refillDon'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 aNutshell}). You can go back later to other parts of this document whenneeded.@refill@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.The Index* Index:: The full index.@detailmenuIntroduction* 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.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 documentOptions, 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{}} wrapsitself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},and @code{\index}. Using these macros usually requires looking updifferent parts of the document and searching through BibTeX databasefiles. @b{Ref@TeX{}} automates these time--consuming tasks almostentirely. It also provides functions to display the structure of adocument and to move around in this structure quickly.@refill@iftexDon'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 besummarized on two pages (@pxref{RefTeX in a Nutshell}). You can goback later to other parts of this document when needed.@end iftex@xref{Imprint}, for information about who to contact for help, bugreports 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. XEmacs21.x users want to install the corresponding plug-in package which isavailable from the@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}. Seethe XEmacs 21.x documentation on package installation fordetails.@refillUsers of earlier Emacs distributions (including Emacs 19) can get a copyof the @b{Ref@TeX{}} distribution from the maintainers web-page.@xref{Imprint}, for more information.@refill@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 multifiledocument, and the BibTeX database files requested by the@code{\bibliography} command. To find these files, @b{Ref@TeX{}} willrequire a search path, i.e. a list of directories to check. Normallythis list is stored in the environment variables @code{TEXINPUTS} and@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on somesystems 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-hookTo 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 LaTeXfiles, add the following lines to your @file{.emacs} file:@refill@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 showa table of contents of the document. This buffer can display sections,labels and index entries defined in the document. From the buffer, youcan jump quickly to every part of your document. Press @kbd{?} to gethelp.@refill@item@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labelsand to find the correct key for references quickly. It distinguisheslabels for different environments, knows about all standardenvironments (and many others), and can be configured to recognize anyadditional labeled environments you have defined yourself (variable@code{reftex-label-alist}).@refill@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@itemderive a label from context (default for section labels)@itemprompt for a label string (default for figures and tables) or@item insert a simple label made of a prefix and a number (all otherenvironments)@refill@end itemize@noindentWhich labels are created how is configurable with the variable@code{reftex-insert-label-flags}.@refill@item@b{Referencing Labels}@* To make a reference, type @kbd{C-c )}(@code{reftex-reference}). This shows an outline of the document withall labels of a certain type (figure, equation,...) and some labelcontext. Selecting a label inserts a @code{\ref@{@var{label}@}} macrointo the original buffer.@refill@end itemize@item@b{Citations}@*Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify aregular expression to search in current BibTeX database files (asspecified in the @code{\bibliography} command) and pull out a list ofmatches for you to choose from. The list is @emph{formatted} andsorted. The selected article is referenced as @samp{\cite@{@var{key}@}}(see the variable @code{reftex-cite-format} if you want to insertdifferent macros).@refill@item@b{Index Support}@*@b{Ref@TeX{}} helps to enter index entries. It also compiles allentries into an alphabetically sorted @file{*Index*} buffer which youcan use to check and edit the entries. @b{Ref@TeX{}} knows about thestandard index macros and can be configured to recognize any additionalmacros you have defined (@code{reftex-index-macros}). Multiple indicesare supported.@refill@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 entrytype @kbd{C-c <} (@code{reftex-index}), select any of the index macrosand enter the arguments with completion.@refill@item@b{The Index Phrases File (Delayed Indexing)}@*Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to addthe current word or selection to a special @emph{index phrase file}.@b{Ref@TeX{}} can later search the document for occurrences of thesephrases and let you interactively index the matches.@refill@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 editall entries.@refill@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, youcan press @kbd{C-c &} (@code{reftex-view-crossref}) to displaycorresponding locations in the document and associated BibTeX databasefiles.@refill @*When the enclosing macro is @code{\cite} or @code{\ref} and no othermessage occupies the echo area, information about the citation or labelwill automatically be displayed in the echo area.@refill@item@b{Multifile Documents}@*Multifile Documents are fully supported. The included files must have afile variable @code{TeX-master} or @code{tex-main-file} pointing to themaster file. @b{Ref@TeX{}} provides cross-referencing information fromall parts of the document, and across document borders(@file{xr.sty}).@refill@item@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document inorder to find labels and other information. It does it automaticallyonce and updates its list internally when @code{reftex-label} and@code{reftex-index} are used. To enforce reparsing, call any of thecommands described above with a raw @kbd{C-u} prefix, or press the@kbd{r} key in the label selection buffer, the table of contentsbuffer, or the index buffer.@refill@item@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} cancooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeXcontains style files which trigger appropriate settings in@b{Ref@TeX{}}, so that for many of the popular LaTeX packages noadditional customizations will be necessary.@refill@item@b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,try these:@refill@lisp(setq reftex-enable-partial-scans t)(setq reftex-save-parse-info t)(setq reftex-use-multiple-selection-buffers t)@end lispTo integrate with AUCTeX, use@lisp(setq reftex-plug-into-AUCTeX t)@end lispTo make your own LaTeX macro definitions known to @b{Ref@TeX{}},customize the variables@refill@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 exampleIf you have a large number of macros defined, you may want to writean AUCTeX style file to support them with both AUCTeX and@b{Ref@TeX{}}.@refill@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menusuntil you have picked up the key bindings. For an overview of what youcan do in each of the different special buffers, press @kbd{?}. Readthe manual if you get stuck, of if you are curious what else might beavailable. The first part of the manual explains ina tutorial way how to use and customize @b{Ref@TeX{}}. The secondpart is a command and variable reference.@refill @end enumerate@node Table of Contents, Labels and References, Introduction, Top@chapter Table of Contents@cindex @file{*toc*} buffer@cindex Table of contents buffer@findex reftex-toc@kindex C-c =Pressing the keys @kbd{C-c =} pops up a buffer showing the table ofcontents of the document. By default, this @file{*toc*} buffer showsonly the sections of a document. Using the @kbd{l} and @kbd{i} keys youcan display all labels and index entries defined in the document aswell.@refillWith the cursor in any of the lines denoting a location in thedocument, simple key strokes will display the corresponding part inanother window, jump to that location, or perform other actions.@refill@kindex ?Here is a list of special commands in the @file{*toc*} buffer. Asummary of this information is always available by pressing@kbd{?}.@refill@table @kbd@tablesubheading{General}@item ?Display a summary of commands.@item 0-9, -Prefix argument.@tablesubheading{Moving around}@item nGoto next entry in the table of context.@item pGoto previous entry in the table of context.@item C-c C-nGoto next section heading. Useful when many labels and index entriesseparate section headings.@refill@item C-c C-pGoto previous section heading.@item N zJump to section N, using the prefix arg. For example, @kbd{3 z} jumpsto section 3.@refill@tablesubheading{Access to document locations}@item @key{SPC}Show the corresponding location in another window. This command does@emph{not} select that other window.@refill@item @key{TAB}Goto the location in another window.@item @key{RET}Go to the location and hide the @file{*toc*} buffer. This will restorethe window configuration before @code{reftex-toc} (@kbd{C-c =}) wascalled.@refill@item mouse-2@vindex reftex-highlight-selectionClicking with mouse button 2 on a line has the same effect as @key{RET}.See also variable @code{reftex-highlight-selection}, @ref{Options(Fontification)}.@refill@item f@vindex reftex-toc-follow-mode@vindex reftex-revisit-to-followToggle follow mode. When follow mode is active, the other window willalways show the location corresponding to the line at point in the@file{*toc*} buffer. This is similar to pressing @key{SPC} after eachcursor motion. The default for this flag can be set with the variable@code{reftex-toc-follow-mode}. Note that only context in files alreadyvisited is shown. @b{Ref@TeX{}} will not visit a file just for followmode. See, however, the variable@code{reftex-revisit-to-follow}.@refill@item .Show calling point in another window. This is the point from where@code{reftex-toc} was last called.@tablesubheading{Exiting}@item qHide the @file{*toc*} buffer, return to the position where@code{reftex-toc} was last called.@refill@item kKill the @file{*toc*} buffer, return to the position where@code{reftex-toc} was last called.@refill@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-levelChange the maximum level of toc entries displayed in the @file{*toc*}buffer. Without prefix arg, all levels will be included. With prefixarg (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 defaultdepth can be configured with the variable@code{reftex-toc-max-level}.@refill@item F@vindex reftex-toc-include-file-boundariesToggle the display of the file borders of a multifile document in the@file{*toc*} buffer. The default for this flag can be set with thevariable @code{reftex-toc-include-file-boundaries}.@refill@item l@vindex reftex-toc-include-labelsToggle the display of labels in the @file{*toc*} buffer. The defaultfor 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 ofthe selected type in the @file{*toc*} buffer. The mode line @samp{L<>}indicator shows which labels are included.@refill@item i@vindex reftex-toc-include-index-entriesToggle the display of index entries in the @file{*toc*} buffer. Thedefault for this flag can be set with the variable@code{reftex-toc-include-index-entries}. When called with a prefixargument, @b{Ref@TeX{}} will prompt for a specific index and includeonly entries in the selected index in the @file{*toc*} buffer. The mode line @samp{I<>} indicator shows which index is used.@refill@item c@vindex reftex-toc-include-contextToggle 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}.@refill@tablesubheading{Updating the buffer}@item gRebuild the @file{*toc*} buffer. This does @emph{not} rescan thedocument.@refill@item r@vindex reftex-enable-partial-scansReparse the LaTeX document and rebuild the @file{*toc*} buffer. When@code{reftex-enable-partial-scans} is non-nil, rescan only the file thislocation is defined in, not the entire document.@refill@item C-u rReparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}buffer.@refill@item xSwitch to the @file{*toc*} buffer of an external document. When thecurrent document is using the @code{xr} package (@pxref{xr (LaTeXpackage)}), @b{Ref@TeX{}} will switch to one of the externaldocuments.@refill@end table@vindex reftex-toc-mapIn order to define additional commands for the @file{*toc*} buffer, thekeymap @code{reftex-toc-map} may be used.@refill@cindex Sectioning commands@cindex KOMA-Script, LaTeX classes@cindex LaTeX classes, KOMA-Script@cindex TOC entries for environments@vindex reftex-section-levelsThe section macros recognized by @b{Ref@TeX{}} are all LaTeX sectionmacros (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 LaTeXenvironments to the table of contents. This is probably only useful fortheorem-like environments. @xref{Defining Label Environments}, for anexample.@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 adocument. When writing a document, any part of it can be marked with alabel, like @samp{\label@{mark@}}. LaTeX records the current value of acertain counter when a label is defined. Later references to this label(like @samp{\ref@{mark@}}) will produce the recorded value of thecounter.@refillLabels can be used to mark sections, figures, tables, equations,footnotes, items in enumerate lists etc. LaTeX is context sensitive indoing this: A label defined in a figure environment automaticallyrecords the figure counter, not the section counter.@refillSeveral different environments can share a common counter and thereforea common label category. E.g. labels in both @code{equation} and@code{eqnarray} environments record the value of the same counter - theequation counter.@refill@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-labelIn order to create a label in a LaTeX document, press @kbd{C-c (}(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitiveand will figure out the environment it currently is in and adapt thelabel to that environment. A label usually consists of a short prefixindicating the type of the label and a unique mark. @b{Ref@TeX{}} has3 different modes to create this mark.@refill@enumerate@item@vindex reftex-translate-to-ascii-function@vindex reftex-derive-label-parameters@vindex reftex-label-illegal-re@vindex reftex-abbrev-parametersA label can be derived from context. This means, @b{Ref@TeX{}} takesthe context of the label definition and constructs a label fromthat@footnote{Note that the context may contain constructs which areillegal in labels. @b{Ref@TeX{}} will therefore strip the accent fromaccented Latin-1 characters and remove everything else which is notlegal in labels. This mechanism is safe, but may not be satisfactoryfor non-western languages. Check the following variables if you need tochange 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 sectionlabels. You will be asked to confirm the derived label, or editit.@refill@itemWe may also use a simple unique number to identify a label. This ismostly useful for labels where it is difficult to come up with a verygood descriptive name. @b{Ref@TeX{}}'s default settings use this methodfor equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}tends to write documents with many equations and finds it impossibleto come up with good names for each of them. These simple labels areinserted without query, and are therefore very fast. Good descriptivenames are not really necessary as @b{Ref@TeX{}} will provide context toreference a label (@pxref{Referencing Labels}).@refill@itemThe third method is to ask the user for a label. This is mostuseful for things which are easy to describe briefly and do not turn uptoo frequently in a document. @b{Ref@TeX{}} uses this for figures andtables. 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 accessthis label later.@refill@end enumerate@vindex reftex-insert-label-flagsIf you want to change the way certain labels are created, check out thevariable @code{reftex-insert-label-flags} (@pxref{Options (CreatingLabels)}).@refillIf you are using AUCTeX to write your LaTeX documents, you canset 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-referenceReferencing 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 aselection process and finally insert the complete @samp{\ref@{label@}}into the buffer.@refillFirst, @b{Ref@TeX{}} will determine the label category which is required.Often that can be figured out from context. For example, if youwrite @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knowsthat an equation label is going to be referenced. If it cannot figureout what label category is needed, it will query for one.@refillYou will then be presented with a label selection menu. This is aspecial buffer which contains an outline of the document along with alllabels of the given label category. In addition, next to the labelthere will be one line of context of the label definition, which is sometext in the buffer near the label definition. Usually this issufficient to identify the label. If you are unsure about a certainlabel, pressing @key{SPC} will show the label definition point inanother window.@refillIn order to reference a label, move to cursor to the correct label andpress @key{RET}. You can also reference several labels with a singlecall 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 summaryof this information is always available from the selection process bypressing @kbd{?}.@refill@table @kbd@tablesubheading{General}@item ?Show a summary of available commands.@item 0-9,-Prefix argument.@tablesubheading{Moving around}@item nGo to next label.@item pGo to previous label.@item bJump back to the position where you last left the selection buffer.Normally this should get you back to the last referenced label.@refill@item C-c C-nGoto next section heading.@item C-c C-pGoto previous section heading.@item N zJump to section N, using the prefix arg. For example @kbd{3 z} jumps to section 3.@refill@tablesubheading{Displaying Context}@item @key{SPC}Show the surroundings of the definition of the current label in anotherwindow. See also the @kbd{f} key.@refill@item f@vindex reftex-revisit-to-followToggle follow mode. When follow mode is active, the other window willalways display the full context of the current label. This is similarto pressing @key{SPC} after each cursor motion. Note that only contextin files already visited is shown. @b{RefTeX} will not visit a filejust for follow mode. See, however, the variable@code{reftex-revisit-to-follow}.@refill@item .Show insertion point in another window. This is the point from where youcalled @code{reftex-reference}.@refill@tablesubheading{Selecting a label and creating the reference}@item @key{RET}Insert a reference to the label at point into the buffer from which theselection process was started. When entries have been marked, @key{RET}references all marked labels.@refill@item mouse-2@vindex reftex-highlight-selectionClicking with mouse button 2 on a label will accept it like @key{RET}would. See also variable @code{reftex-highlight-selection}, @ref{Options(Misc)}.@refill@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 aseparator to be inserted before the corresponding reference. So markingsix entries with the keys @samp{m , , - , +} will give a reference listlike this (see the variable @code{reftex-multiref-punctuation})@exampleIn eqs. (1), (2), (3)--(4), (5) and (6)@end example@item uUnmark a marked entry.@c FIXME: Do we need `A' as well for consistency?@cindex LaTeX packages, @code{saferef}@cindex @code{saferef}, LaTeX package@item aAccept the marked entries and put all labels as a comma-separated listinto one @emph{single} @code{\ref} macro. Some packages like@file{saferef.sty} support multiple references in this way.@refill@item lUse the last referenced label(s) again. This is equivalent to moving tothat label and pressing @key{RET}.@refill@item @key{TAB}Enter a label with completion. This may also be a label which does notyet 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.@refill@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 isdisplayed by the @samp{S<>} indicator in the mode line of theselection buffer.@tablesubheading{Exiting}@item qExit the selection process without inserting any reference into thebuffer.@refill@tablesubheading{Controlling what gets displayed}@vindex reftex-label-menu-flagsThe defaults for the following flags can be configured with the variable @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).@item cToggle the display of the one-line label definition context in theselection buffer.@refill@item FToggle the display of the file borders of a multifile document in theselection buffer.@refill@item tToggle 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.@refill@item #Toggle the display of a label counter in the selection buffer.@refill@item %Toggle the display of labels hidden in comments in the selectionbuffers. Sometimes, you may have commented out parts of your document.If these parts contain label definitions, @b{Ref@TeX{}} can still displayand reference these labels.@refill@tablesubheading{Updating the buffer}@item gUpdate the menu. This will rebuilt the menu from the internal labellist, but not reparse the document (see @kbd{r}).@refill@item r@vindex reftex-enable-partial-scansReparse the document to update the information on all labels and rebuildthe menu. If the variable @code{reftex-enable-partial-scans} isnon-@code{nil} and your document is a multifile document, this willreparse only a part of the document (the file in which the label atpoint was defined).@refill@item C-u rReparse the @emph{entire} document.@item sSwitch the label category. After prompting for another label category,a menu for that category will be shown.@refill@item xReference a label from an external document. With the LaTeX package@code{xr} it is possible to reference labels defined in anotherdocument. This key will switch to the label menu of an externaldocument and let you select a label from there (@pxref{xr (LaTeXpackage),,xr}).@refill@end table@vindex reftex-select-label-mapIn order to define additional commands for the selection process, thekeymap @code{reftex-select-label-map} may be used.@refill@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 referencedwith a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}recognizes all labeled environments and macros discussed in @cite{TheLaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley1994.}. These are:@refill@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 isthe LaTeX core stuff)@refill@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)@refill@item@cindex @code{endnote}, LaTeX package@cindex LaTeX packages, @code{endnote}@cindex @code{\endnote}, LaTeX macrothe @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})@refill@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 itemizeIf you want to use other labeled environments, defined with@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognizethem (@pxref{Defining Label Environments}).@refill@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 labeledenvironments and macros. This is done with the variable@code{reftex-label-alist} (@pxref{Options (Defining LabelEnvironments)}). If you are not familiar with Lisp, you can use the@code{custom} library to configure this rather complex variable. To dothis, use@example@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}@end example@vindex reftex-label-alist-builtinHere 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 forall the builtin environments and macros (@pxref{Builtin LabelEnvironments}).@refill@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 twonew environments, @code{theorem} and @code{axiom}@refill@example\newtheorem@{axiom@}@{Axiom@}\newtheorem@{theorem@}@{Theorem@}@end example@noindentto be used like this:@example\begin@{axiom@}\label@{ax:first@} ....\end@{axiom@}@end exampleSo we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are newlabeled environments which define their own label categories. We caneither use Lisp to do this (e.g. in @file{.emacs}) or use the customlibrary. 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 lispThe type indicator characters @code{?a} and @code{?h} are used forprompts 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.@refill@noindentThe labels for Axioms and Theorems will have the prefixes @samp{ax:} and@samp{thr:}, respectively. @xref{AUCTeX}, for information on howAUCTeX can use @b{Ref@TeX{}} to automatically create labels when a newenvironment is inserted into a buffer.@refill@noindentThe @samp{~\ref@{%s@}} is a format string indicating how to insertreferences to these labels.@refill@noindentThe next item indicates how to grab context of the label definition.@refill@itemize @minus@item@code{t} means to get it from a default location (from the beginning ofa @code{\macro} or after the @code{\begin} statement). @code{t} is@emph{not} a good choice for eqnarray and similar environments.@refill@item@code{nil} means to use the text right after the label definition.@refill@itemFor more complex ways of getting context, see the variable@code{reftex-label-alist} (@ref{Options (Defining LabelEnvironments)}).@refill@end itemizeThe following list of strings is used to guess the correct label typefrom the word before point when creating a reference. E.g. if youwrite: @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 andrestrict the menu to only these labels without even asking.@refillThe final item in each entry is the level at which the environmentshould produce entries in the table of context buffer. If the number ispositive, 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 thedocument similar to sectioning commands. For everything else, omit theitem.@refillTo do the same configuration with @code{customize}, you need to click onthe @code{[INS]} button twice to create two templates and fill them inlike this:@refill@exampleReftex 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-flagsDepending on how you would like the label insertion and selection forthe 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 (ReferencingLabels)}).@refill@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments@subsection Quick Equation Macro@cindex Quick equation macro@cindex Macros as environment wrappersSuppose you would like to have a macro for quick equations. Itcould be defined like this:@example\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}@end example@noindentand used like this:@exampleEinstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.@end exampleWe 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 lispThe 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 isan equation label, the different @code{nil} elements indicate to use thedefault values for equations. The @samp{1} as the fifth elementindicates that the context of the label definition should be the 1stargument of the macro.@refillHere is again how this would look in the customization buffer:@exampleReftex 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 macroSuppose you want to make figures not directly with the figureenvironment, but with a macro like@example\newcommand@{\myfig@}[5][tbp]@{% \begin@{figure@}[#1] \epsimp[#5]@{#2@} \caption@{#3@} \label@{#4@} \end@{figure@}@}@end example@noindentwhich would be called like@example\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}@end exampleNow 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 findthe context.@refill@lisp(setq reftex-label-alist '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))@end lispThe 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 withlabels from normal figure environments. The @code{nil} entries forprefix 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.@refillAs a side effect of this configuration, @code{reftex-label} will nowinsert the required naked label (without the @code{\label} macro) whenpoint is directly after the opening parenthesis of a @code{\myfig} macroargument.@refillAgain, 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 categorySometimes you don't want to define a new label environment or macro, butjust change the information associated with a label category. Maybe youwant to add some magic words, for another language. Changing only theinformation associated with a label category is done by giving@code{nil} for the environment name and then specify the items you wantto define. Here is an example which adds German magic words to allpredefined label categories.@refill@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 categoryAnother case where one only wants to change the information associatedwith the label category is to change the macro which is used forreferencing the label. When working with the AMS-LaTeX stuff, you mightprefer @code{\eqref} for doing equation references. Here is how todo 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. Thefollowing is equivalent to the line above.@refill@lisp(setq reftex-label-alist '(AMSTeX))@end lispNote that this is automatically done by the @file{amsmath.el} style fileof AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,this configuration will not be necessary.@refill@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 environmentsSome LaTeX packages define environment-like structures without using thestandard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parsethese directly, but you can write your own special-purpose parser anduse it instead of the name of an environment in an entry for@code{reftex-label-alist}. The function should check if point iscurrently in the special environment it was written to detect. If so,it must return a buffer position indicating the start of thisenvironment. The return value must be @code{nil} on failure to detectthe environment. The function is called with one argument @var{bound}.If non-@code{nil}, @var{bound} is a boundary for backwards searcheswhich should be observed. We will discuss two examples.@refill@cindex LaTeX commands, abbreviatedSome people define abbreviations forenvironments, like @code{\be} for @code{\begin@{equation@}}, and@code{\ee} for @code{\end@{equation@}}. The parser function would haveto 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 returnthe beginning of the match. To avoid scanning too far, we can also lookfor empty lines which cannot occure inside an equation environment.Here is the setup:@refill@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 defineslist macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which areterminated by @samp{\z.} or by an empty line.@refill@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 exampleThe difficulty is that the @samp{\a.} lists can nest and that an emptyline terminates all list levels in one go. So we have to count nestinglevels between @samp{\a.} and @samp{\z.}. Here is the implementationfor @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 togetherWhen you have to put several entries into @code{reftex-label-alist}, justput them after each other in a list, or create that many templates inthe customization buffer. Here is a lisp example which uses several ofthe 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-2When point is idle on the argument of a @code{\ref} macro, the echo areawill display some information about the label referenced there. Notethat the information is only displayed if the echo area is not occupiedby 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 moreinformation.@refill@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 referencesThe LaTeX package @code{xr} makes it possible to create references tolabels defined in external documents. The preamble of a document using@code{xr} will contain something like this:@refill@example\usepackage@{xr@}\externaldocument[V1-]@{volume1@}\externaldocument[V3-]@{volume3@}@end example@noindentand we can make references to any labels defined in theseexternal documents by using the prefixes @samp{V1-} and @samp{V3-},respectively.@refill@b{Ref@TeX{}} can be used to create such references as well. Start thereferencing process normally, by pressing @kbd{C-c )}. Select a labeltype if necessary. When you see the label selection buffer, pressing@kbd{x} will switch to the label selection buffer of one of the externaldocuments. You may then select a label as before and @b{Ref@TeX{}} willinsert it along with the required prefix.@refillFor this kind of inter-document cross-references, saving of parsinginformation and the use of multiple selection buffers can mean a largespeed-up (@pxref{Optimizations}).@refill@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 createcross--references with page information. When you want to make areference with the @code{\vref} macro, just press the @kbd{v} key in theselection buffer to toggle between @code{\ref} and @code{\vref}(@pxref{Referencing Labels}). The mode line of the selection buffershows the current status of this switch. If you find that you almostalways use @code{\vref}, you may want to make it the default bycustomizing the variable @code{reftex-vref-is-default}. If thistoggling 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}).@refill@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 ofthe referenced counter but also the complete text around it, like@samp{Figure 3 on the preceding page}. In order to make it work youneed to use label prefixes like @samp{fig:} consistently - something@b{Ref@TeX{}} does automatically. When you want to make a referencewith the @code{\fref} macro, just press the @kbd{V} key in the selectionbuffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}(@pxref{Referencing Labels}). The mode line of the selection buffershows the current status of this switch. If this cycling seemsinconvenient, you can also use the commands @code{reftex-fancyref-fref}and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-cf} and @kbd{C-c F}.}. Or use AUCTeX to create your macros(@pxref{AUCTeX}).@refill@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 ofit. The argument of the macro is a citation key which identifies anarticle or book in either a BibTeX database file or in an explicit@code{thebibliography} environment in the document. @b{Ref@TeX{}}'ssupport for citations helps to select the correct key quickly.@refill@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.@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 processIn order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} thenprompts for a regular expression which will be used to search throughthe database and present the list of matches to choose from in aselection process similar to that for selecting labels(@pxref{Referencing Labels}).@refillThe regular expression uses an extended syntax: @samp{&&} defines alogic @code{and} for regular expressions. For example@samp{Einstein&&Bose} will match all articles which mentionBose-Einstein condensation, or which are co-authored by Bose andEinstein. When entering the regular expression, you can complete onknown citation keys.@refill@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 likeBibTeX, it will search for the specified files in the current directoryand 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 itsinformation from there. Note that in this case the informationpresented in the selection buffer will just be a copy of relevant@code{\bibitem} entries, not the structured listing available withBibTeX database files.@refill@kindex ?In the selection buffer, the following keys provide special commands. Asummary of this information is always available from the selectionprocess by pressing @kbd{?}.@refill@table @kbd@tablesubheading{General}@item ?Show a summary of available commands.@item 0-9,-Prefix argument.@tablesubheading{Moving around}@item nGo to next article.@item pGo to previous article.@tablesubheading{Access to full database entries}@item @key{SPC}Show the database entry corresponding to the article at point, inanother window. See also the @kbd{f} key.@refill@item fToggle follow mode. When follow mode is active, the other window willalways display the full database entry of the current article. This isequivalent to pressing @key{SPC} after each cursor motion. With BibTeXentries, follow mode can be rather slow.@refill@tablesubheading{Selecting entries and creating the citation}@item @key{RET}Insert a citation referencing the article at point into the buffer fromwhich the selection process was started.@refill@item mouse-2@vindex reftex-highlight-selectionClicking with mouse button 2 on a citation will accept it like @key{RET}would. See also variable @code{reftex-highlight-selection}, @ref{Options(Misc)}.@refill@item mMark 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 uUnmark a marked entry.@item aAccept all (marked) entries in the selection buffer and create a single@code{\cite} macro referring to them.@refill@item AAccept all (marked) entries in the selection buffer and create aseparate @code{\cite} macro for each of it.@refill@item @key{TAB}Enter a citation key with completion. This may also be a key which doesnot yet exist.@item .Show insertion point in another window. This is the point from where youcalled @code{reftex-citation}.@refill@tablesubheading{Exiting}@item qExit the selection process without inserting a citation into thebuffer.@refill@tablesubheading{Updating the buffer}@item gStart over with a new regular expression. The full database will berescanned with the new expression (see also @kbd{r}).@refill@c FIXME: Should we use something else here? r is usually rescan!@item rRefine the current selection with another regular expression. This will@emph{not} rescan the entire database, but just the already selectedentries.@refill@end table@vindex reftex-select-bib-mapIn order to define additional commands for this selection process, thekeymap @code{reftex-select-bib-map} may be used.@refill@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 @code{natbib}, citation style@cindex @code{harvard}, citation style@cindex @code{chicago}, citation style@vindex reftex-cite-formatThe standard LaTeX macro @code{\cite} works well with numeric or simplekey citations. To deal with the more complex task of author-yearcitations as used in many natural sciences, a variety of packages hasbeen developed which define derived forms of the @code{\cite} macro.@b{Ref@TeX{}} can be configured to produce these citation macros as well bysetting the variable @code{reftex-cite-format}. For the most commonlyused packages (@code{natbib}, @code{harvard}, @code{chicago}) this maybe done from the menu, under @code{Ref->Citation Styles}. Since thereare usually several macros to create the citations, executing@code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correctmacro. For the Natbib style, this looks like this:@exampleSELECT 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 exampleFollowing the most generic of these packages, @code{natbib}, the builtincitation 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 shownearlier (Jones et al, 1997)}).@refillTo 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 lispYou can also use AUCTeX style files to automatically set thecitation style based on the @code{usepackage} commands in a givendocument. @xref{Style Files}, for information on how to set up the stylefiles correctly.@refill@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-crossrefWhen point is idle on the argument of a @code{\cite} macro, the echo areawill display some information about the article cited there. Notethat the information is only displayed if the echo area is not occupiedby a different message. @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX databaseentry corresponding to a @code{\cite} macro, or all citation locationscorresponding to a @code{\bibitem} or BibTeX database entry.@xref{Viewing Cross-References}.@refill@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 whichproduce multiple bibliographies in a document. This is no problem for@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX databasefiles. If they do not, it is best to have each document part in aseparate file (as it is required for @code{chapterbib} anyway). Then@b{Ref@TeX{}} will still scan the locally relevant databases correctly. Ifyou have multiple bibliographies within a @emph{single file}, this mayor may not be the case.@node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations@section Citations outside LaTeX@cindex Citations outside LaTeX@vindex reftex-default-bibliographyThe command @code{reftex-citation} can also be executed outside a LaTeXbuffer. This can be useful to reference articles in the mail buffer andother documents. You should @emph{not} enter @code{reftex-mode} forthis, just execute the command. The list of BibTeX files will in thiscase 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 informationabout a citation directly into the buffer. Here is the lisp code to addthe @kbd{C-c [} binding to the mail buffer. It also provides a localbinding for @code{reftex-cite-format}.@refill@lisp(add-hook 'mail-setup-hook (lambda () (define-key mail-mode-map "\C-c[" (lambda () (interactive) (require 'reftex) (let ((reftex-cite-format 'locally)) (reftex-citation))))))@end lisp@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 coresupports two different indices, the standard index and a glossary. Withthe 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 anicely formatted index. Tools used with LaTeX include @code{MakeIndex}and @code{xindy}.@refillIndexing is a very difficult task. It must follow strict conventions tomake the index consistent and complete. There are basically twoapproaches one can follow, and both have their merits.@enumerate@itemPart of the indexing should already be done with the markup. Thedocument structure should be reflected in the index, so when startingnew sections, the basic topics of the section should be indexed. If thedocument contains definitions, theorems or the like, these should allcorrespond to appropriate index entries. This part of the index canvery well be developed along with the document. Often it is worthwhileto define special purpose macros which define an item and at the sametime make an index entry, possibly with special formatting to make thereference 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}).@refill@itemThe rest of the index is often just a collection of where in thedocument certain words or phrases are being used. This part isdifficult to develop along with the document, because consistent entriesfor each occurrence are needed and are best selected when the documentis ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file}which collects phrases and helps indexing the phrases globally.@refill@end enumerateBefore you start, you need to make sure that @b{Ref@TeX{}} knows aboutthe index style being used in the current document. @b{Ref@TeX{}} hasbuiltin 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 additionalargument, and @b{Ref@TeX{}} needs to be configured for those. Asufficiently new version of AUCTeX (9.10c or later) will do thisautomatically. If you really don't use AUCTeX (you should!), thisconfiguration needs to be done by hand with the menu (@code{Ref->IndexStyle}), or globally for all your documents with@refill@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-wordIn order to index the current selection or the word at the cursor press@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes theselection 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 aprefix argument (@kbd{C-u C-c /}), you get a chance to edit thegenerated index entry. Use this to change the case of the word or tomake 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 willjust 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 theavailable index macros and for its arguments. Completion will beavailable for the index entry and, if applicable, the index tag. Theindex tag is a string identifying one of multiple indices. With the@file{multind} and @file{index} packages, this tag is the first argumentto the redefined @code{\index} macro.@refill@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 forlater indexing. The file is located in the same directory as the masterfile 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 itis initialized by inserting a file header which contains the definitionof the available index macros. This list is initialized from@code{reftex-index-macros} (@pxref{Defining Index Macros}). You canedit 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 isa phrase file header example:@refill@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 exampleThe macro definition lines consist of a unique letter identifying amacro, 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 flagindicates 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 theabove example it is assumed that the macro @code{\index*@{@var{word}@}}already typesets its argument in the text, so that it is unnecessary torepeat @var{word} outside the macro.@refill@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, collectingPhrases for indexing can be collected while writing the document. Thecommand @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 linecan 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 andcopy 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 beindexed.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 properformat. 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 characteridentifying one of the macros defined in the file header. It isoptional - when omitted, the first macro definition line in the filewill be used for this phrase. The @var{phrase} is the phrase to besearched for when indexing. It may contain several words separated byspaces. By default the search phrase is also the text entered asargument of the index macro. If you want the index entry to bedifferent from the search phrase, enter another @key{TAB} and the indexargument @var{arg}. If you want to have each match produce severalindex 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 beable 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 anexample:@refill@example%--------------------------------------------------------------------I Suni Planet Planetsi Vega Stars!Vega Jupiter Planets!Jupiteri Mars Planets!Mars || Gods!Mars || Chocolate Bars!Marsi Pluto Planets!Pluto && Kuiper Belt Objects!Pluto@end exampleSo @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 firstmacro definition in the file header (see above example). At eachoccurrence of @samp{Mars} you will be able choose between indexing it asa 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.@refill@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-sBefore indexing the phrases in the phrases buffer, they should bechecked carefully for consistency. A first step is to sort the phrasesalphabetically - this is done with the command @kbd{C-c C-s}(@code{reftex-index-sort-phrases}). It will sort all phrases in thebuffer alphabetically by search phrase. If you want to group certainphrases and only sort within the groups, insert empty lines between thegroups. Sorting will only change the sequence of phrases within eachgroup (see the variable @code{reftex-index-phrases-sort-in-blocks}).@refill@kindex C-c C-iA useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})which lists information about the phrase at point, including an exampleof how the index entry will look like and the number of expected matchesin the document.@refill@kindex C-c C-tAnother important check is to find out if there are double oroverlapping entries in the buffer. For example if you are firstsearching and indexing @samp{Mars} and then @samp{Planet Mars}, thesecond 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 inthe buffer which is either duplicate or a subphrase of another phrase.In order to check the whole buffer like this, start at the beginning andexecute this command repeatedly.@refill@node Global Indexing, , Consistency Checks, The Index Phrases File@subsection Global Indexing@cindex Global indexing@cindex Indexing, global@cindex Indexing, from @file{phrases} bufferOnce the index phrases have been collected and organized, you are setfor global indexing. I recommend to do this only on an otherwisefinished document. Global indexing starts from the phrases buffer.There are several commands which start indexing: @kbd{C-c C-x} acts onthe current phrase line, @kbd{C-c C-r} on all lines in the currentregion and @kbd{C-c C-a} on all phrase lines in the buffer. It isprobably good to do indexing in small chunks since your concentrationmay not last long enough to do everything in one go.@refill@b{Ref@TeX{}} will start at the first phrase line and search the phraseglobally in the whole document. At each match it will stop, compute thereplacement string and offer you the following choices@footnote{Windowsusers: Restrict yourself to the described keys during indexing. Pressing @key{Help} at the indexing prompt can apparently hang Emacs.}:@refill@table @kbd@item yReplace this match with the proposed string.@item nSkip this match.@item !Replace this and all further matches in this file.@item qSkip this match, start with next file.@item QSkip this match, start with next phrase.@item oSelect a different indexing macro for this match.@item 1-9Select one of multiple index keys (those separated with @samp{||}).@item eEdit the replacement text.@item C-rRecursive edit. Use @kbd{C-M-c} to return to the indexing process.@item sSave this buffer and ask again about the current match.@item SSave all document buffers and ask again about the current match.@item C-gAbort the indexing process.@end tableThe @samp{Find and Index in Document} menu in the phrases buffer alsolists a few options for the indexing process. The options haveassociated 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 WordsWhen searching for index phrases, make sure whole words are matched.This should probably always be on.@item Case Sensitive SearchSearch case sensitively for phrases. I recommend to have this settingoff, in order to match the capitalized words at the beginning of asentence, and even typos. You can always say @emph{no} at a match youdo not like.@item Wrap Long LinesInserting index macros increases the line length. Turn this option onto allow @b{Ref@TeX{}} to wrap long lines.@item Skip Indexed MatchesWhen this is on, @b{Ref@TeX{}} will at each match try to figure out ifthis match is already indexed. A match is considered indexed if it iseither the argument of an index macro, or if an index macro is directly(without whitespace separation) before or after the match. Index macrosare those configured in @code{reftex-index-macros}. Intended forre-indexing a documents after changes have been made.@refill@end tableEven though indexing should be the last thing you do to a document, youare bound to make changes afterwards. Indexing then has to be appliedto the changed regions. The command@code{reftex-index-phrases-apply-to-region} is designed for thispurpose. When called from a LaTeX document with active region, it willapply @code{reftex-index-all-phrases} to the current region.@refill@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-indexIn order to compile and display the index, press @kbd{C-c >}. If thedocument uses multiple indices, @b{Ref@TeX{}} will ask you to selectone. Then, all index entries will be sorted alphabetically anddisplayed in a special buffer, the @file{*Index*} buffer. From thatbuffer you can check and edit each entry.@refillThe index can be restricted to the current section or the region. Thenonly entries in that part of the document will go into the compiledindex. To restrict to the current section, use a numeric prefix@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the currentregion, make the region active and use a numeric prefix @samp{3} (press@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer therestriction can be moved from one section to the next by pressing the@kbd{<} and @kbd{>} keys.@refillOne caveat: @b{Ref@TeX{}} finds the definition point of an index entryby searching near the buffer position where it had found to macro duringscanning. If you have several identical index entries in the samebuffer and significant changes have shifted the entries around, you mustrescan the buffer to ensure the correspondence between the@file{*Index*} buffer and the definition locations. It is thereforeadvisable to rescan the document (with @kbd{r} or @kbd{C-u r})frequently while editing the index from the @file{*Index*}buffer.@refill@kindex ?Here is a list of special commands available in the @file{*Index*} buffer. Asummary of this information is always available by pressing@kbd{?}.@refill@table @kbd@tablesubheading{General}@item ?Display a summary of commands.@item 0-9, -Prefix argument.@tablesubheading{Moving around}@item ! A..ZPressing any capital letter will jump to the corresponding section inthe @file{*Index*} buffer. The exclamation mark is special and jumps to the first entries alphabetically sorted below @samp{A}. These areusually non-alphanumeric characters.@refill@item nGo to next entry.@refill@item pGo to previous entry.@refill@tablesubheading{Access to document locations}@item @key{SPC}Show the place in the document where this index entry is defined.@refill @item @key{TAB}Go to the definition of the current index entry in anotherwindow.@refill@item @key{RET}Go to the definition of the current index entry and hide the@file{*Index*} buffer window.@refill@item f@vindex reftex-index-follow-mode@vindex reftex-revisit-to-followToggle follow mode. When follow mode is active, the other window willalways show the location corresponding to the line in the @file{*Index*}buffer at point. This is similar to pressing @key{SPC} after eachcursor motion. The default for this flag can be set with the variable@code{reftex-index-follow-mode}. Note that only context in filesalready visited is shown. @b{Ref@TeX{}} will not visit a file just forfollow mode. See, however, the variable@code{reftex-revisit-to-follow}.@refill@tablesubheading{Entry editing}@item eEdit the current index entry. In the minibuffer, you can edit theindex macro which defines this entry.@refill@item C-kKill the index entry. Currently not implemented because I don't knowhow to implement an @code{undo} function for this.@refill@item *Edit the @var{key} part of the entry. This is the initial part of theentry which determines the location of the entry in the index.@refill@item |Edit the @var{attribute} part of the entry. This is the part after thevertical bar. With @code{MakeIndex}, this part is an encapsulatingmacro. With @code{xindy}, it is called @emph{attribute} and is aproperty of the index entry that can lead to special formatting. Whencalled with @kbd{C-u} prefix, kill the entire @var{attribute}part.@refill@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 visualappearance of the entry in the index. When called with @kbd{C-u}prefix, kill the entire @var{visual} part.@refill@item (Toggle the beginning of page range property @samp{|(} of theentry.@refill @item )Toggle the end of page range property @samp{|)} of the entry.@refill @item _Make the current entry a subentry. This command will prompt for thesuperordinate entry and insert it.@refill@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}).@refill @tablesubheading{Exiting}@item qHide the @file{*Index*} buffer.@refill@item kKill the @file{*Index*} buffer.@refill@item C-c =Switch to the Table of Contents buffer of this document.@refill@tablesubheading{Controlling what gets displayed}@item c@vindex reftex-index-include-contextToggle the display of short context in the @file{*Index*} buffer. Thedefault for this flag can be set with the variable@code{reftex-index-include-context}.@refill@item @}Restrict the index to a single document section. The correspondingsection number will be displayed in the @code{R<>} indicator in themode line and in the header of the @file{*Index*} buffer.@refill@item @{Widen the index to contain all entries of the document.@refill@item <When the index is currently restricted, move the restriction to theprevious section.@refill@item >When the index is currently restricted, move the restriction to thenext section.@refill@tablesubheading{Updating the buffer}@item gRebuild the @file{*Index*} buffer. This does @emph{not} rescan thedocument. However, it sorts the entries again, so that edited entrieswill move to the correct position.@refill@item r@vindex reftex-enable-partial-scansReparse the LaTeX document and rebuild the @file{*Index*} buffer. When@code{reftex-enable-partial-scans} is non-nil, rescan only the file thislocation is defined in, not the entire document.@refill@item C-u rReparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}buffer.@refill@item sSwitch to a different index (for documents with multipleindices).@refill @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 hasalso builtin support for the re-implementations of @code{\index}in the @file{multind} and @file{index} packages. However, sincethe 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-macrosWhen writing a document with an index you will probably defineadditional 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 exampleThe first macro @code{\ix} typesets its argument in the text and placesit into the index. The second macro @code{\nindex} typesets itsargument 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} packagehere.}. The last macro also places its argument into the index, but assubitems under the main index entry @samp{Astronomical Objects}. Hereis how to make @b{Ref@TeX{}} recognize and correctly interpret thesemacros, 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 lispNote that the index tag is @samp{idx} for the main index, and@samp{name} for the name index. @samp{idx} and @samp{glo} are reservedfor the default index and for the glossary.The character arguments @code{?x}, @code{?n}, and @code{?o} are forquick identification of these macros when @b{Ref@TeX{}} inserts newindex entries with @code{reftex-index}. These codes need to beunique. @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 superordinateentry 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, italmost always can be @code{nil}.The final element in the list indicates if the text being indexed needsto be repeated outside the macro. For the normal index macros, thisshould 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 templateslike this:@exampleRepeat:[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 exampleWith the macro @code{\ix} defined, you may want to change the defaultmacro 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 lispwhich specifies that the macro identified with the character @code{?x} (the@code{\ix} macro) should be used for indexing phrases and words alreadyin the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).The index tag is "idx".@refill@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 thematching 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 BibTeXdatabase entry.@refillThe feature is invoked by pressing @kbd{C-c &}(@code{reftex-view-crossref}) while point is on the @var{key} argumentof a macro involved in cross--referencing. You can also click with@kbd{S-mouse-2} on the macro argument. Here is what will happen forindividual classes of macros:@refill@table @asis@item @code{\ref}@cindex @code{\ref}Display the corresponding label definition. All usualvariants@footnote{all macros that start with @samp{ref} or end with@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active forcross--reference display. This works also for labels defined in anexternal document when the current document refers to them through the@code{xr} interface (@pxref{xr (LaTeX package)}).@refill@item @code{\label}@cindex @code{\label}@vindex reftex-label-alistDisplay a document location which references this label. Pressing@kbd{C-c &} several times moves through the entire document and findsall locations. Not only the @code{\label} macro but also other macroswith label arguments (as configured with @code{reftex-label-alist}) areactive for cross--reference display.@refill@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--referencedisplay.@refill@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 findsall locations.@refill@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 adocument where the database entry at point is cited will be displayed.On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs tothe document you want to search. Subsequent calls will use the samedocument, until you break this link with a prefix argument to @kbd{C-c&}.@refill@item @code{\index}@cindex @code{\index}Display other locations in the document which are marked by an indexmacro 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.@refill@end table@vindex reftex-view-crossref-extraWhile the display of cross referencing information for the abovementioned macros is hard--coded, you can configure additional relationsin 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 systemswhich 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{}}'sentire set of options.@refill@node Key Bindings, Faces, RefTeXs Menu, Top@section Default Key Bindings@cindex Key Bindings, summaryHere is a summary of the available key bindings.@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-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 exampleNote that the @kbd{S-mouse-2} binding is only provided if this key isnot already used by some other package. @b{Ref@TeX{}} will not override anexisting binding to @kbd{S-mouse-2}.@refillPersonally, I also bind some functions in the users @kbd{C-c} map foreasier access.@refill@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 bydefault. 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-hookChanging and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook@code{reftex-load-hook}. For information on the keymapswhich 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 andtable of contents buffers. It does not create its own faces, but usesthe ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} willuse faces only when @code{font-lock} is loaded. This seems to bereasonable because people who like faces will very likely have itloaded. If you wish to turn off fontification or change the involvedfaces, see @ref{Options (Fontification)}.@refill@node Multifile Documents, Language Support, AUCTeX, Top@section Multifile Documents@cindex Multifile documents@cindex Documents, spread over filesThe following is relevant when working with documents spread over manyfiles:@refill@itemize @bullet@item@b{Ref@TeX{}} has full support for multifile documents. You can edit parts ofseveral (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 multifiledocument.@refill@item@vindex tex-main-file@vindex TeX-masterAll files belonging to a multifile document should define a FileVariable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for thestandard Emacs LaTeX mode) containing the name of the master file. Forexample, to set the file variable @code{TeX-master}, include somethinglike the following at the end of each TeX file:@refill@example%%% Local Variables: ***%%% mode:latex ***%%% TeX-master: "thesis.tex" ***%%% End: ***@end exampleAUCTeX with the setting@lisp(setq-default TeX-master nil)@end lispwill actually ask you for each new file about the master file and insertthis comment automatically. For more details see the documentation ofthe AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), thedocumentation 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}).@refill@itemThe context of a label definition must be found in the same file as thelabel itself in order to be processed correctly by @b{Ref@TeX{}}. The onlyexception is that section labels referring to a section statementoutside the current file can still use that section title ascontext.@refill@end itemize@node Language Support, Finding Files, Multifile Documents, Top@section Language Support@cindex Language supportSome parts of @b{Ref@TeX{}} are language dependent. The defaultsettings work well for English. If you are writing in a differentlanguage, the following hints may be useful:@itemize @bullet@item@vindex reftex-derive-label-parameters@vindex reftex-abbrev-parametersThe mechanism to derive a label from context includes the abbreviationof words and omission of unimportant words. These mechanisms may haveto 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-reAlso, when a label is derived from context, @b{Ref@TeX{}} clears thecontext string from non-ASCII characters in order to make a legal label.If there should ever be a version of @TeX{} which allows extendedcharacters @emph{in labels}, then we will have to look at thevariables @code{reftex-translate-to-ascii-function} and@code{reftex-label-illegal-re}.@itemWhen a label is referenced, @b{Ref@TeX{}} looks at the word before pointto guess which label type is required. These @emph{magic words} aredifferent 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 andfor the author list in citations. Some of this may be languagedependent. 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 filesIn order to find files included in a document via @code{\input} or@code{\include}, @b{Ref@TeX{}} searches all directories specified in theenvironment variable @code{TEXINPUTS}. Similarly, it will search thepath specified in the variables @code{BIBINPUTS} and @code{TEXBIB} forBibTeX database files.When searching, @b{Ref@TeX{}} will also expand recursive pathdefinitions (directories ending in @samp{//} or @samp{!!}). But it willonly search and expand directories @emph{explicitly} given in thesevariables. This may cause problems under the following circumstances:@itemize @bullet@itemMost TeX system have a default search path for both TeX files and BibTeXfiles which is defined in some setup file. Usually this default path isfor system files which @b{Ref@TeX{}} does not need to see. But if yourdocument needs TeX files or BibTeX database files in a directory onlygiven in the default search path, @b{Ref@TeX{}} will fail to find them.@itemSome TeX systems do not use environment variables at all in order tospecify the search path. Both default and user search path are thendefined in setup files.@end itemize@noindentThere are three ways to solve this problem:@itemize @bullet@itemSpecify all relevant directories explicitly in the environmentvariables. If for some reason you don't want to mess with the defaultvariables @code{TEXINPUTS} and @code{BIBINPUTS}, define your ownvariables and configure @b{Ref@TeX{}} to use them instead:@lisp(setq reftex-texpath-environment-variables '("MYTEXINPUTS"))(setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))@end lisp@itemSpecify 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@itemSome TeX systems provide stand--alone programs to do the file search justlike 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 thisprogram. 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@node Optimizations, Problems and Work-Arounds, Finding Files, Top@section Optimizations@cindex OptimizationsImplementing 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.@refill@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 BibTeXdatabase files for lookup purposes. These buffers are kept, so thatsubsequent use of the same files is fast. If you can't afford keepingthese 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, partialA @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 &}) initiatesre-parsing of the entire document in order to update the parsinginformation. For a large document this can be unnecessary, inparticular if only one file has changed. @b{Ref@TeX{}} can be configuredto do partial scans instead of full ones. @kbd{C-u} re-parsing thendoes apply only to the current buffer and files included from it.Likewise, the @kbd{r} key in both the label selection buffer and thetable-of-contents buffer will only prompt scanning of the file in whichthe label or section macro near the cursor was defined. Re-parsing ofthe entire document is still available by using @kbd{C-u C-u} as aprefix, or the capital @kbd{R} key in the menus. To use this feature,try@refill@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-extensionEven with partial scans enabled, @b{Ref@TeX{}} still has to make one fullscan, when you start working with a document. To avoid this, parsinginformation can be stored in a file. The file @file{MASTER.rel} is usedfor storing information about a document with master file@file{MASTER.tex}. It is written automatically when you kill a bufferin @code{reftex-mode} or when you exit Emacs. The information isrestored when you begin working with a document in a new editingsession. To use this feature, put into @file{.emacs}:@refill@vindex reftex-save-parse-info@lisp(setq reftex-save-parse-info t)@end lisp@item@b{Automatic Document Scans}@*@cindex Automatic document scans@cindex Document scanning, automaticAt rare occasions, @b{Ref@TeX{}} will automatically rescan a part of thedocument. 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 selectionbuffer, saying that their position in the label list in uncertain. Amanual document scan will fix this.@refill@item@b{Multiple Selection Buffers}@*@cindex Multiple selection buffers@cindex Selection buffers, multipleNormally, the selection buffer @file{*RefTeX Select*} is re-created forevery selection process. In documents with very many labels this cantake several seconds. @b{Ref@TeX{}} provides an option to create aseparate selection buffer for each label type and to keep this bufferfrom one selection to the next. These buffers are updated automaticallyonly 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 thatcategory have been added. To turn on this feature, use@refill@vindex reftex-use-multiple-selection-buffers@lisp(setq reftex-use-multiple-selection-buffers t)@end lisp@noindent@cindex Selection buffers, updatingYou can also inhibit the automatic updating entirely. Then theselection buffer will always pop up very fast, but may not contain themost recently defined labels. You can always update the buffer by hand,with the @kbd{g} key. To get this behavior, use instead@refill@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@page@node AUCTeX, Multifile Documents, Faces, Top@section @w{AUC @TeX{}}@cindex @code{AUCTeX}, Emacs package@cindex Emacs packages, @code{AUCTeX}AUCTeX is without doubt the best major mode for editing TeX and LaTeXfiles with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).If AUCTeX is not part of you Emacs distribution, you can getit@footnote{XEmacs 21.x users may want to install the correspondingXEmacs package.} by ftp from the@uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.@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 thisinterface is turned on, both packages will interact closely. Instead ofusing @b{Ref@TeX{}}'s commands directly, you can then also use themindirectly as part of the AUCTeXenvironment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will beneeded for all of this to work. Parts of it work also with earlierversions.}. The interface is turned on with@refill@lisp(setq reftex-plug-into-AUCTeX t)@end lispIf you need finer control about which parts of the interface are usedand which not, read the docstring of the variable@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-xcustomize-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 environmentis inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label togo 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@noindentwithout 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 nothave to rescan the buffer in order to see it.@refill@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 macrointeractively with @kbd{C-c @key{RET}}, AUCTeX normally prompts formacro arguments. Internally, it uses the functions@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} toprompt for arguments which are labels, citation keys and index entries.The interface takes over these functions@footnote{@code{fset} is used todo this, which is not reversible. However, @b{Ref@TeX{}} implements theold functionality when you later decide to turn off the interface.} andsupplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. Forexample, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}will supply its label selection process (@pxref{ReferencingLabels}).@refill@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 inassociation 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 styledefines macros or environments connected with labels, citations, or theindex. Many style files (e.g. @file{amsmath.el} or @file{natbib.el})distributed with AUCTeX already support @b{Ref@TeX{}} in thisway.@refillBefore calling a @b{Ref@TeX{}} function, the style hook should alwaystest for the availability of the function, so that the style file willalso work for people who do not use @b{Ref@TeX{}}. @refillAdditions made with style files in the way described below remain localto the current document. For example, if one package uses AMSTeX, thestyle file will make @b{Ref@TeX{}} switch over to @code{\eqref}, butthis will not affect other documents.@refill@findex reftex-add-label-environments@findex reftex-add-to-label-alistA style hook may contain calls to@code{reftex-add-label-environments}@footnote{This used to be thefunction @code{reftex-add-to-label-alist} which is still available as analias for compatibility.} which defines additions to@code{reftex-label-alist}. The argument taken by this function must havethe same format as @code{reftex-label-alist}. The @file{amsmath.el}style file of AUCTeX for example contains the following:@refill@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} environmentwith @code{\newtheorem} might use@refill@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-formatSimilarly, a style hook may contain a call to@code{reftex-set-cite-format} to set the citation format. The stylefile @file{natbib.el} for the Natbib citation style does switch@b{Ref@TeX{}}'s citation format like this:@refill@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} todefine additional @code{\index}-like macros. The argument must havethe same format as @code{reftex-index-macros}. It may be a symbol, totrigger 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 lispIf you have your own package @file{myindex} which defines thefollowing 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 exampleyou 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-levelsFinally the hook may contain a call to @code{reftex-add-section-levels}to define additional section statements. For example, the FoilTeX classhas just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Hereis 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{}} hassupport 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 mousehighlighting is provided (among other things) by Peter S. Galbraith's@file{bib-cite.el}. There is some overlap in the functionalities ofBib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled withAUCTeX.@refillBib-cite version 3.06 and later can be configured so that bib-cite'smouse 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 (ratherthan BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. Tomake use of this feature, try@refill@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}, @code{\bibliography} and @code{\section}(etc.) statements have to be first on a line (except for white space).@refill@item@b{Commented regions}@*@cindex Labels, commented out@b{Ref@TeX{}} sees also labels in regions commented out and will refuse tomake duplicates of such labels. This is considered to be a feature.@refill@item@b{Wrong section numbers}@*@cindex Section numbers, wrong@vindex reftex-enable-partial-scansWhen using partial scans (@code{reftex-enable-partial-scans}), the sectionnumbers in the table of contents may eventually become wrong. A fullscan will fix this.@refill@item@b{Local settings}@*@cindex Settings, local@findex reftex-add-label-environments@findex reftex-set-cite-format@findex reftex-add-section-levelsThe label environment definitions in @code{reftex-label-alist} areglobal and apply to all documents. If you need to make definitionslocal to a document, because they would interfere with settings in otherdocuments, 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 currentdocument. @xref{AUCTeX}.@refill@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 filedifferent from its disk representation (e.g. x-symbol, isotex,iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimesreflects the disk state of a file. This happens only in @emph{unvisited}parts of a multifile document, because @b{Ref@TeX{}} visits these filesliterally for speed reasons. Then both short context and sectionheadings may look different from what you usually see on your screen.In rare cases @code{reftex-toc} may have problems to jump to an affectedsection heading. There are three possible ways to deal withthis:@refill @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 multifiledocument into Emacs (i.e. there won't be any temporary buffers).@refill@item@vindex reftex-initialize-temporary-buffers@code{(setq reftex-initialize-temporary-buffers t)}@*This means full initialization of temporary buffers. It involvesa penalty when the same unvisited file is used for lookup often.@refill@itemSet @code{reftex-initialize-temporary-buffers} to a list of hookfunctions doing a minimal initialization.@refill@end itemize@vindex reftex-refontify-contextSee 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} macroto 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@noindentWe 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@noindentThe 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 onlyafter the @samp{@{step+@}}, also when specifying how to getcontext.@refill @item@b{Idle timers in XEmacs}@*@cindex Idle timer restart@vindex reftex-use-itimer-in-xemacsIn XEmacs, idle timer restart does not work reliably after fastkeystrokes. Therefore @b{Ref@TeX{}} currently uses the post commandhook to start the timer used for automatic crossref information. Whenthis 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-modeWith @i{Viper} mode prior to Vipers version 3.01, you need to protect@b{Ref@TeX{}}'s keymaps with@refill@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@b{Ref@TeX{}} was written by @i{@value{AUTHOR}}@email{@value{AUTHOR-EMAIL}}, with contributions by @i{StephenEglen}. @b{Ref@TeX{}} is currently maintained by @refill@noindent@value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}}If you have questions about @b{Ref@TeX{}}, there are several Usenetgroups which have competent readers: @code{comp.emacs},@code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}.You can also write directly to the maintainer.If you find a bug in @b{Ref@TeX{}} or its documentation, or if you wantto contribute code or ideas, please@uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}. Rememberto provide all necessary information such as version numbers of Emacsand @b{Ref@TeX{}}, and the relevant part of your configuration in@file{.emacs}. When reporting a bug which throws an exception, pleaseinclude a backtrace if you know how to produce one.@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. XEmacs21.x users want to install the corresponding plugin package which isavailable from the XEmacs @code{ftp} site. See the XEmacs 21.xdocumentation on package installation for details.@refillUsers of earlier Emacs distributions (including Emacs 19) can get a@b{Ref@TeX{}} distribution from the@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainerswebpage}. Note that the Emacs 19 version supports many but not allfeatures described in this manual.@refillThanks to the people on the Net who have used @b{Ref@TeX{}} and helpeddeveloping it with their reports. In particular thanks to @i{FranBurstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl Eichwalder,Erik Frik, Peter Galbraith, Kai Grossjohann, Frank Harrell, DieterKraft, Adrian Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier,Sudeep Kumar Palat, Daniel Polani, Robin Socha, Richard Stanton, AllanStrand, Jan Vroonhof, Christoph Wedler, Alan Williams}.@refillThe @code{view-crossref} feature was inspired by @i{Peter Galbraith's}@file{bib-cite.el}.@refillFinally thanks to @i{Uwe Bolick} who first got me (some years ago) intosupporting LaTeX labels and references with an editor (which wasMicroEmacs at the time).@refill@node Commands, Options, Imprint, Top@chapter Commands@cindex Commands, list ofHere is a summary of @b{Ref@TeX{}}'s commands which can be executed fromLaTeX files. Command which are executed from the special buffers arenot described here. All commands are available from the @code{Ref}menu. See @xref{Key Bindings}.@deffn Command reftex-tocShow the table of contents for the current document. When called withone ore two @kbd{C-u} prefixes, rescan the document first.@refill@end deffn@deffn Command reftex-labelInsert a unique label. With one or two @kbd{C-u} prefixes, enforcedocument rescan first.@end deffn@deffn Command reftex-referenceStart a selection process to select a label, and insert a reference toit. With one or two @kbd{C-u} prefixes, enforce document rescan first.@end deffn@deffn Command reftex-citationMake a citation using BibTeX database files. After prompting for a regularexpression, 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 isformated according to @code{reftex-cite-format} and inserted into thebuffer.@refill @*When called with one or two @kbd{C-u} prefixes, first rescans thedocument. When called with a numeric prefix, make that many citations.When called with point inside the braces of a @code{\cite} command, itwill add another key, ignoring the value of@code{reftex-cite-format}.@refill @* The regular expression uses an expanded syntax: @samp{&&} is interpretedas @code{and}. Thus, @samp{aaaa&&bbb} matches entries which containboth @samp{aaaa} and @samp{bbb}. While entering the regexp, completionon knows citation keys is possible. @samp{=} is a good regularexpression to match all entries in all files.@refill@end deffn@deffn Command reftex-indexQuery for an index macro and insert it along with its arguments. Theindex macros available are those defined in @code{reftex-index-macro} orby a call to @code{reftex-add-index-macros}, typically from an AUCTeXstyle file. @b{Ref@TeX{}} provides completion for the index tag and theindex key, and will prompt for other arguments.@refill@end deffn@deffn Command reftex-index-selection-or-wordPut current selection or the word near point into the default indexmacro. This uses the information in @code{reftex-index-default-macro}to make an index entry. The phrase indexed is the current selection orthe word near point. When called with one @kbd{C-u} prefix, let theuser 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. Whencalled 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.@refill@end deffn@deffn Command reftex-index-phrase-selection-or-wordAdd current selection or the word at point to the phrases buffer.When you are in transient-mark-mode and the region is active, theselection will be used - otherwise the word at point.You get a chance to edit the entry in the phrases buffer - to save thebuffer and return to the LaTeX document, finish with @kbd{C-c C-c}.@end deffn@deffn Command reftex-index-visit-phrases-bufferSwitch to the phrases buffer, initialize if empty.@end deffn@deffn Command reftex-index-phrases-apply-to-regionIndex 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-indexDisplay 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.@refill@end deffn@deffn Command reftex-view-crossrefView 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 ofthese. Where it makes sense, subsequent calls show additionallocations. See also the variable @code{reftex-view-crossref-extra} andthe command @code{reftex-view-crossref-from-bibtex}. With one or two@kbd{C-u} prefixes, enforce rescanning of the document. With argument2, select the window showing the cross reference.@end deffn@deffn Command reftex-view-crossref-from-bibtexView location in a LaTeX document which cites the BibTeX entry at point.Since BibTeX files can be used by many LaTeX documents, this functionprompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset thislink to a document, call the function with with a prefix arg. Callingthis function several times find successive citation locations.@end deffn@deffn Command reftex-create-tags-fileCreate TAGS file by running @code{etags} on the current document. TheTAGS file is also immediately visited with@code{visit-tags-table}.@refill@end deffn@deffn Command reftex-grep-documentRun grep query through all files related to this document.With prefix arg, force to rescan document.No active TAGS table is required.@refill@end deffn@deffn Command reftex-search-documentRegexp 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.@refill@end deffn@deffn Command reftex-query-replace-documentRun a query-replace-regexp of @var{from} with @var{to} over the entiredocument. With prefix arg, replace only word-delimited matches. Noactive TAGS table is required.@refill@end deffn@deffn Command reftex-change-labelQuery replace @var{from} with @var{to} in all @code{\label} and@code{\ref} commands. Works on the entire multifile document. Noactive TAGS table is required.@refill@end deffn@deffn Command reftex-renumber-simple-labelsRenumber all simple labels in the document to make them sequentially.Simple labels are the ones created by RefTeX, consisting only of theprefix and a number. After the command completes, all these labels willhave sequential numbers throughout the document. Any references to thelabels will be changed as well. For this, @b{Ref@TeX{}} looks at thearguments of any macros which either start or end with the string@samp{ref}. This command should be used with care, in particular inmultifile documents. You should not use it if another document refersto this one with the @code{xr} package.@refill@end deffn@deffn Command reftex-find-duplicate-labelsProduce a list of all duplicate labels in the document.@refill@end deffn@deffn Command reftex-customizeRun the customize browser on the @b{Ref@TeX{}} group.@end deffn@deffn Command reftex-show-commentaryShow the commentary section from @file{reftex.el}.@end deffn@deffn Command reftex-infoRun info on the top @b{Ref@TeX{}} node.@end deffn@deffn Command reftex-parse-documentParse the entire document in order to update the parsing information.@end deffn@deffn Command reftex-reset-modeEnforce rebuilding of several internal lists and variables. Alsoremoves the parse file associated with the current document.@end deffn@node Options, Keymaps and Hooks, Commands, Top@chapter Options, Keymaps, Hooks@cindex Options, list ofHere is a complete list of @b{Ref@TeX{}}'s configuration variables. Allvariables have customize support - so if you are not familiar with EmacsLisp (and even if you are) you might find it more comfortable to use@code{customize} to look at and change these variables. @kbd{M-xreftex-customize} will get you there.@refill@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-toc-max-levelThe 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 bechanged from within the @file{*toc*} buffer with the @kbd{t} key.@refill@end defopt@defopt reftex-toc-keep-other-windowsNon-@code{nil} means, split the selected window to display the@file{*toc*} buffer. This helps to keep the window configuration, butmakes the @file{*toc*} small. When @code{nil}, all other windows exceptthe selected one will be deleted, so that the @file{*toc*} window fillshalf the frame.@refill@end defopt@defopt reftex-toc-include-file-boundariesNon-@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.@refill@end defopt@defopt reftex-toc-include-labelsNon-@code{nil} means, include labels in @file{*toc*} buffer. This flagcan be toggled from within the @file{*toc*} buffer with the @kbd{l}key.@refill@end defopt@defopt reftex-toc-include-index-entriesNon-@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-contextNon-@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.@refill@end defopt@defopt reftex-toc-follow-modeNon-@code{nil} means, point in @file{*toc*} buffer (thetable-of-contents buffer) will cause other window to follow. The otherwindow will show the corresponding part of the document. This flag canbe toggled from within the @file{*toc*} buffer with the @kbd{f}key.@refill@end defopt@deffn {Normal Hook} reftex-toc-mode-hookNormal hook which is run when a @file{*toc*} buffer iscreated.@refill@end deffn@deffn Keymap reftex-toc-mapThe keymap which is active in the @file{*toc*} buffer.(@pxref{Table of Contents}).@refill@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-entriesDefault label alist specifications. It is a list of symbols withassociations in the constant @code{reftex-label-alist-builtin}.@code{LaTeX} should always be the last entry.@refill@end defopt@defopt reftex-label-alistSet 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 forsection labels, and @key{SPC} for the @code{any} label type. These arehard-coded at other places in the code.@refillThe value of the variable must be a list of items. Each item is a listitself 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 exampleEach list entry describes either an environment carrying a counter foruse with @code{\label} and @code{\ref}, or a LaTeX macro defining alabel as (or inside) one of its arguments. The elements of each listentry are:@refill@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 optionalarguments, a star to mark the label argument, if any. The macro doesnot have to have a label argument - you could also use@samp{\label@{...@}} inside one of its arguments.@refillSpecial names: @code{section} for section labels, @code{any} to define agroup which contains all labels.@refillThis may also be a function to do local parsing and identify point to bein a a non-standard label environment. The function must take anargument @var{bound} and limit backward searches to this value. Itshould return either nil or a cons cell @code{(@var{function}. @var{position})} with the function symbol and the position where thespecial environment starts. See the Info documentation for anexample.@refillFinally this may also be @code{nil} if the entry is only meant to changesome settings associated with the type indicator character (seebelow).@refill@item @var{type-key}Type indicator character, like @code{?t}, must be a printable ASCIIcharacter. The type indicator is a single character which defines alabel type. Any label inside the environment or macro is assumed tobelong to this type. The same character may occur several times in thislist, to cover cases in which different environments carry the samelabel type (like @code{equation} and @code{eqnarray}). If the typeindicator is @code{nil} and the macro has a label argument @samp{@{*@}},the macro defines neutral labels just like @code{\label}. In this casethe reminder of this entry is ignored.@refill@item @var{label-prefix}Label prefix string, like @samp{tab:}. The prefix is a short stringused as the start of a label. It may be the empty string. The prefixmay contain the following @samp{%} escapes:@refill@example%f Current file name, directory and extension stripped.%F Current file name relative to master file directory.%u User login name, on systems which support this.%S A section prefix derived with variable @code{reftex-section-prefixes}.@end example@noindentExample: In a file @file{intro.tex}, @samp{eq:%f:} will become@samp{eq:intro:}.@refill@item @var{reference-format}Format string for reference insert in buffer. @samp{%s} will bereplaced 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.@refill@item @var{context-method}Indication on how to find the short context.@itemize @minus@itemIf @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill@itemIf @code{t}, use@itemize @minus@itemthe section heading for section labels.@itemtext following the @samp{\begin@{...@}} statement of environments (nota good choice for environments like eqnarray or enumerate, where one hasseveral labels in a single environment).@refill@itemtext after the macro name (starting with the first arg) formacros.@refill@end itemize@itemIf an integer, use the nth argument of the macro. As a special case,1000 means to get text after the last macro argument.@refill@itemIf 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. puttingthis to @samp{\\caption[[@{]} will use the caption in a figure or tableenvironment. @samp{\\begin@{eqnarray@}\|\\\\} works foreqnarrays.@refill@itemIf any of @code{caption}, @code{item}, @code{eqnarray-like},@code{alignat-like}, this symbol will internally be translated into anappropriate regexp (see also the variable@code{reftex-default-context-regexps}).@refill@itemIf a function, call this function with the name of the environment/macroas argument. On call, point will be just after the @code{\label} macro.The function is expected to return a suitable context string. It shouldthrow an exception (error) when failing to find context. As an example,here is a function returning the 10 chars following the label macro ascontext:@refill@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 itemizeLabel context is used in two ways by @b{Ref@TeX{}}: For display in the labelmenu, and to derive a label string. If you want to use a differentmethod for each of these, specify them as a dotted pair.E.g. @code{(nil . t)} uses the text after the label (@code{nil}) fordisplay, and text from the default position (@code{t}) to derive a labelstring. This is actually used for section labels.@refill@item @var{magic-word-list}List of magic words which identify a reference to be of this type. Ifthe word before point is equal to one of these words when calling@code{reftex-reference}, the label list offered will be automaticallyrestricted to labels of the correct type. If the first element of thisword--list is the symbol `regexp', the strings are interpreted as regularexpressions.@refill@item @var{toc-level}The integer level at which this environment should be added to the tableof contents. See also @code{reftex-section-levels}. A positive valuewill number the entries mixed with the sectioning commands of the samelevel. A negative value will make unnumbered entries. Useful only fortheorem-like environments which structure the document. Will be ignoredfor macros. When omitted or @code{nil}, no TOC entries will bemade.@refill@end tableIf the type indicator characters of two or more entries are the same,@b{Ref@TeX{}} will use@refill@itemize @minus@itemthe first non-@code{nil} format and prefix@itemthe magic words of all involved entries.@end itemizeAny list entry may also be a symbol. If that has an association in@code{reftex-label-alist-builtin}, the @code{cddr} of that association isspliced into the list. However, builtin defaults should normally be setwith the variable @code{reftex-default-label-alist-entries}.@refill@end defopt@defopt reftex-max-section-depthMaximum depth of section levels in document structure.Standard LaTeX needs 7, default is 12.@end defopt@defopt reftex-section-levelsCommands 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 thesame as the positive value, but the section will never get anumber. The @code{cdr} may also be a function which then has to returnthe level.@refill@end defopt@defopt reftex-section-prefixesPrefixes for section labels. When the label prefix given in an entry in@code{reftex-label-alist} contains @samp{%S}, this list is used todetermine the correct prefix string depending on the current sectionlevel. The list is an alist, with each entry of the form@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macronames 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-regexpsAlist with default regular expressions for finding context. The emacslisp form @w{@code{(format regexp (regexp-quote environment))}} is usedto calculate the final regular expression - so @samp{%s} will bereplaced with the environment or macro.@refill@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-flagsFlags governing label insertion. The value has the form@example(@var{derive} @var{prompt})@end exampleIf @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensiblelabel from context. A section label for example will be derived fromthe section heading. The conversion of the context to a legal label isgoverned 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}.@refillIf @var{prompt} is @code{t}, the user will be prompted for a labelstring. When @var{prompt} is @code{nil}, the default label will beinserted without query.@refillSo the combination of @var{derive} and @var{prompt} controls labelinsertion. Here is a table describing all four possibilities:@refill@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 exampleEach flag may be set to @code{t}, @code{nil}, or a string of label typeletters indicating the label types for which it should be true. Thus,the combination may be set differently for each label type. The defaultsettings @samp{"s"} and @samp{"sft"} mean: Derive section labels fromheadings (with confirmation). Prompt for figure and table labels. Usesimple labels without confirmation for everything else.@refillThe 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}.@refill@end defopt@deffn Hook reftex-format-label-functionIf non-@code{nil}, should be a function which produces the string toinsert as a label definition. The function will be called with twoarguments, the @var{label} and the @var{default-format} (usually@samp{\label@{%s@}}). It should return the string to insert into thebuffer.@refill@end deffn@deffn Hook reftex-string-to-label-functionFunction to turn an arbitrary string into a legal label.@b{Ref@TeX{}}'s default function uses the variable@code{reftex-derive-label-parameters}.@refill@end deffn@deffn Hook reftex-translate-to-ascii-functionFilter function which will process a context string before it is used toderive a label from it. The intended application is to convert ISO orMule characters into something legal in labels. The default function@code{reftex-latin1-to-ascii} removes the accents from Latin-1characters. X-Symbol (>=2.6) sets this variable to the much moregeneral @code{x-symbol-translate-to-ascii}.@refill@end deffn@defopt reftex-derive-label-parametersParameters for converting a string into a label. This variable is alist of the following items:@refill@table @asis@item @var{nwords}Number of words to use.@item @var{maxchar}Maximum number of characters in a label string.@item @var{illegal}@code{nil}: Throw away any words containing characters illegal in labels.@*@code{t}: Throw away only the illegal 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-reRegexp matching characters not legal in labels.@end defopt@defopt reftex-abbrev-parametersParameters for abbreviation of words. A list of four parameters.@refill@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.@refill@item @var{before}Character class before abbrev point in word.@refill@item @var{after}Character class after abbrev point in word.@refill@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-flagsList 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.@refill@item @var{section-numbers}Include section numbers (like 4.1.3) in table of contents.@refill@item @var{counters}Show counters. This just numbers the labels in the menu.@refill@item @var{no-context}Non-@code{nil} means do @emph{not} show the short context.@refill@item @var{follow}Follow full context in other window.@refill@item @var{show-commented}Show labels from regions which are commented out.@refill@item @var{match-everywhere}Obsolete flag.@refill@item @var{show-files}Show begin and end of included files.@refill@end tableEach of these flags can be set to @code{t} or @code{nil}, or to a stringof 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 sectionand figure labels, @code{nil} for everything else. Setting it to@samp{"^sf"} makes it the other way round.@refillThe 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}.@refillMost options can also be switched from the label menu itself - so if youdecide here to not have a table of contents in the label menu, you canstill get one interactively during selection from the label menu.@refill@end defopt@defopt reftex-multiref-punctuationPunctuation strings for multiple references. When marking is used inthe selection buffer to select several references, this variableassociates the 3 marking characters @samp{,-+} with prefix strings to beinserted 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}.@refill@end defopt@defopt reftex-vref-is-defaultNon-@code{nil} means, the varioref macro @code{\vref} is used asdefault. In the selection buffer, the @kbd{v} key toggles the referencemacro between @code{\ref} and @code{\vref}. The value of this variabledetermines the default which is active when entering the selectionprocess. Instead of @code{nil} or @code{t}, this may also be a stringof type letters indicating the label types for which it should betrue.@refill@end defopt@defopt reftex-fref-is-defaultNon-@code{nil} means, the fancyref macro @code{\fref} is used asdefault. In the selection buffer, the @kbd{V} key toggles the referencemacro between @code{\ref}, @code{\fref} and @code{\Fref}. The value ofthis variable determines the default which is active when entering theselection process. Instead of @code{nil} or @code{t}, this may also bea string of type letters indicating the label types for which it shouldbe true.@end defopt@deffn Hook reftex-format-ref-functionIf non-@code{nil}, should be a function which produces the string toinsert as a reference. Note that the insertion format can also bechanged with @code{reftex-label-alist}. This hook also is used by thespecial commands to insert @code{\vref} and @code{\fref} references, soeven if you set this, your setting will be ignored by the specialcommands. 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.@refill@end deffn@defopt reftex-level-indentNumber of spaces to be used for indentation per section level.@refill@end defopt@defopt reftex-guess-label-typeNon-@code{nil} means, @code{reftex-reference} will try to guess thelabel type. To do that, @b{Ref@TeX{}} will look at the word before thecursor and compare it with the magic words given in@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} willimmediately offer the correct label menu - otherwise it will prompt youfor a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}will always prompt for a label type.@refill@end defopt@deffn {Normal Hook} reftex-display-copied-context-hookNormal Hook which is run before context is displayed anywhere. Designedfor @w{@code{X-Symbol}}, but may have other uses as well.@refill@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 commandstarted and a symbol indicating in what context the hook iscalled.@refill@end deffn@deffn {Normal Hook} reftex-select-label-mode-hookNormal hook which is run when a selection buffer enters@code{reftex-select-label-mode}.@refill @end deffn@deffn Keymap reftex-select-label-mapThe keymap which is active in the labels selection process(@pxref{Referencing Labels}).@refill@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-bibfile-ignore-regexpsList of regular expressions to exclude files in@code{\\bibliography@{..@}}. File names matched by any of these regexpswill not be parsed. Intended for files which contain only@code{@@string} macro definitions and the like, which are ignored by@b{Ref@TeX{}} anyway.@refill@end defopt@defopt reftex-default-bibliographyList of BibTeX database files which should be used if none are specified.When @code{reftex-citation} is called from a document with neithera @samp{\bibliography@{...@}} statement nor a @code{thebibliography}environment, @b{Ref@TeX{}} will scan these files instead. Intended forusing @code{reftex-citation} in non-LaTeX files. The files will besearched along the BIBINPUTS or TEXBIB path.@refill@end defopt@defopt reftex-sort-bibtex-matchesSorting of the entries found in BibTeX databases by reftex-citation.Possible values:@refill@examplenil @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-formatThe format of citations to be inserted into the buffer. It can be astring, 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.@refillIf @code{reftex-cite-format} is a string, it will be used as the format.In the format, the following percent escapes will be expanded.@refill@table @code@item %lThe BibTeX label of the citation.@item %aList of author names, see also @code{reftex-cite-punctuation}.@item %2aLike %a, but abbreviate more than 2 authors like Jones et al.@item %AFirst author name only.@item %eWorks like @samp{%a}, but on list of editor names. (@samp{%2e} and@samp{%E} work a well).@refill@end tableIt 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@noindentUsually, only @samp{%l} is needed. The other stuff is mainly for theecho area display, and for @code{(setq reftex-comment-citations t)}.@refill@samp{%<} as a special operator kills punctuation and space around itafter the string has been formatted.@refillBeware that all this only works with BibTeX database files. Whencitations are made from the @code{\bibitems} in an explicit@code{thebibliography} environment, only @samp{%l} is available.@refillIf @code{reftex-cite-format} is an alist of characters and strings, theuser will be prompted for a character to select one of the possibleformat strings.@refillIn 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 symbolsare those which have an association in the constant@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format'natbib)}.@refill@end defopt@deffn Hook reftex-format-cite-functionIf non-@code{nil}, should be a function which produces the string toinsert as a citation. Note that the citation format can also be changedwith the variable @code{reftex-cite-format}. The function will becalled with two arguments, the @var{citation-key} and the@var{default-format} (taken from @code{reftex-cite-format}). It shouldreturn the string to insert into the buffer.@refill@end deffn@defopt reftex-comment-citationsNon-@code{nil} means add a comment for each citation describing the fullentry. The comment is formatted according to@code{reftex-cite-comment-format}.@refill@end defopt@defopt reftex-cite-comment-formatCitation format used for commented citations. Must @emph{not} contain@samp{%l}. See the variable @code{reftex-cite-format} for possiblepercent escapes.@refill@end defopt@defopt reftex-cite-punctuationPunctuation for formatting of name lists in citations. This is a listof 3 strings.@refill@enumerate@itemnormal names separator, like @samp{, } in Jones, Brown and Miller@itemfinal names separator, like @samp{ and } in Jones, Brown and Miller@itemThe @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-hookNormal hook which is run when a selection buffer enters@code{reftex-select-bib-mode}.@refill @end deffn@deffn Keymap reftex-select-bib-mapThe keymap which is active in the citation-key selection process(@pxref{Creating Citations}).@refill@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-indexNon-@code{nil} means, index entries are parsed as well. Index supportis resource intensive and the internal structure holding the parsedinformation can become quite big. Therefore it can be turned off. Whenthis is @code{nil} and you execute a command which requires indexsupport, you will be asked for confirmation to turn it on and rescan thedocument.@refill@end defopt@defopt reftex-index-special-charsList of special characters in index entries, given as strings. Thesecorrespond to the @code{MakeIndex} keywords @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.@end defopt@defopt reftex-index-macrosList of macros which define index entries. The structure of each entryis@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 denoteoptional arguments. The star marks where the index key is.@refill@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 canbe defined as well. If this is an integer, the Nth argument of themacro holds the index tag.@refill@var{key} is a character which is used to identify the macro for inputwith @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} arereserved for default index and glossary.@refill@var{prefix} can be a prefix which is added to the @var{key} part of theindex entry. If you have a macro@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefixshould be @samp{Molecules!}.@refill@var{exclude} can be a function. If this function exists and returns anon-nil value, the index entry at point is ignored. This wasimplemented to support the (deprecated) @samp{^} and @samp{_} shortcutsin the LaTeX2e @code{index} package.@refill@var{repeat}, if non-@code{nil}, means the index macro does not typesetthe entry in the text, so that the text has to be repeated outside theindex macro. Needed for @code{reftex-index-selection-or-word} and forindexing from the phrase buffer.@refillThe final entry may also be a symbol. It must have an association inthe variable @code{reftex-index-macros-builtin} to specify the mainindexing package you are using. Legal values are currently@refill@exampledefault @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 exampleNote that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,so with a sufficiently new version of AUCTeX, you should not set thepackage here.@end defopt@defopt reftex-index-default-macroThe 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 theTAG argument of the index macro is optional, the TAG argument will beomitted.@refill@end defopt@defopt reftex-index-default-tagDefault index tag. When working with multiple indexes, RefTeX queriesfor an index tag when creating index entries or displaying a specificindex. This variable controls the default offered for these queries.The default can be selected with @key{RET} during selection orcompletion. Legal values of this variable are:@refill@examplenil @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-formatFormat 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 formatstring through the @code{format} function. This can be used to add themath delimiters (e.g. @samp{$}) to the string. Requires the@file{texmathp.el} library which is part of AUCTeX.@refill@end defopt@defopt reftex-index-phrase-file-extensionFile extension for the index phrase file. This extension will be addedto the base name of the master file.@end defopt@defopt reftex-index-phrases-logical-and-regexpRegexp matching the @samp{and} operator for index arguments in phrasesfile. When several index arguments in a phrase line are separated bythis operator, each part will generate an index macro. So each match ofthe search phrase will produce @emph{several} different index entries.Make sure this does no match things which are not separators. Thislogical @samp{and} has higher priority than the logical @samp{or}specified in @code{reftex-index-phrases-logical-or-regexp}.@refill@end defopt@defopt reftex-index-phrases-logical-or-regexpRegexp matching the @samp{or} operator for index arguments in phrasesfile. When several index arguments in a phrase line are separated bythis operator, the user will be asked to select one of them at eachmatch of the search phrase. The first index arg will be the default. Anumber key @kbd{1}--@kbd{9} must be pressed to switch to another. Makesure 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}.@refill@end defopt@defopt reftex-index-phrases-search-whole-wordsNon-@code{nil} means phrases search will look for whole words, not subwords.This works by requiring word boundaries at the beginning and end ofthe search string. When the search phrase already has a non-word-charat one of these points, no word boundary is required there.@end defopt@defopt reftex-index-phrases-case-fold-searchNon-@code{nil} means, searching for index phrases will ignorecase.@refill@end defopt@defopt reftex-index-phrases-skip-indexed-matchesNon-@code{nil} means, skip matches which appear to be indexed already.When doing global indexing from the phrases buffer, searches for somephrases may match at places where that phrase was already indexed. Inparticular when indexing an already processed document again, thiswill 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 anindex macro is directly before or after the phrase. If that is thecase, that match will be ignored.@refill@end defopt@defopt reftex-index-phrases-wrap-long-linesNon-@code{nil} means, when indexing from the phrases buffer, wrap lines.Inserting indexing commands in a line makes the line longer - oftenso long that it does not fit onto the screen. When this variable isnon-@code{nil}, newlines will be added as necessary before and/or after theindexing command to keep lines short. However, the matched textphrase and its index command will always end up on a single line.@refill@end defopt@defopt reftex-index-phrases-sort-prefers-entryNon-@code{nil} means when sorting phrase lines, the explicit index entryis used. Phrase lines in the phrases buffer contain a search phrase, andsorting is normally based on these. Some phrase lines also havean explicit index argument specified. When this variable isnon-@code{nil}, the index argument will be used for sorting.@refill@end defopt@defopt reftex-index-phrases-sort-in-blocksNon-@code{nil} means, empty and comment lines separate phrase bufferinto blocks. Sorting will then preserve blocks, so that lines arere-arranged only within blocks.@end defopt@defopt reftex-index-phrases-mapKeymap for the Index Phrases buffer.@end defopt@defopt reftex-index-phrases-mode-hookNormal hook which is run when a buffer is put into@code{reftex-index-phrases-mode}.@refill@end defopt@defopt reftex-index-section-lettersThe letters which denote sections in the index. Usually these are allcapital letters. Don't use any downcase letters. Order is notsignificant, the index will be sorted by whatever the sort functionthinks is correct. In addition to these letters, @b{Ref@TeX{}} willcreate a group @samp{!} which contains all entries sorted below thelowest specified letter. In the @file{*Index*} buffer, pressing any ofthese capital letters or @kbd{!} will jump to that section.@refill@end defopt@defopt reftex-index-include-contextNon-@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-modeNon-@code{nil} means, point in @file{*Index*} buffer will cause otherwindow to follow. The other window will show the corresponding part ofthe document. This flag can be toggled from within the @file{*Index*}buffer with the @kbd{f} key.@end defopt@deffn Keymap reftex-index-mapThe keymap which is active in the @file{*Index*} buffer(@pxref{Index Support}).@refill@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-extraMacros which can be used for the display of cross references.This is used when `reftex-view-crossref' is called with point in anargument of a macro. Note that crossref viewing for citations,references (both ways) and index entries is hard-coded. This variableis only to configure additional structures for which crossreferenceviewing 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 theregexp used to search for cross references. @samp{%s} in this regexp isreplaced with with the macro argument at point. @var{highlight} is aninteger indicating which subgroup of the match should be highlighted.@end defopt@defopt reftex-auto-view-crossrefNon-@code{nil} means, initially turn automatic viewing of crossref infoon. Automatic viewing of crossref info normally uses the echo area.Whenever point is on the argument of a @code{\ref} or @code{\cite}macro, and no other message is being displayed, the echo area willdisplay information about that cross reference. You can also set thevariable to the symbol @code{window}. In this case a small temporarywindow is used for the display. This feature can be turned on and offrom the menu (Ref->Options).@refill@end defopt@defopt reftex-idle-timeTime (secs) Emacs has to be idle before automatic crossref display isdone.@refill@end defopt@defopt reftex-cite-view-formatCitation format used to display citation info in the message area. Seethe variable @code{reftex-cite-format} for possible percentescapes.@refill@end defopt@defopt reftex-revisit-to-echoNon-@code{nil} means, automatic citation display will revisit files ifnecessary. When nil, citation display in echo area will only be activefor cached echo strings (see @code{reftex-cache-cite-echo}), or forBibTeX database files which are already visited by a live associatedbuffers.@refill@end defopt@defopt reftex-cache-cite-echoNon-@code{nil} means, the information displayed in the echo area forcite macros (see variable @code{reftex-auto-view-crossref}) is cached andsaved along with the parsing information. The cache survives documentscans. 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-variablesList of specifications how to retrieve the search path for TeX files.Several entries are possible.@refill@itemize @minus@itemIf an element is the name of an environment variable, its content isused.@refill@itemIf an element starts with an exclamation mark, it is used as a commandto retrieve the path. A typical command with the kpathsearch librarywould be @w{@code{"!kpsewhich -show-path=.tex"}}.@itemOtherwise the element itself is interpreted as a path.@end itemizeMultiple directories can be separated by the system dependent@code{path-separator}. Directories ending in @samp{//} or @samp{!!} willbe expanded recursively. See also @code{reftex-use-external-file-finders}.@end defopt@defopt reftex-bibpath-environment-variablesList of specifications how to retrieve the search path for BibTeXfiles. Several entries are possible.@refill@itemize @minus@itemIf an element is the name of an environment variable, its content isused.@refill@itemIf an element starts with an exclamation mark, it is used as a commandto retrieve the path. A typical command with the kpathsearch librarywould be @w{@code{"!kpsewhich -show-path=.bib"}}.@itemOtherwise the element itself is interpreted as a path.@end itemizeMultiple directories can be separated by the system dependent@code{path-separator}. Directories ending in @samp{//} or @samp{!!} willbe expanded recursively. See also @code{reftex-use-external-file-finders}.@end defopt@defopt reftex-file-extensionsAssociation 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 legal extensions for this file type.}@end exampleWhen a files is searched and it does not have any of the legal extensions,we try the default extension first, and then the naked file name.@refill@end defopt@defopt reftex-search-unrecursed-path-firstNon-@code{nil} means, search all specified directories before tryingrecursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},then @samp{/tex/}, and then all subdirectories of @samp{./}. If thisoption is @code{nil}, the subdirectories of @samp{./} are searchedbefore @samp{/tex/}. This is mainly for speed - most of the time therecursive path is for the system files and not for the user files. Setthis to @code{nil} if the default makes @b{Ref@TeX{}} finding files withequal names in wrong sequence.@refill@end defopt@defopt reftex-use-external-file-findersNon-@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 BibTeXdatabase files. With this option turned on, it calls an externalprogram 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-findersAssociation list with external programs to call for finding files. Eachentry is a cons cell @w{@code{(@var{type} . @var{program})}}.@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is astring containing the external program to use with any arguments.@code{%f} will be replaced by the name of the file to be found. Notethat these commands will be executed directly, not via a shell. Onlyrelevant when @code{reftex-use-external-file-finders} isnon-@code{nil}.@refill@end defopt@page@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options@section Optimizations@cindex Options, optimizations@cindex Optimizations, options@defopt reftex-keep-temporary-buffersNon-@code{nil} means, keep buffers created for parsing and lookup.@b{Ref@TeX{}} sometimes needs to visit files related to the currentdocument. We distinguish files visited for@refill@table @asis@item PARSINGParts of a multifile document loaded when (re)-parsing thedocument.@refill@item LOOKUPBibTeX database files and TeX files loaded to find a reference, todisplay label context, etc.@refill@end tableThe created buffers can be kept for later use, or be thrown awayimmediately after use, depending on the value of this variable:@refill@table @code@item nilThrow away as much as possible.@item tKeep everything.@item 1Throw away buffers created for parsing, but keep the ones created forlookup.@refill@end tableIf a buffer is to be kept, the file is visited normally (which ispotentially slow but will happen only once). If a buffer is to be thrownaway, the initialization of the buffer depends upon the variable@code{reftex-initialize-temporary-buffers}.@refill@end defopt@defopt reftex-initialize-temporary-buffersNon-@code{nil} means do initializations even when visiting filetemporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks andother stuff to briefly visit a file. When @code{t}, the full defaultinitializations are done (@code{find-file-hook} etc.). Instead of@code{t} or @code{nil}, this variable may also be a list of hookfunctions to do a minimal initialization.@refill@end defopt@defopt reftex-no-include-regexpsList of regular expressions to exclude certain input files from parsing.If the name of a file included via @code{\include} or @code{\input} ismatched by any of the regular expressions in this list, that file is notparsed by @b{Ref@TeX{}}.@end defopt@defopt reftex-enable-partial-scansNon-@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 amenu. Requesting re-parsing of an entire multifile document thenrequires a @kbd{C-u C-u} prefix or the capital @kbd{R} key inmenus.@refill@end defopt@defopt reftex-save-parse-infoNon-@code{nil} means, save information gathered with parsing in files.The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} isused to save the information. When this variable is @code{t},@itemize @minus@itemaccessing the parsing information for the first time in an editingsession will read that file (if available) instead of parsing thedocument.@refill@itemexiting Emacs or killing a buffer in reftex-mode will cause a newversion of the file to be written.@refill@end itemize@end defopt@defopt reftex-parse-file-extensionFile 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-rescanNon-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seemsnecessary. Applies (currently) only in rare cases, when a new labelcannot be placed with certainty into the internal label list.@end defopt@defopt reftex-use-multiple-selection-buffersNon-@code{nil} means use a separate selection buffer for each labeltype. These buffers are kept from one selection to the next and neednot 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 thevariable @code{reftex-auto-update-selection-buffers}.@refill@end defopt@defopt reftex-auto-update-selection-buffersNon-@code{nil} means, selection buffers will be updated automatically.When a new label is defined with @code{reftex-label}, all selectionbuffers associated with that label category are emptied, in order toforce an update upon next use. When @code{nil}, the buffers are leftalone and have to be updated by hand, with the @kbd{g} key from thelabel selection process. The value of this variable will only have anyeffect when @code{reftex-use-multiple-selection-buffers} isnon-@code{nil}.@refill@end defopt@node Options (Fontification), Options (Misc), Options (Optimizations), Options@section Fontification@cindex Options, fontification@cindex Fontification, options@defopt reftex-use-fontsNon-@code{nil} means, use fonts in label menu and on-the-fly help.Font-lock must be loaded as well to actually get fontifieddisplay. After changing this option, a rescan may be necessary toactivate it.@refill@end defopt@defopt reftex-refontify-contextNon-@code{nil} means, re-fontify the context in the label menu withfont-lock. This slightly slows down the creation of the label menu. Itis only necessary when you definitely want the context fontified.@refillThis option may have 3 different values:@table @code@item nilNever refontify.@item tAlways refontify.@item 1Refontify when necessary, e.g. with old versions of the x-symbolpackage.@refill@end tableThe option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill@end defopt@defopt reftex-highlight-selectionNon-@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 mostkeys in the selection and @file{*toc*} buffers act on. However, if youmainly use the mouse to select an item, you may find it nice to havemouse-triggered highlighting @emph{instead} or @emph{as well}. Thevariable may have one of these values:@refill@examplenil @r{No highlighting.}cursor @r{Highlighting is cursor driven.}mouse @r{Highlighting is mouse driven.}both @r{Both cursor and mouse trigger highlighting.}@end exampleChanging this variable requires to rebuild the selection and *toc*buffers to become effective (keys @kbd{g} or @kbd{r}).@refill@end defopt@defopt reftex-cursor-selected-faceFace name to highlight cursor selected item in toc and selection buffers.See also the variable @code{reftex-highlight-selection}.@refill@end defopt@defopt reftex-mouse-selected-faceFace name to highlight mouse selected item in toc and selection buffers.See also the variable @code{reftex-highlight-selection}.@refill@end defopt@defopt reftex-file-boundary-faceFace name for file boundaries in selection buffer.@end defopt@defopt reftex-label-faceFace name for labels in selection buffer.@end defopt@defopt reftex-section-heading-faceFace name for section headings in toc and selection buffers.@end defopt@defopt reftex-toc-header-faceFace name for the header of a toc buffer.@end defopt@defopt reftex-bib-author-faceFace name for author names in bib selection buffer.@end defopt@defopt reftex-bib-year-faceFace name for year in bib selection buffer.@end defopt@defopt reftex-bib-title-faceFace name for article title in bib selection buffer.@end defopt@defopt reftex-bib-extra-faceFace name for bibliographic information in bib selection buffer.@end defopt@defopt reftex-select-mark-faceFace name for marked entries in the selection buffers.@end defopt@defopt reftex-index-header-faceFace name for the header of an index buffer.@end defopt@defopt reftex-index-section-faceFace name for the start of a new letter section in the index.@end defopt@defopt reftex-index-tag-faceFace name for index names (for multiple indices).@end defopt@defopt reftex-index-faceFace name for index entries.@end defopt@node Options (Misc), , Options (Fontification), Options@section Miscellaneous@cindex Options, misc@defopt reftex-extra-bindingsNon-@code{nil} means, make additional key bindings on startup. Theseextra bindings are located in the users @samp{C-c letter}map. @xref{Key Bindings}.@refill@end defopt@defopt reftex-plug-into-AUCTeXPlug-in flags for AUCTeX interface. This variable is a list of5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}will@refill@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 exampleYou may also set the variable itself to t or nil in order to turn alloptions on or off, respectively.@*Supplying labels in new sections and environments applies when creatingsections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*Supplying macro arguments applies when you insert such a macrointeractively with @kbd{C-c @key{RET}}.@*See the AUCTeX documentation for more information.@end defopt@defopt reftex-revisit-to-followNon-@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-argsNon-@code{nil} means, allow arguments of macros to be detached bywhitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note thatthis will be the case even if @code{\bb} is defined with zero or oneargument.@refill@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-mapThe keymap for @b{Ref@TeX{}} mode.@end deffn@deffn {Normal Hook} reftex-load-hookNormal hook which is being run when loading @file{reftex.el}.@end deffn@deffn {Normal Hook} reftex-mode-hookNormal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill@end deffnFurthermore, the 4 modes used for referencing labels, creatingcitations, the table of contents buffer and the phrases buffer havetheir own keymaps and mode hooks. See the respective sections. Thereare many more hooks which are described in the relevant sections aboutoptions for a specific part of @b{Ref@TeX{}}.@refill@node Changes, , Keymaps and Hooks, Top@chapter Changes@cindex ChangesHere is a list of recent changes to @b{Ref@TeX{}}.@ignore@noindent @b{Version 1.00}@itemize @bullet@itemreleased on 7 Jan 1997.@end itemize@noindent @b{Version 1.04}@itemize @bullet@itemMacros as wrappers, AMSTeX support, delayed context parsing fornew labels.@refill@end itemize@noindent @b{Version 1.05}@itemize @bullet@itemXEmacs port.@end itemize@noindent @b{Version 1.07}@itemize @bullet@item@b{Ref@TeX{}} gets its own menu.@end itemize@noindent @b{Version 1.09}@itemize @bullet@itemSupport for @code{tex-main-file}, an analogue for@code{TeX-master}.@refill@itemMS-DOS support.@end itemize@noindent @b{Version 2.00}@itemize @bullet@itemLabels can be derived from context (default for sections).@itemConfiguration of label insertion and label referencing revised.@itemCrossref fields in BibTeX database entries.@item@code{reftex-toc} introduced (thanks to Stephen Eglen).@end itemize@noindent @b{Version 2.03}@itemize @bullet@item@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added todefault environments.@refill@item@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).@itemNew functions @code{reftex-arg-label}, @code{reftex-arg-ref},@code{reftex-arg-cite}.@refill@itemEmacs/XEmacs compatibility reworked. XEmacs 19.15 now isrequired.@refill@item@code{reftex-add-to-label-alist} (to be called from AUCTeX stylefiles).@refill@itemFinding context with a hook function.@itemSorting BibTeX entries (new variable:@code{reftex-sort-bibtex-matches}).@end itemize@noindent @b{Version 2.05}@itemize @bullet@itemSupport for @file{custom.el}.@itemNew function @code{reftex-grep-document} (thanks to Stephen Eglen).@end itemize@noindent @b{Version 2.07}@itemize @bullet@itemNew functions @code{reftex-search-document},@code{reftex-query-replace-document}.@end itemize@noindent @b{Version 2.11}@itemize @bullet@itemSubmitted for inclusion to Emacs and XEmacs.@end itemize@noindent @b{Version 2.14}@itemize @bullet@itemVariable @code{reftex-plug-into-AUCTeX} simplifies cooperation withAUCTeX.@refill@end itemize@noindent @b{Version 2.17}@itemize @bullet@itemLabel prefix expands % escapes with current file name and other stuff.@itemCitation format now with % escapes. This is not backwardcompatible!@refill@itemTEXINPUTS variable recognized when looking for input files.@itemContext can be the nth argument of a macro.@refill@itemSearching in the select buffer is now possible (@kbd{C-s} and@kbd{C-r}).@refill@itemDisplay and derive-label can use two different context methods.@itemAMSmath @code{xalignat} and @code{xxalignat} added.@end itemize@noindent @b{Version 3.00}@itemize @bullet@item@b{Ref@TeX{}} should work better for very large projects:@itemThe new parser works without creating a master buffer.@itemRescanning can be limited to a part of a multifile document.@itemInformation from the parser can be stored in a file.@item@b{Ref@TeX{}} can deal with macros having a naked label as an argument.@itemMacros may have white space and newlines between arguments.@itemMultiple identical section headings no longer confuse@code{reftex-toc}.@refill@item@b{Ref@TeX{}} should work correctly in combination with buffer-alteringpackages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill@itemAll labeled environments discussed in @emph{The LaTeX Companion} byGoossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of@b{Ref@TeX{}}'s defaults.@refill@end itemize@noindent @b{Version 3.03}@itemize @bullet@itemSupport for the LaTeX package @code{xr}, for inter-documentreferences.@refill@itemA few (minor) Mule-related changes.@itemFixed bug which could cause @emph{huge} @file{.rel} files.@itemSearch for input and @file{.bib} files with recursive path definitions.@end itemize@noindent @b{Version 3.04}@itemize @bullet@itemFixed BUG in the @emph{xr} support.@end itemize@noindent @b{Version 3.05}@itemize @bullet@itemCompatibility code now first checks for XEmacs feature.@end itemize@noindent @b{Version 3.07}@itemize @bullet@item@code{Ref} menu improved.@end itemize@noindent @b{Version 3.10}@itemize @bullet@itemFixed a bug which made reftex 3.07 fail on [X]Emacs version 19.@itemRemoved unimportant code which caused OS/2 Emacs to crash.@itemAll customization variables now accessible from menu.@end itemize@noindent @b{Version 3.11}@itemize @bullet@itemFixed bug which led to naked label in (e.g.) footnotes.@itemAdded scroll-other-window functions to RefTeX-Select.@end itemize@noindent @b{Version 3.12}@itemize @bullet@itemThere are 3 new keymaps for customization: @code{reftex-toc-map},@code{reftex-select-label-map}, @code{reftex-select-bib-map}.@itemRefontification uses more standard font-lock stuff.@itemWhen no BibTeX database files are specified, citations can also use@code{\bibitem} entries from a @code{thebibliography} environment.@refill@end itemize@noindent @b{Version 3.14}@itemize @bullet@itemSelection buffers can be kept between selections: this is faster.See new variable @code{reftex-use-multiple-selection-buffers}.@refill@itemPrefix interpretation of reftex-view-crossref changed.@itemSupport for the @code{varioref} package (@kbd{v} key in selectionbuffer).@refill@end itemize@noindent @b{Version 3.16}@itemize @bullet@itemNew hooks @code{reftex-format-label-function},@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill@itemTeXInfo documentation completed.@itemSome restrictions in Label inserting and referencing removed.@itemNew variable @code{reftex-default-bibliography}.@end itemize@noindent @b{Version 3.17}@itemize @bullet@itemAdditional bindings in selection and @file{*toc*} buffers. @kbd{g}redefined.@itemNew command @code{reftex-save-all-document-buffers}.@itemMagic word matching made more intelligent.@itemSelection process can switch to completion (with @key{TAB}).@item@code{\appendix} is now recognized and influences section numbering.@itemFile commentary shortened considerably (use Info documentation).@itemNew option @code{reftex-no-include-regexps} to skip some include files.@itemNew option @code{reftex-revisit-to-follow}.@end itemize@noindent @b{Version 3.18}@itemize @bullet@itemThe selection now uses a recursive edit, much like minibuffer input.This removes all restrictions during selection. E.g. you can nowswitch buffers at will, use the mouse etc.@refill@itemNew option @code{reftex-highlight-selection}.@item@kbd{mouse-2} can be used to select in selection and @file{*toc*}buffers.@refill@itemFixed some problems regarding the interaction with VIPER mode.@itemFollow-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.19}@itemize @bullet@itemFixed bug with AUCTeX @code{TeX-master}.@end itemize@noindent @b{Version 3.21}@itemize @bullet@itemNew options for all faces used by @b{Ref@TeX{}}. They're in thecustomization group @code{reftex-fontification-configurations}.@refill@end itemize@noindent @b{Version 3.22}@itemize @bullet@itemFixed bug with empty context strings.@item@code{reftex-mouse-view-crossref} is now bound by default at@kbd{S-mouse-2}.@refill@end itemize@noindent @b{Version 3.23}@itemize @bullet@itemParse 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.@itemThe cursor inside a @code{\ref} or @code{\cite} macro can now triggerautomatic display of crossref information in the echo area. Seevariable @code{reftex-auto-view-crossref}.@itemAUCTeX interface updates:@itemize @minus@itemAUCTeX 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.@itemSettings added to @b{Ref@TeX{}} via style files remain local.@end itemize@itemFixed bug with @code{reftex-citation} in non-latex buffers.@itemFixed bug with syntax table and context refontification.@itemSafety-net for name change of @code{font-lock-reference-face}.@end itemize@noindent @b{Version 3.24}@itemize @bullet@itemNew option @code{reftex-revisit-to-echo}.@itemInterface with X-Symbol (>=2.6) is now complete and stable.@itemAdapted to new outline, which uses overlays.@itemFile names in @code{\bibliography} may now have the @code{.bib}extension.@refill@itemFixed Bug with parsing "single file" from master file buffer.@end itemize@noindent @b{Version 3.25}@itemize @bullet@itemEchoing of citation info caches the info for displayed entries.New option @code{reftex-cache-cite-echo}.@refill@item@kbd{M-x reftex-reset-mode} now also removes the file with parsinginfo.@refill@itemDefault of @code{reftex-revisit-to-follow} changed to nil.@end itemize@noindent @b{Version 3.26}@itemize @bullet@item[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.@itemNew hooks @code{reftex-translate-to-ascii-function},@code{reftex-string-to-label-function}.@refill@itemMade sure automatic crossref display will not visit/scan files.@end itemize@noindent @b{Version 3.27}@itemize @bullet@itemMacros can define @emph{neutral} labels, just like @code{\label}itself.@refill@itemNew option @code{reftex-allow-detached-macro-args}, default @code{nil}!@end itemize@noindent @b{Version 3.28}@itemize @bullet@itemAuto view crossref for XEmacs uses @code{post-command-hook} to restart thetimer, since itimer restart is not reliable.@refill@itemOption @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.@itemExpansion of recursive tex and bib path rewritten.@itemFixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.@itemFixed bug with section numbering after *-red sections.@end itemize@noindent @b{Version 3.30}@itemize @bullet@itemIn @code{reftex-citation}, the regular expression used to scan BibTeXfiles can be specified using completion on known citation keys.@itemNew keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}entries.@itemNew command @code{reftex-renumber-simple-labels} to renumber simplelabels like @samp{eq:13} sequentially through a document.@end itemize@noindent @b{Version 3.33}@itemize @bullet@itemMultiple selection buffers are now hidden buffers (they start with aSPACE).@item Fixed bug with file search when TEXINPUTS environment variable is empty.@end itemize@noindent @b{Version 3.34}@itemize @bullet@itemAdditional flag in @code{reftex-derive-label-parameters} do make onlylowercase labels (default @code{t}).@itemAll @file{.rel} files have a final newline to avoid queries.@itemSingle byte representations of accented European letters (ISO-8859-1)are now legal in labels.@end itemize@noindent @b{Version 3.35}@itemize @bullet@itemISO 8859 Latin-1 chars are converted to ASCII to derive better labels.This takes back the related changes in 3.34 for safety reasons.@refill@end itemize@noindent @b{Version 3.36}@itemize @bullet@itemNew value @code{window} for option @code{reftex-auto-view-crossref}.@end itemize@noindent @b{Version 3.38}@itemize @bullet@item@code{reftex-view-crossref} no longer moves to find a macro. Point hasto be on the macro argument.@end itemize@noindent @b{Version 3.41}@itemize @bullet@itemNew 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.42}@itemize @bullet@itemFile search further refined. New option @code{reftex-file-extensions}.@item@file{*toc*} buffer can show the file boundaries of a multifiledocument, 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}. @refill@end itemize@noindent @b{Version 3.43}@itemize @bullet@itemViewing cross-references generalized. Now works on @code{\label},@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations ofthese, and from BibTeX buffers.@refill@itemNew option @code{reftex-view-crossref-extra}.@refill@itemSupport for the additional sectioning commands @code{\addchap} and@code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill@itemFiles in @code{reftex-default-bibliography} will be searched along@code{BIBINPUTS} path.@refill@itemReading a parse file now checks consistency.@end itemize@end ignore@noindent @b{Version 4.00}@itemize @bullet@itemRefTeX has been split into several smaller files which are autoloaded on demand.@itemIndex support, along with many new options.@itemThe selection of keys for @code{\ref} and @code{\cite} now allows toselect multiple items by marking entries with the @kbd{m} key.@itemFancyref support.@end itemize@noindent @b{Version 4.01}@itemize @bullet@itemNew command @code{reftex-index-globally} to index a word in manyplaces in the document. Also available from the index buffer with@kbd{&}.@itemThe first item in a @code{reftex-label-alist} entry may now also be a parserfunction 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.02}@itemize @bullet@itemmacros ending in @samp{refrange} are considered to contain references.@itemIndex entries made with @code{reftex-index-selection-or-word} in TeXmath mode automatically get enclosing @samp{$} to preserve math mode. Seenew option @code{reftex-index-math-format}. Requires AUCTeX.@end itemize@noindent @b{Version 4.04}@itemize @bullet@itemNew option @code{reftex-index-default-tag} implements a default for queries.@end itemize@noindent @b{Version 4.06}@itemize @bullet@item@code{reftex-section-levels} can contain a function to compute the levelof a sectioning command.@itemMultiple @code{thebibliography} environments recognized.@end itemize@noindent @b{Version 4.09}@itemize @bullet@itemNew 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 thissetting.@refill @itemRefTeX maintaines an @file{Index Phrases} file in which phrases can be collected. When the document is ready, RefTeX can search allthese phrases and assist indexing all matches.@refill@itemThe 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 filesneed to be adapted.@refill@itemThe variable @code{reftex-section-levels} no longer contains thedefault stuff which has been moved to a constant.@refill@itemEnvironments like theorems can be placed into the TOC by puttingentries for @samp{"begin@{theorem@}"} in@code{reftex-setion-levels}.@refill @end itemize@noindent @b{Version 4.10}@itemize @bullet@itemRenamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflictwith @file{reftex-vars.el} on DOS machines.@itemNew options @code{reftex-parse-file-extension} and@code{reftex-index-phrase-file-extension}.@end itemize@noindent @b{Version 4.11}@itemize @bullet@itemFixed bug which would parse @samp{\Section} just like @samp{\section}.@end itemize@noindent @b{Version 4.12}@itemize @bullet@itemSupport for @file{bibentry} citation style.@end itemize@noindent @b{Version 4.15}@itemize @bullet@itemSmall bug fixes.@itemImproved interaction with Emacs LaTeX mode.@end itemize@node Index, , , Top@unnumbered Index@printindex cp@summarycontents@contents@bye