@c %**start of header
@setfilename ../info/reftex
@settitle RefTeX User Manual
-@dircategory Emacs
-@direntry
-* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
-@end direntry
@synindex ky cp
@syncodeindex vr cp
@syncodeindex fn cp
-@set VERSION 4.15
-@set EDITION 4.15
-@set DATE November 2000
-@set AUTHOR Carsten Dominik
-@set AUTHOR-EMAIL dominik@@astro.uva.nl
-@set MAINTAINER Carsten Dominik
-@set MAINTAINER-EMAIL dominik@@astro.uva.nl
+@set VERSION 4.19
+@set EDITION 4.19
+@set DATE August 2002
@c %**end of header
+
+@copying
+This file documents @b{Ref@TeX{}}, a package to do labels, references,
+citations and indices for LaTeX documents with Emacs.
+
+This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
+@b{Ref@TeX{}} @value{VERSION}.
+
+Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
+@end direntry
+
@finalout
@c Macro definitions
@end ifnotinfo
@end macro
-@ifinfo
-This file documents @b{Ref@TeX{}}, a package to do labels, references,
-citations and indices for LaTeX documents with Emacs.@refill
-
-This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
-@b{Ref@TeX{}} @value{VERSION}@refill
-
-Copyright (c) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided that the entire resulting
-derive work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
-@end ifinfo
-
@titlepage
@title Ref@TeX{} User Manual
@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
@author by Carsten Dominik
@page
-Copyright @copyright{} 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
-
-@sp 2
-This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
-@b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
-
-@sp 2
-
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
-
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided that the entire resulting
-derive work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
-
+@vskip 0pt plus 1filll
+@insertcopying
@end titlepage
-@page
@ifnottex
@node Top,,,(dir)
* Viewing Cross-References:: Who references or cites what?
* RefTeXs Menu:: The Ref menu in the menubar.
-* Keybindings:: The default keybindings.
+* 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.
* Installation:: How to install and activate RefTeX.
* RefTeX in a Nutshell:: A brief summary and quick guide.
-
+
Labels and References
* Creating Labels::
@itemize @bullet
@item
-@b{Creating Labels}@*
+@b{Creating Labels}@*
Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
@b{Ref@TeX{}} will either
@itemize @minus
derive a label from context (default for section labels)
@item
prompt for a label string (default for figures and tables) or
-@item
+@item
insert a simple label made of a prefix and a number (all other
environments)@refill
@end itemize
additional customizations will be necessary.@refill
@item
-@b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,
-try these:@refill
-@lisp
-(setq reftex-enable-partial-scans t)
-(setq reftex-save-parse-info t)
-(setq reftex-use-multiple-selection-buffers t)
-@end lisp
-
-To integrate with AUCTeX, use
+@b{Useful Settings}@*
+To integrate RefTeX with AUCTeX, use
@lisp
(setq reftex-plug-into-AUCTeX t)
@end lisp
the manual if you get stuck, of if you are curious what else might be
available. The first part of the manual explains in
a tutorial way how to use and customize @b{Ref@TeX{}}. The second
-part is a command and variable reference.@refill
+part is a command and variable reference.@refill
@end enumerate
@node Table of Contents, Labels and References, Introduction, Top
@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.@refill
+
@tablesubheading{Access to document locations}
@item @key{SPC}
Show the corresponding location in another window. This command does
Show calling point in another window. This is the point from where
@code{reftex-toc} was last called.
+@page
@tablesubheading{Exiting}
@item q
Hide the @file{*toc*} buffer, return to the position where
@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*}
+@samp{2}, restrict the index to the section at point in the @file{*toc*}
buffer.
@tablesubheading{Controlling what gets displayed}
default for this flag can be set with the variable
@code{reftex-toc-include-index-entries}. When called with a prefix
argument, @b{Ref@TeX{}} will prompt for a specific index and include
-only entries in the selected index in the @file{*toc*} buffer. The mode
+only entries in the selected index in the @file{*toc*} buffer. The mode
line @samp{I<>} indicator shows which index is used.@refill
@item c
package)}), @b{Ref@TeX{}} will switch to one of the external
documents.@refill
+@item a
+Toggle the automatic recentering of the @file{*toc*} buffer. When this
+option is on, moving around in the document will cause the @file{*toc*}
+to always highlight the current section. This can be enabled by default
+with the variable @code{reftex-auto-recenter-toc}.
+
@end table
@vindex reftex-toc-map
In order to define additional commands for the @file{*toc*} buffer, the
keymap @code{reftex-toc-map} may be used.@refill
+@findex reftex-toc-recenter
+@vindex reftex-auto-recenter-toc
+@vindex reftex-idle-time
+@cindex @file{*toc*} buffer, recentering
+@cindex Table of contents buffer, recentering
+@kindex C-c -
+If you call @code{reftex-toc} while the @file{*toc*} buffer already
+exists, the cursor will immediately jump to the right place, i.e. the
+section from which @code{reftex-toc} was called will be highlighted.
+The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
+the @file{*toc*} buffer and highlight the correct line without actually
+selecting the @file{*toc*} window. This can be useful to quickly find
+out where in the document you currently are. If you want the TOC buffer
+to show the current section automatically whenever you stop typing, try
+@lisp
+(setq reftex-auto-recenter-toc t)
+@end lisp
+When this is turned on, the toc buffer will be recentered whenever Emacs
+is idle for more than @code{reftex-idle-time} seconds.
+
+
@cindex Sectioning commands
@cindex KOMA-Script, LaTeX classes
@cindex LaTeX classes, KOMA-Script
@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.@refill
+
@tablesubheading{Displaying Context}
@item @key{SPC}
Show the surroundings of the definition of the current label in another
@tablesubheading{Controlling what gets displayed}
@vindex reftex-label-menu-flags
-The defaults for the following flags can be configured with the variable
+The defaults for the following flags can be configured with the variable
@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
@item c
@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
+With prefix @var{arg}, change the maximum level of toc entries displayed
to @var{arg}. Chapters are level 1, section are level 2.@refill
@item #
@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 @b{Ref@TeX{}} to automatically create labels when a new
-environment is inserted into a buffer.@refill
+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
@example
[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
- Type specification : [Value Menu] Char : f
+ 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
@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 occure inside an equation environment.
+for empty lines which cannot occur inside an equation environment.
Here is the setup:@refill
@lisp
(defun detect-be-ee (bound)
;; Search backward for the macros or an empty line
- (if (re-search-backward
+ (if (re-search-backward
"\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
(if (match-beginning 2)
(match-beginning 2) ; Return start of environment
(defun detect-linguex (bound)
(let ((cnt 0))
(catch 'exit
- (while
+ (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
+ (cond
((match-beginning 1)
;; empty line terminates all - return nil
(throw 'exit nil))
@kindex C-c &
@kindex S-mouse-2
-When point is idle 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.
+When point is idle for more than @code{reftex-idle-time} seconds on the
+argument of a @code{\ref} macro, the echo area will display some
+information about the label referenced there. Note that the information
+is only displayed if the echo area is not occupied by a different
+message.
@b{Ref@TeX{}} can also display the label definition corresponding to a
@code{\ref} macro, or all reference locations corresponding to a
@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.@refill
+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.@refill
@cindex @code{\bibliography}
@cindex @code{thebibliography}, LaTeX environment
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
+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)}).@refill
@findex reftex-view-crossref
@findex reftex-mouse-view-crossref
-When point is idle 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.
+When point is idle for more than @code{reftex-idle-time} seconds on the
+argument of a @code{\cite} macro, the echo area will display some
+information about the article cited there. Note that the information is
+only displayed if the echo area is not occupied by a different message.
@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
entry corresponding to a @code{\cite} macro, or all citation locations
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
+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
+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.
format. A phrase line looks like this:
@example
-[@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
+[@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}.
@b{Ref@TeX{}} will start at the first phrase line and search the phrase
globally in the whole document. At each match it will stop, compute the
replacement string and offer you the following choices@footnote{Windows
-users: Restrict yourself to the described keys during indexing. Pressing
+users: Restrict yourself to the described keys during indexing. Pressing
@key{Help} at the indexing prompt can apparently hang Emacs.}:@refill
@table @kbd
@item e
Edit the replacement text.
@item C-r
-Recursive edit. Use @kbd{M-C-c} to return to the indexing process.
+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
@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 @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.@refill
@item n
@tablesubheading{Access to document locations}
@item @key{SPC}
-Show the place in the document where this index entry is defined.@refill
+Show the place in the document where this index entry is defined.@refill
@item @key{TAB}
Go to the definition of the current index entry in another
@item (
Toggle the beginning of page range property @samp{|(} of the
-entry.@refill
+entry.@refill
@item )
-Toggle the end of page range property @samp{|)} of the entry.@refill
+Toggle the end of page range property @samp{|)} of the entry.@refill
@item _
Make the current entry a subentry. This command will prompt for the
superordinate entry and insert it.@refill
@item ^
-Remove the highest superordinate entry. If the current entry is a
+Remove the highest superordinate entry. If the current entry is a
subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
-(@samp{bbb!ccc}).@refill
+(@samp{bbb!ccc}).@refill
@tablesubheading{Exiting}
@item q
@item s
Switch to a different index (for documents with multiple
-indices).@refill
+indices).@refill
@end table
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.
+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.
Macro with args: \ix@{*@}
Index Tag : [Value Menu] String: idx
Access Key : x
- Key Prefix :
+ 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 :
+ Key Prefix :
Exclusion hook : nil
Repeat Outside : [Toggle] off (nil)
[INS] [DEL] List:
@code{reftex-index-macros} will be recognized.@refill
@end table
-@vindex reftex-view-crossref-macros
+@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-macros}.
-
+in the variable @code{reftex-view-crossref-extra}.
+
@iftex
@chapter All the Rest
@end iftex
-@node RefTeXs Menu, Keybindings, Viewing Cross-References, Top
+@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top
@section @b{Ref@TeX{}}'s Menu
@cindex RefTeXs Menu
@cindex Menu, in the menu bar
@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
entire set of options.@refill
-@node Keybindings, Faces, RefTeXs Menu, Top
-@section Default Keybindings
-@cindex Keybindings, summary
+@node Key Bindings, Faces, RefTeXs Menu, Top
+@section Default Key Bindings
+@cindex Key Bindings, summary
-Here is a summary of the available keybindings.
+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 >
@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}
@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 keybindings for reftex-reset-mode and reftex-parse-document?
+@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
@end example
@noindent These keys are reserved for the user, so I cannot bind them by
-default. If you want to have these keybindings available, set in your
+default. If you want to have these key bindings available, set in your
@file{.emacs} file:
@vindex reftex-extra-bindings
@end lisp
@vindex reftex-load-hook
-Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook
+Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook
@code{reftex-load-hook}. For information on the keymaps
which should be used to add keys, see @ref{Keymaps and Hooks}.
-@node Faces, AUCTeX, Keybindings, Top
+@node Faces, AUCTeX, Key Bindings, Top
@section Faces
@cindex Faces
@vindex reftex-multiref-punctuation
@vindex reftex-cite-punctuation
-@item
+@item
@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
for the author list in citations. Some of this may be language
dependent. See the variables @code{reftex-multiref-punctuation} and
Specify the full search path directly in @b{Ref@TeX{}}'s variables.
@lisp
-(setq reftex-texpath-environment-variables
+(setq reftex-texpath-environment-variables
'("./inp:/home/cd/tex//:/usr/local/tex//"))
(setq reftex-bibpath-environment-variables
'("/home/cd/tex/lit/"))
@lisp
(setq reftex-use-external-file-finders t)
(setq reftex-external-file-finders
- '(("tex" "kpsewhich -format=.tex %f")
- ("bib" "kpsewhich -format=.bib %f")))
+ '(("tex" . "kpsewhich -format=.tex %f")
+ ("bib" . "kpsewhich -format=.bib %f")))
@end lisp
@end itemize
+@cindex Noweb files
+@vindex reftex-file-extensions
+@vindex TeX-file-extensions
+Some people like to use RefTeX with noweb files, which usually have the
+extension @file{.nw}. In order to deal with such files, the new
+extension must be added to the list of valid extensions in the variable
+@code{reftex-file-extensions}. When working with AUCTeX as major mode,
+the new extension must also be known to AUCTeX via the variable
+@code{TeX-file-extension}. For example:
+
+@lisp
+(setq reftex-file-extensions
+ '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
+(setq TeX-file-extensions
+ '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
+@end lisp
+
@node Optimizations, Problems and Work-Arounds, Finding Files, Top
@section Optimizations
@cindex Optimizations
+@b{Note added 2002. Computers have gotten a lot faster, so most of the
+optimizations discussed below will not be necessary on new machines. I
+am leaving this stuff in the manual for people who want to write thick
+books, where some of it still might be useful.}
+
Implementing the principle of least surprises, the default settings of
@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
when using @b{Ref@TeX{}} for a large project and/or on a small computer,
@end group
@end lisp
-@page
@node AUCTeX, Multifile Documents, Faces, Top
@section @w{AUC @TeX{}}
@cindex @code{AUCTeX}, Emacs package
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 you Emacs distribution, you can get
+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
@uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.
(reftex-set-cite-format 'natbib))))
@end lisp
-@findex reftex-add-index-macros
+@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
@item
@b{LaTeX commands}@*
@cindex LaTeX commands, not found
-@code{\input}, @code{\include}, @code{\bibliography} and @code{\section}
-(etc.) statements have to be first on a line (except for white space).@refill
+@code{\input}, @code{\include}, and @code{\section} (etc.) statements
+have to be first on a line (except for white space).@refill
@item
@b{Commented regions}@*
headings may look different from what you usually see on your screen.
In rare cases @code{reftex-toc} may have problems to jump to an affected
section heading. There are three possible ways to deal with
-this:@refill
+this:@refill
@itemize @minus
@item
@vindex reftex-keep-temporary-buffers
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.@refill
+context.@refill
@item
@b{Idle timers in XEmacs}@*
@item
@b{Viper mode}@*
@cindex Viper mode
-@cindex Keybindings, problems with Viper mode
+@cindex Key bindings, problems with Viper mode
@findex viper-harness-minor-mode
With @i{Viper} mode prior to Vipers version 3.01, you need to protect
@b{Ref@TeX{}}'s keymaps with@refill
@cindex @code{http}, @b{Ref@TeX{}} home page
@cindex @code{ftp}, @b{Ref@TeX{}} site
-@b{Ref@TeX{}} was written by @i{@value{AUTHOR}}
-@email{@value{AUTHOR-EMAIL}}, with contributions by @i{Stephen
+@b{Ref@TeX{}} was written by @i{@value{Carsten Dominik}}
+@email{dominik@@science.uva.nl}, with contributions by @i{Stephen
Eglen}. @b{Ref@TeX{}} is currently maintained by @refill
@noindent
-@value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}}
+@value{Carsten Dominik} @email{dominik@@science.uva.nl}
If you have questions about @b{Ref@TeX{}}, there are several Usenet
groups which have competent readers: @code{comp.emacs},
If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
to contribute code or ideas, please
-@uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}. Remember
+@uref{mailto:dominik@@science.uva.nl,contact the maintainer}. Remember
to provide all necessary information such as version numbers of Emacs
and @b{Ref@TeX{}}, and the relevant part of your configuration in
@file{.emacs}. When reporting a bug which throws an exception, please
Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
developing it with their reports. In particular thanks to @i{Fran
-Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl Eichwalder,
-Peter Galbraith, Kai Grossjohann, Frank Harrell, Dieter Kraft, Adrian
-Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar
-Palat, Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan
-Vroonhof, Christoph Wedler, Alan Williams}.@refill
+Burstall, Alastair Burt, Lars Clausen, Soren Dayton, Stephen Eglen, Karl
+Eichwalder, Erik Frik, Erik Frisk, Peter Galbraith, Kai Grossjohann,
+Frank Harrell, Stephan Heuel, Alan Ho, Lute Kamstra, Dieter Kraft,
+Adrian Lanz, Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep
+Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, Richard Stanton,
+Allan Strand, Jan Vroonhof, Christoph Wedler, Alan Williams, Roland
+Winkler, Eli Zaretskii}.@refill
The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
@file{bib-cite.el}.@refill
Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
LaTeX files. Command which are executed from the special buffers are
not described here. All commands are available from the @code{Ref}
-menu. For keybindings, @pxref{Keybindings}.
+menu. See @xref{Key Bindings}.
@deffn Command reftex-toc
Show the table of contents for the current document. When called with
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
-formated according to @code{reftex-cite-format} and inserted into the
+formatted according to @code{reftex-cite-format} and inserted into the
buffer.@refill @*
When called with one or two @kbd{C-u} prefixes, first rescans the
document. When called with a numeric prefix, make that many citations.
When called with point inside the braces of a @code{\cite} command, it
will add another key, ignoring the value of
-@code{reftex-cite-format}.@refill @*
+@code{reftex-cite-format}.@refill @*
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
View location in a LaTeX document which cites the BibTeX entry at point.
Since BibTeX files can be used by many LaTeX documents, this function
prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
-link to a document, call the function with with a prefix arg. Calling
+link to a document, call the function with a prefix arg. Calling
this function several times find successive citation locations.
@end deffn
active TAGS table is required.@refill
@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
@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.@refill
+@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,
changed from within the @file{*toc*} buffer with the @kbd{t} key.@refill
@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, initially turn automatic recentering of toc on.
+When active, the @file{*TOC*} buffer will always show the section you
+are currently working in. Recentering happens whenever Emacs is idle
+for more than `reftex-idle-time' seconds.
+This feature can be turned on and off from the menu
+(Ref->Options).
+@end defopt
+
+@defopt reftex-toc-split-windows-horizontally
+Non-@code{nil} means, create TOC window by splitting window
+horizontally. The default is to split vertically.
+@end defopt
+
+@defopt reftex-toc-split-windows-horizontally-fraction
+Fraction of the horizontal width of the frame to be used for TOC window.
+Only relevant when @code{reftex-toc-split-windows-horizontally} is
+non-@code{nil}.
+@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
group which contains all labels.@refill
This may also be a function to do local parsing and identify point to be
-in a a non-standard label environment. The function must take an
+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
with the variable @code{reftex-default-label-alist-entries}.@refill
@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.@refill
-@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
@deffn {Normal Hook} reftex-select-label-mode-hook
Normal hook which is run when a selection buffer enters
-@code{reftex-select-label-mode}.@refill
+@code{reftex-select-label-mode}.@refill
@end deffn
@deffn Keymap reftex-select-label-map
@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
@item
final names separator, like @samp{ and } in Jones, Brown and Miller
@item
-The @samp{et al.} string, like @samp{ @{\it et al.@}} in
+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}.@refill
+@code{reftex-select-bib-mode}.@refill
@end deffn
@deffn Keymap reftex-select-bib-map
@defopt reftex-index-special-chars
List of special characters in index entries, given as strings. These
-correspond to the @code{MakeIndex} keywords
+correspond to the @code{MakeIndex} keywords
@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
@end defopt
case.@refill
@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
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
+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 with the macro argument at point. @var{highlight} is an
+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 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 of
-from the menu (Ref->Options).@refill
+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).@refill
@end defopt
@defopt reftex-idle-time
-Time (secs) Emacs has to be idle before automatic crossref display is
-done.@refill
+Time (secs) Emacs has to be idle before automatic crossref display
+or toc recentering is done.@refill
@end defopt
@defopt reftex-cite-view-format
@defopt reftex-file-extensions
Association list with file extensions for different file types.
-This is a list of items, each item is like:
+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"}.}
@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{Keybindings}.@refill
+map. @xref{Key Bindings}.@refill
@end defopt
@defopt reftex-plug-into-AUCTeX
@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
+@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
@item
Multiple selection buffers are now hidden buffers (they start with a
SPACE).
-@item
+@item
Fixed bug with file search when TEXINPUTS environment variable is empty.
@end itemize
@noindent @b{Version 3.34}
@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}.
+@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}.
@item
Reading a parse file now checks consistency.
@end itemize
-@end ignore
@noindent @b{Version 4.00}
@itemize @bullet
@item
-RefTeX has been split into several smaller files which are autoloaded on
+RefTeX has been split into several smaller files which are autoloaded on
demand.
@item
Index support, along with many new options.
@itemize @bullet
@item
New option @code{reftex-toc-max-level} to limit the depth of the toc.
-New keybinding @kbd{t} in the @file{*toc*} buffer to change this
-setting.@refill
+New key binding @kbd{t} in the @file{*toc*} buffer to change this
+setting.@refill
@item
-RefTeX maintaines an @file{Index Phrases} file in which phrases can be
+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.@refill
@item
@item
Environments like theorems can be placed into the TOC by putting
entries for @samp{"begin@{theorem@}"} in
-@code{reftex-setion-levels}.@refill
+@code{reftex-setion-levels}.@refill
@end itemize
@noindent @b{Version 4.10}
@itemize @bullet
@noindent @b{Version 4.15}
@itemize @bullet
@item
+Fixed bug with parsing of BibTeX files, when fields contain quotes or
+unmatched parenthesis.
+@item
Small bug fixes.
@item
Improved interaction with Emacs LaTeX mode.
@end itemize
+@end ignore
+@noindent @b{Version 4.17}
+@itemize @bullet
+@item
+The toc window can be split off horizontally. See new options
+@code{reftex-toc-split-windows-horizontally},
+@code{reftex-toc-split-windows-horizontally-fraction}.
+@item
+It is possible to specify a function which verifies an index match
+during global indexing. See new option @code{reftex-index-verify-function}.
+@item
+The macros which input a file in LaTeX (like \input, \include) can
+be configured. See new option @code{reftex-include-file-commands}.
+@item
+The macros which specify the bibliography file (like \bibliography) can
+be configured. See new option @code{reftex-bibliography-commands}.
+@item
+The regular expression used to search for the \bibliography macro has
+been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
+chapterbib.
+@item
+Small bug fixes.
+@end itemize
+@noindent @b{Version 4.18}
+@itemize @bullet
+@item
+@code{reftex-citation} uses the word before the cursor as a default
+search string.
+@item
+Simplified several regular expressions for speed.
+@item
+Better support for chapterbib.
+@end itemize
+@noindent @b{Version 4.19}
+@itemize @bullet
+@item
+New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
+section in the TOC buffer without selecting the TOC window.
+@item
+Recentering happens automatically in idle time when the option
+@code{reftex-auto-recenter-toc} is turned on.
+@item
+Fixed several bugs related to automatic cursor positioning in the TOC
+buffer.
+@item
+The highlight in the TOC buffer stays when the focus moves to a
+different window.
+@item
+New command `reftex-goto-label'.
+@item
+Part numbers are no longer included in chapter numbers, and a new
+part does not reset the chapter counter. See new option
+@code{reftex-part-resets-chapter}.
+@end itemize
@node Index, , , Top
@unnumbered Index
@contents
@bye
+@ignore
+ arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43
+@end ignore
HCoop / bpt / emacs.git / blobdiff