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