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