Commit 4f595e15 authored by Ralf Angeli's avatar Ralf Angeli
Browse files

Merge from standalone RefTeX repository.

Here is the ChangeLog of the standalone version of RefTeX without
information about Makefiles and other auxiliary files.  The differences to
the Emacs repository are documented in the respective ChangeLog files.

2010-11-06  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el (reftex-create-bibtex-file): Make sure that
	entries with whitespace at various places are found.
	(reftex-extract-bib-entries-from-thebibliography): Remove
	superfluous backslash.

2010-10-16  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el
	(reftex-extract-bib-entries-from-thebibliography): Use
	`with-current-buffer'.

2010-09-14  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el (reftex-do-citation): Make it possible again
	to insert non-existent entries.

2010-01-30  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el (reftex-syntax-table-for-bib, reftex-mode):
	Do not derive `reftex-syntax-table-for-bib' from
	`reftex-syntax-table' because parens have to retain their paren
	syntax in order for parsing of BibTeX entries like @book(...) to
	work.

2009-09-12  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-label-alist): Doc fix.

	* lisp/reftex-toc.el (reftex-re-enlarge): Call `enlarge-window'
	only if there is something to do because in Emacs the horizontal
	version throws an error even if the parameter is 0.

2009-08-08  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-index.el: Suppress byte-compiler warnings.  Move
	provide statement to end of file.

	* lisp/reftex-dcr.el: Suppress byte-compiler warnings.  Move
	provide statement to end of file.

	* lisp/reftex-auc.el: Suppress byte-compiler warnings.

	* doc/reftex.texi (Imprint): Mention Wolfgang in list of
	contributors.

	* lisp/reftex-vars.el (reftex-plug-into-AUCTeX): Doc fix.

2009-07-05  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi (Creating Citations): Give a hint about how to
	auto-revert the BibTeX database file when using external editors.

	* lisp/reftex-cite.el (reftex-do-citation): Save match data when
	asking for optional arguments.

2009-04-29  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el (reftex-in-comment): Do not error out if
	`comment-start-skip' is not set.

2009-03-01  Wolfgang Mayer  <wmayer7@gmail.com>

	* lisp/reftex-cite.el (reftex-all-used-citation-keys):
	Fix regexp to correctly extract all citations in the same line.

2008-12-29  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-vref-is-default)
	(reftex-fref-is-default): Adapt doc string.
	(reftex-ref-style-default-list): New name for
	`reftex-ref-style-active-list'.  Use :set instead of :repeat.
	(reftex-vref-is-default, reftex-fref-is-default): Adapt to new
	name.

	* lisp/reftex-base.el (reftex-tie-multifile-symbols): Add doc
	string.
	(reftex-tie-multifile-symbols): Initialize
	`reftex-ref-style-list'.
	(reftex-untie-multifile-symbols): Add doc string.
	(reftex-add-index-macros): Doc fix.
	(reftex-ref-style-activate, reftex-ref-style-toggle)
	(reftex-ref-style-list): New functions.
	(reftex-mode-menu): Use them.

	* lisp/reftex-sel.el (reftex-select-cycle-ref-style-internal): Use
	`reftex-ref-style-list' function.

	* lisp/reftex-ref.el (reftex-reference): Use
	`reftex-ref-style-list' function.

	* doc/reftex.texi (Referencing Labels): Simplify section about
	reference macro cycling.
	(Reference Styles, Options (Referencing Labels)): Adapt to changed
	implementation.

2008-12-18  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el (reftex-in-comment): Deal correctly with
	escaped comment characters.

2008-11-30  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-ref-style-alist): Change structure
	so that it is not possible to use multiple different package names
	within a style.
	(reftex-ref-style-active-list): Adapt to new structure of
	`reftex-ref-style-alist'.

	* lisp/reftex-sel.el (reftex-select-cycle-active-ref-styles):
	Remove.
	(reftex-select-cycle-ref-style-internal): Adapt to new structure
	of `reftex-ref-style-alist'.

	* lisp/reftex-ref.el: Adapt creation of `reftex-<package>-<macro>'
	functions to new structure of `reftex-ref-style-alist'.
	(reftex-reference): Adapt to new structure of
	`reftex-ref-style-alist'.

	* lisp/reftex-base.el (reftex-mode-menu): Adapt to new structure
	of `reftex-ref-style-alist'.

	* doc/reftex.texi (Options (Referencing Labels)): Adapt to new
	structure of `reftex-ref-style-alist'.

2008-10-16  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi (Referencing Labels, Reference Styles): Document
	changes in the referencing functionality.

2008-10-15  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-ref-style-alist): Remove the symbols
	for symbols for macro type distinction.  Add characters for macro
	selection.
	(reftex-ref-macro-prompt): New variable.

	* lisp/reftex-sel.el (reftex-select-cycle-ref-style-internal):
	Remove code for testing macro type.
	(reftex-select-toggle-numref-pageref): Remove.
	(reftex-select-label-map): Remove binding for
	`reftex-select-toggle-numref-pageref'.

	* lisp/reftex-ref.el (reftex-reference): Prompt for a reference
	macro if `reftex-ref-macro-prompt' is non-nil.

	* lisp/reftex-base.el (reftex-select-with-char): Kill the RefTeX
	Select buffer when done.

2008-06-07  David Kastrup  <dak@gnu.org>

	* lisp/reftex-base.el (reftex-remove-if): Improve performance.

2008-06-07  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el (reftex-get-string-refs): Use a regexp
	alternative for better performance.

	* doc/reftex.texi (Commands): Mention options for definition of
	header and footer in BibTeX files.
	(Options (Creating Citations)): Document
	`reftex-create-bibtex-header' and `reftex-create-bibtex-footer'.

	* lisp/reftex-cite.el (reftex-stringref-p): Remove.
	(reftex-get-string-refs): Do without `reftex-stringref-p' and use
	`reftex-remove-if' instead of the cl-based `remove-if'.
	(reftex-create-bibtex-file): Doc fix.

	* lisp/reftex-base.el (reftex-remove-if): New function.

2008-06-07  Wolfgang Mayer  <wmayer7@gmail.com>

	* lisp/reftex-vars.el (reftex-create-bibtex-header)
	(reftex-create-bibtex-footer): New variables.

	* lisp/reftex-cite.el (reftex-parse-bibtex-entry): Accept
	additional optional argument `raw' and keep quotes or braces if it
	is non-nil.
	(reftex-stringref-p, reftex-get-string-refs): New functions.
	(reftex-create-bibtex-file): Include entries that are
	cross-referenced from cited entries.  Include @String definitions
	in the resulting bib file.  Add header and footer defined in
	`reftex-create-bibtex-header' and `reftex-create-bibtex-footer'.

2008-05-03  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-parse.el (reftex-parse-from-file): Move backward one
	char if a `\' was matched after a section macro.

	* lisp/reftex-global.el (reftex-isearch-switch-to-next-file): Use
	`reverse' instead of `nreverse' and `copy-list' in order to make
	the byte compiler happy.  Get rid of unused `orig-flist' variable.

	* lisp/reftex-base.el (reftex-compile-variables): Revert last
	change.  Match `\' after a section macro.
	(reftex-mapconcat-with-predicate): Remove.

2008-04-13  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el (reftex-mapconcat-with-predicate): New
	function.
	(reftex-compile-variables): Use it.  Treat environments and macros
	differently in the regexp for section matching.

	* lisp/reftex-parse.el (reftex-parse-from-file): Use beginning of
	match instead of end as bound.

	* lisp/reftex-sel.el (reftex-select-label-map): Changing binding
	of reference style toggling to "s" which is not already taken.

	* doc/reftex.texi (Reference Styles): Reflect change in key
	binding for toggling reference styles.  Some minor changes.

2008-03-27  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el: Some whitespace, doc and checkdoc fixes.

2008-03-16  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-index.el (reftex-index-selection-or-word): Use
	`reftex-region-active-p'.
	(reftex-index-show-entry)
	(reftex-index-initialize-phrases-buffer)
	(reftex-index-phrases-apply-to-region): Sync with Emacs trunk.

	* lisp/reftex-dcr.el (reftex-start-itimer-once): Silence the byte
	compiler.

	* lisp/reftex-auc.el: Move `provide' call to bottom of file.

	* lisp/reftex-base.el: Require easymenu and define autoloads
	earlier to avoid compiler warnings.
	(reftex-region-active-p, reftex-select-with-char)
	(reftex-show-commentary): Sync with version in Emacs trunk.
	(reftex-make-overlay, reftex-overlay-put, reftex-move-overlay)
	(reftex-delete-overlay): Define in a way which hides the XEmacs
	symbols from the byte compiler.
	(reftex-info): Silence the byte compiler.  Use `reftex.info'
	instead of `reftex' in order to get the correct file.

2008-03-07  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el (reftex-extract-bib-entries): Check if
	BibTeX file changed on disk and ask if it should be reread in case
	it did.

2008-03-02  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi: Lots of small fixes.
	(Reference Styles): New section.
	(varioref (LaTeX package), fancyref (LaTeX package)): Remove.
	(Options (Referencing Labels)): Remove descriptions of deprecated
	variables `reftex-vref-is-default' and `reftex-fref-is-default'.
	Add descriptions for `reftex-ref-style-alist' and
	`reftex-ref-style-active-list'.
	(Referencing Labels): Update regarding reference styles.

2008-02-17  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-ref.el (reftex-format-special): Add third argument
	for refstyle possible to be passed, making the byte compiler
	happy.
	(reftex-reference): Pass refstyle to `reftex-format-special'.

	* lisp/reftex-vars.el (reftex-ref-style-active-list): Make
	creation of type compatible with Emacs 21.
	(reftex-format-ref-function): Mention third argument of special
	format function.

	* lisp/reftex-base.el (reftex-mode-menu): Make creation of
	Reference Style menu compatible with Emacs 21.

	* doc/reftex.texi: Fix some typos.

2008-01-27  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-ref-style-active-list): Doc fix.

	* lisp/reftex-base.el (reftex-erase-all-selection-and-index-buffers)
	(reftex-access-parse-file): Use `mapc' instead of `mapcar' where
	return value is not used.

	* lisp/reftex-ref.el (reftex-offer-label-menu): Use `mapc' instead
	of `mapcar' where return value is not used.

	* lisp/reftex-sel.el (reftex-select-item, reftex-select-unmark):
	Use `mapc' instead of `mapcar' where return value is not used.

	* lisp/reftex-vars.el (reftex-ref-style-alist)
	(reftex-ref-style-active-list): New variables.
	(reftex-vref-is-default, reftex-fref-is-default): Adapt doc string
	to new implementation.  Mark as obsolete.  Add compatibility code
	for honoring the variable values in case they are set.

	* lisp/reftex-base.el (reftex-mode-menu): Reference styles are now
	computed from `reftex-ref-style-alist'.  Fix typo.

	* lisp/reftex-ref.el (reftex-reference): Determine reference macro
	by looking at `reftex-ref-style-active-list' and
	`reftex-ref-style-alist'.  Use only one special format function.
	(reftex-varioref-vref, reftex-fancyref-fref)
	(reftex-fancyref-Fref): Remove definitions.  The functions are now
	generated from `reftex-ref-style-alist'.
	(reftex-format-vref, reftex-format-Fref, reftex-format-fref):
	Remove.
	(reftex-format-special): New function.

	* lisp/reftex-sel.el (reftex-select-toggle-varioref)
	(reftex-select-toggle-fancyref): Remove.
	(reftex-select-cycle-active-ref-styles)
	(reftex-select-cycle-ref-style-internal)
	(reftex-select-cycle-ref-style-forward)
	(reftex-select-cycle-ref-style-backward)
	(reftex-select-toggle-numref-pageref): New functions.
	(reftex-select-label-map): Use `v' and `V' for general cycling
	through reference styles.  Add `p' for switching between number
	and page reference types.

2008-01-06  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el (reftex-pop-to-bibtex-entry)
	(reftex-extract-bib-entries-from-thebibliography): Match \bibitem
	entries with spaces or tabs in front of arguments.
	(reftex-insert-bib-matches): Use `mapc' instead of `mapcar'
	because return value is not used.

2008-01-05  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-toc.el (reftex-make-separate-toc-frame): Hide
	non-operational call to `focus-frame' in Emacs for the compilers's
	sake.

2008-01-03  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-dcr.el (reftex-mouse-view-crossref): Explain why
	point is set.

	* lisp/reftex-toc.el (reftex-toc-do-promote): Use `mapc' instead
	of `mapcar' because return value is not used.
	(reftex-toggle-auto-toc-recenter): Fix typo.

	* lisp/reftex-cite.el (reftex-do-citation): Use `mapc' instead of
	`mapcar' because return value is not used.

2007-10-10  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-cite-format-builtin)
	(reftex-bibliography-commands): Add support for ConTeXt.

	* doc/reftex.texi (Citation Styles): Mention support for ConTeXt.

2007-08-23  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi (Options (Defining Label Environments)): Fix
	typo.

2007-07-22  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el (reftex-set-cite-format): Autoload.
	(reftex-access-parse-file): Create parse file in a way that does
	not interfere with recentf mode.
	(reftex-access-parse-file): Do not risk destroying an existing
	buffer.

2007-07-07  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-parse.el (reftex-nth-arg): Use `forward-comment'
	instead of `comment-forward'.  The latter is not always available
	and the former is sufficient for LaTeX.
	(reftex-nth-arg): Revert last change since moving over whitespace
	and comments is done by `reftex-move-to-next-arg'.

2007-05-20  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi (Citation Styles): Correct some mistakes.

2007-04-03  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-cite.el: Delete trailing whitespace.
	(reftex-pop-to-bibtex-entry, reftex-extract-bib-entries)
	(reftex-parse-bibtex-entry, reftex-create-bibtex-file): Match
	entries containing numbers and symbol constituents.

2007-03-28  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi: Replace BibTeX by @BibTeX{} throughout the
	file.

2007-03-12  John Paul Wallington  <jpw@pobox.com>

	* lisp/reftex-vars.el (reftex-format-ref-function)
	(reftex-format-cite-function): Fix custom type.

2007-03-10  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-base.el: Remove information in comment already in
	imprint or cluttering output of `finder-commentary'.
	Require reftex.el.

	* lisp/reftex.el: Remove.  Now generated from reftex.el.in.

	* lisp/reftex-dcr.el: Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-global.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-index.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-parse.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-ref.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-sel.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-toc.el Remove version info in header.  Add
	maintainer info.

	* lisp/reftex-vars.el Remove version info in header.  Add
	maintainer info.

2007-03-08  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi: Include macros.texi and version.texi.  Change
	maintainer and version information.  Express TeX, LaTeX, AUCTeX
	and RefTeX with macros.
	(Imprint): Change maintainer information.

2007-03-04  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex.el: Update.

	* lisp/reftex-base.el (reftex-show-commentary): Look in
	reftex-base.el.
	(reftex-report-bug): New function.

	* lisp/reftex.el: Move original content to reftex-base.el.  Add
	new header and automatically generated autoloads.

	* lisp/reftex-base.el: New file.  Insert original content of
	reftex.el.  Remove autoload for `reftex-index-phrases-mode'.
	Delete trailing whitespace.

2007-02-26  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-index.el (reftex-index-visit-phrases-buffer): Set
	marker when visiting buffer.  This allows for returning from the
	phrases file to the file one was just editing instead of the file
	where the last phrases was added from.

2007-02-25  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-index.el (reftex-index-phrases-syntax-table): New
	variable.  Give ?\" punctuation syntax as it usually is not used
	as string quote in TeX-related modes and may occur unmatched.  The
	change also prevents fontification of quoted content.
	(reftex-index-phrases-mode): Use it.

	* lisp/reftex-cite.el (reftex-parse-bibtex-entry): Match fields
	containing hyphens (besides word constituents).

2007-02-25  David Kastrup  <dak@gnu.org>

	* lisp/reftex.el (reftex-uniquify, reftex-uniquify-by-car):
	Replace O(n^2) algorithms with O(n log n).  Introduce optional
	argument SORT (not yet used).  TODO: figure out callers that can
	specify SORT, in order to further speed this up.

2007-02-25  Ralf Angeli  <angeli@caeruleus.net>

	* lisp/reftex-vars.el (reftex-cite-key-separator): New variable.

	* lisp/reftex-auc.el (reftex-arg-cite): Use
	`reftex-cite-key-separator'.

	* lisp/reftex-cite.el (reftex-do-citation)
	(reftex-figure-out-cite-format): Use `reftex-cite-key-separator'.

	* doc/reftex.texi (Options (Creating Citations)): Document
	`reftex-cite-key-separator'.

	* lisp/reftex-cite.el (reftex-do-citation): Return all keys, not
	just the first one.

	* lisp/reftex-auc.el (reftex-arg-cite): Correctly handle new
	value type returned by `reftex-citation'.

2007-02-24  Ralf Angeli  <angeli@caeruleus.net>

	* doc/reftex.texi: Set correct filename for standalone
	distribution.

2007-02-07  Ralf Angeli  <angeli@caeruleus.net>

	Create `reftex' module.
parent 440ba395
2012-09-30 Ralf Angeli <angeli@caeruleus.net>
Merge from standalone RefTeX repository.
* reftex.texi: Express TeX, LaTeX, AUCTeX, BibTeX and RefTeX
with macros.
(Imprint): Mention Wolfgang in list of contributors.
(Creating Citations): Give a hint about how to
auto-revert the BibTeX database file when using external editors.
(Referencing Labels): Simplify section about reference macro
cycling.
(Options (Referencing Labels)): Adapt to new structure of
`reftex-ref-style-alist'.
(Referencing Labels, Reference Styles): Document changes in the
referencing functionality.
(Commands): Mention options for definition of header and footer in
BibTeX files.
(Options (Creating Citations)): Document
`reftex-create-bibtex-header' and `reftex-create-bibtex-footer'.
(Reference Styles): New section.
(varioref (LaTeX package), fancyref (LaTeX package)): Remove.
(Options (Referencing Labels)): Remove descriptions of deprecated
variables `reftex-vref-is-default' and `reftex-fref-is-default'.
Add descriptions for `reftex-ref-style-alist' and
`reftex-ref-style-default-list'.
(Referencing Labels): Update regarding reference styles.
(Citation Styles): Mention support for ConTeXt.
(Options (Defining Label Environments)): Fix typo.
(Options (Creating Citations)): Document
`reftex-cite-key-separator'.
2012-09-30 Achim Gratz <Stromeko@Stromeko.DE>
* org.texi: Add description of ORG_ADD_CONTRIB to info
......
......@@ -6,26 +6,44 @@
@syncodeindex vr cp
@syncodeindex fn cp
@c Version and Contact Info
@set VERSION 4.31
@set EDITION 4.31
@set DATE February 2006
@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site}
@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page}
@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 ../emacs/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 AUC@TeX{} project
@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org})
@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org})
@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org})
@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}
@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 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}
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.
......@@ -64,9 +82,9 @@ developing GNU and promoting software freedom.''
@end macro
@titlepage
@title Ref@TeX{} User Manual
@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
@subtitle Edition @value{EDITION}, @value{DATE}
@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
......@@ -79,18 +97,17 @@ developing GNU and promoting software freedom.''
@ifnottex
@node Top,,,(dir)
@top RefTeX
@top @RefTeX{}
@b{Ref@TeX{}} is a package for managing Labels, References,
Citations and index entries with GNU Emacs.
@RefTeX{} is a package for managing Labels, References, Citations and
index entries with GNU Emacs.
Don't be discouraged by the size of this manual, which covers
@b{Ref@TeX{}} in great depth. All you need to know to use
@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
Nutshell}). You can go back later to other parts of this document when
needed.
This manual documents @RefTeX{} version @value{VERSION}.
@insertcopying
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.
......@@ -106,8 +123,8 @@ needed.
* 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.
* 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
......@@ -123,6 +140,7 @@ The Index
* Index:: The full index.
@detailmenu
--- The Detailed Node Listing ---
Introduction
......@@ -136,9 +154,8 @@ Labels and References
* 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.
* varioref (LaTeX package):: How to create \vref instead of \ref.
* fancyref (LaTeX package):: How to create \fref instead of \ref.
Defining Label Environments
......@@ -176,7 +193,7 @@ The Index Phrases File
AUCTeX
* AUCTeX-RefTeX Interface:: How both packages work together
* Style Files:: AUCTeX's style files can support RefTeX
* Style Files:: @AUCTeX{}'s style files can support RefTeX
* Bib-Cite:: Hypertext reading of a document
Options, Keymaps, Hooks
......@@ -202,18 +219,18 @@ Options, Keymaps, Hooks
@chapter Introduction
@cindex Introduction
@b{Ref@TeX{}} is a specialized package for support of labels,
references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
and @code{\index}. Using these macros usually requires looking up
different parts of the document and searching through BibTeX database
files. @b{Ref@TeX{}} automates these time--consuming tasks almost
entirely. It also provides functions to display the structure of a
document and to move around in this structure quickly.
@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 @b{Ref@TeX{}}
in great depth. All you need to know to use @b{Ref@TeX{}} can be
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
......@@ -230,51 +247,122 @@ reports or suggestions.
@section Installation
@cindex Installation
@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version
20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x.
XEmacs 21.x users want to install the corresponding plug-in package
which is available from the @value{XEMACSFTP}. See the XEmacs 21.x
documentation on package installation for details.
@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) can get a copy
of the @b{Ref@TeX{}} distribution from the maintainers web-page.
@xref{Imprint}, for more information.
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.
@section Environment
@cindex Finding files
@cindex BibTeX database files, not found
@cindex TeX files, not found
@cindex @code{TEXINPUTS}, environment variable
@cindex @code{BIBINPUTS}, environment variable
@subsection Building and Installing
@b{Ref@TeX{}} needs to access all files which are part of a multifile
document, and the BibTeX database files requested by the
@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
require a search path, i.e. a list of directories to check. Normally
this list is stored in the environment variables @code{TEXINPUTS} and
@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
systems these variables do not contain the full search path. If
@b{Ref@TeX{}} does not work for you because it cannot find some files,
read @ref{Finding Files}.
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
@section Entering @b{Ref@TeX{}} Mode
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 @b{Ref@TeX{}} Mode on and off in a particular buffer, use
@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
files, add the following lines to your @file{.emacs} file:
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 @b{Ref@TeX{}} in a Nutshell
@section @RefTeX{} in a Nutshell
@cindex Quick-Start
@cindex Getting Started
@cindex RefTeX in a Nutshell
......@@ -289,7 +377,7 @@ can jump quickly to every part of your document. Press @kbd{?} to get
help.
@item
@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
@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
......@@ -300,7 +388,7 @@ additional labeled environments you have defined yourself (variable
@item
@b{Creating Labels}@*
Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
@b{Ref@TeX{}} will either
@RefTeX{} will either
@itemize @minus
@item
derive a label from context (default for section labels)
......@@ -325,7 +413,7 @@ into the original buffer.
@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
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}@}}
......@@ -334,9 +422,9 @@ different macros).
@item
@b{Index Support}@*
@b{Ref@TeX{}} helps to enter index entries. It also compiles all
@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. @b{Ref@TeX{}} knows about the
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.
......@@ -354,7 +442,7 @@ and enter the arguments with completion.
@b{The Index Phrases File (Delayed Indexing)}@*
Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
the current word or selection to a special @emph{index phrase file}.
@b{Ref@TeX{}} can later search the document for occurrences of these
@RefTeX{} can later search the document for occurrences of these
phrases and let you interactively index the matches.
@item
......@@ -366,11 +454,11 @@ all entries.
@page
@item @b{Viewing Cross-References}@*
When point is on the @var{key} argument of a cross--referencing macro
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
@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
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
......@@ -380,12 +468,12 @@ will automatically be displayed in the echo area.
@b{Multifile Documents}@*
Multifile Documents are fully supported. The included files must have a
file variable @code{TeX-master} or @code{tex-main-file} pointing to the
master file. @b{Ref@TeX{}} provides cross-referencing information from
master file. @RefTeX{} provides cross-referencing information from
all parts of the document, and across document borders
(@file{xr.sty}).
@item
@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
@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
......@@ -394,20 +482,20 @@ commands described above with a raw @kbd{C-u} prefix, or press the
buffer, or the index buffer.
@item
@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
@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
@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
@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
To integrate RefTeX with @AUCTeX{}, use
@lisp
(setq reftex-plug-into-AUCTeX t)
@end lisp
To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
To make your own @LaTeX{} macro definitions known to @RefTeX{},
customize the variables
@example
@code{reftex-label-alist} @r{(for label macros/environments)}
......@@ -417,15 +505,15 @@ customize the variables
@code{reftex-index-default-macro} @r{(to set the default macro)}
@end example
If you have a large number of macros defined, you may want to write
an AUCTeX style file to support them with both AUCTeX and
@b{Ref@TeX{}}.
an @AUCTeX{} style file to support them with both @AUCTeX{} and
@RefTeX{}.
@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
@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, of if you are curious what else might be
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 @b{Ref@TeX{}}. The second
a tutorial way how to use and customize @RefTeX{}. The second
part is a command and variable reference.
@end enumerate
......@@ -463,10 +551,10 @@ Prefix argument.
@tablesubheading{Moving around}
@item n
Goto next entry in the table of context.
Goto next entry in the table of contents.
@item p
Goto previous entry in the table of context.
Goto previous entry in the table of contents.
@item C-c C-n
Goto next section heading. Useful when many labels and index entries
......@@ -506,7 +594,7 @@ always show the location corresponding to the line at point in the
@file{*toc*} buffer. This is similar to pressing @key{SPC} after each
cursor motion. The default for this flag can be set with the variable
@code{reftex-toc-follow-mode}. Note that only context in files already
visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
visited is shown. @RefTeX{} will not visit a file just for follow
mode. See, however, the variable
@code{reftex-revisit-to-follow}.
......@@ -521,8 +609,8 @@ Show calling point in another window. This is the point from where
Promote the current section. This will convert @code{\section} to
@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
an active region, all sections in the region will be promoted, including
the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh
document scan before executing this command - if necessary, it will
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.
......@@ -578,7 +666,7 @@ variable @code{reftex-toc-include-file-boundaries}.
Toggle the display of labels in the @file{*toc*} buffer. The default
for this flag can be set with the variable
@code{reftex-toc-include-labels}. When called with a prefix argument,
@b{Ref@TeX{}} will prompt for a label type and include only labels of
@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.
......@@ -587,7 +675,7 @@ indicator shows which labels are included.
Toggle the display of index entries in the @file{*toc*} buffer. The
default for this flag can be set with the variable
@code{reftex-toc-include-index-entries}. When called with a prefix
argument, @b{Ref@TeX{}} will prompt for a specific index and include
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.
......@@ -605,18 +693,18 @@ document.
@item r
@vindex reftex-enable-partial-scans
Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
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*}
Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*toc*}
buffer.
@item x
Switch to the @file{*toc*} buffer of an external document. When the
current document is using the @code{xr} package (@pxref{xr (LaTeX
package)}), @b{Ref@TeX{}} will switch to one of the external
package)}), @RefTeX{} will switch to one of the external
documents.
......@@ -669,11 +757,11 @@ recentering of the TOC window on the current frame with
@cindex LaTeX classes, KOMA-Script
@cindex TOC entries for environments
@vindex reftex-section-levels
The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
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
@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.
......@@ -686,21 +774,21 @@ example.
@cindex Label environment
@cindex @code{\label}
LaTeX provides a powerful mechanism to deal with cross--references in a
@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
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
footnotes, items in enumerate lists etc. @LaTeX{} is context sensitive in
doing this: A label defined in a figure environment automatically
records the figure counter, not the section counter.
Several different environments can share a common counter and therefore
a common label category. E.g. labels in both @code{equation} and
@code{eqnarray} environments record the value of the same counter - the
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
......@@ -709,9 +797,8 @@ equation counter.
* 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.
* varioref (LaTeX package):: How to create \vref instead of \ref.
* fancyref (LaTeX package):: How to create \fref instead of \ref.
@end menu
@node Creating Labels, Referencing Labels, , Labels and References
......@@ -722,12 +809,12 @@ equation counter.
@kindex C-c (
@findex reftex-label
In order to create a label in a LaTeX document, press @kbd{C-c (}
(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
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. @b{Ref@TeX{}} has
3 different modes to create this mark.
indicating the type of the label and a unique mark. @RefTeX{} has
three different modes to create this mark.
@enumerate
@item
......@@ -735,10 +822,10 @@ indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
@vindex reftex-derive-label-parameters
@vindex reftex-label-illegal-re
@vindex reftex-abbrev-parameters
A label can be derived from context. This means, @b{Ref@TeX{}} takes
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. @b{Ref@TeX{}} will therefore strip the accent from
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
......@@ -746,28 +833,28 @@ change things: @code{reftex-translate-to-ascii-function},
@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
@code{reftex-abbrev-parameters}.}. This works best for section labels,
where the section heading is used to construct a label. In fact,
@b{Ref@TeX{}}'s default settings use this method only for section
@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. @b{Ref@TeX{}}'s default settings use this method
for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
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 @b{Ref@TeX{}} will provide context to
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. @b{Ref@TeX{}} uses this for figures and