Remove hand-written node pointers in doc/misc/reftex.texi
[bpt/emacs.git] / doc / misc / reftex.texi
CommitLineData
4009494e
GM
1\input texinfo @c -*-texinfo-*-
2@c %**start of header
db78a8cb 3@setfilename ../../info/reftex
4009494e
GM
4@settitle RefTeX User Manual
5@synindex ky cp
6@syncodeindex vr cp
7@syncodeindex fn cp
8
4f595e15
RA
9@ifnottex
10@macro RefTeX {}
11Ref@TeX{}
12@end macro
13@macro AUCTeX {}
14AUC@TeX{}
15@end macro
16@macro BibTeX {}
17Bib@TeX{}
18@end macro
19@macro ConTeXt {}
20Con@TeX{}t
21@end macro
22@end ifnottex
23@tex
24\gdef\RefTeX{Ref\TeX}
25\gdef\AUCTeX{AUC\TeX}
26\gdef\BibTeX{Bib\TeX}
27\gdef\ConTeXt{Con\TeX t}
28@end tex
29
07f133bf 30@include emacsver.texi
4f595e15
RA
31
32@set VERSION @value{EMACSVER}
33@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,@AUCTeX{} web site}
34@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,@RefTeX{} web page}
4009494e 35@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers}
4f595e15
RA
36@set MAINTAINER the @AUCTeX{} project
37@set SUPPORTADDRESS @AUCTeX{} user mailing list (@email{auctex@@gnu.org})
38@set DEVELADDRESS @AUCTeX{} developer mailing list (@email{auctex-devel@@gnu.org})
39@set BUGADDRESS @AUCTeX{} bug mailing list (@email{bug-auctex@@gnu.org})
40@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs FTP site}
4009494e
GM
41@c %**end of header
42
43@copying
4f595e15
RA
44This manual documents @RefTeX{} (version @value{VERSION}), a package
45to do labels, references, citations and indices for LaTeX documents
46with Emacs.
4009494e 47
f99f1641 48Copyright @copyright{} 1997--2012 Free Software Foundation, Inc.
4009494e
GM
49
50@quotation
51Permission is granted to copy, distribute and/or modify this document
6a2c4aec 52under the terms of the GNU Free Documentation License, Version 1.3 or
4009494e 53any later version published by the Free Software Foundation; with no
debf4439
GM
54Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
55and with the Back-Cover Texts as in (a) below. A copy of the license
56is included in the section entitled ``GNU Free Documentation License''.
4009494e 57
6f093307 58(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
6bf430d1 59modify this GNU manual.''
4009494e
GM
60@end quotation
61@end copying
62
0c973505 63@dircategory Emacs misc features
4009494e 64@direntry
62e034c2
GM
65* RefTeX: (reftex). Emacs support for LaTeX cross-references
66 and citations.
4009494e
GM
67@end direntry
68
69@finalout
70
71@c Macro definitions
72
73@c Subheadings inside a table. Need a difference between info and the rest.
74@macro tablesubheading{text}
75@ifinfo
76@subsubheading \text\
77@end ifinfo
78@ifnotinfo
79@item @b{\text\}
80@end ifnotinfo
81@end macro
82
83@titlepage
4f595e15
RA
84@title @RefTeX{} User Manual
85@subtitle Support for @LaTeX{} labels, references, citations and index entries with GNU Emacs
86@subtitle Version @value{VERSION}
4009494e
GM
87
88@author by Carsten Dominik
89@page
90@vskip 0pt plus 1filll
91@insertcopying
92@end titlepage
93
5dc584b5
KB
94@summarycontents
95@contents
96
4009494e 97@ifnottex
6d1962b3 98@node Top
4f595e15 99@top @RefTeX{}
4009494e 100
4f595e15
RA
101@RefTeX{} is a package for managing Labels, References, Citations and
102index entries with GNU Emacs.
4009494e 103
4f595e15 104This manual documents @RefTeX{} version @value{VERSION}.
4009494e 105
4f595e15
RA
106Don't be discouraged by the size of this manual, which covers @RefTeX{}
107in great depth. All you need to know to use @RefTeX{} can be summarized
108on two pages (@pxref{RefTeX in a Nutshell}). You can go back later to
109other parts of this document when needed.
5dc584b5 110
4009494e
GM
111@menu
112* Introduction:: Quick-Start information.
113
114* Table of Contents:: A Tool to move around quickly.
115* Labels and References:: Creating and referencing labels.
116* Citations:: Creating Citations.
117* Index Support:: Creating and Checking Index Entries.
118* Viewing Cross-References:: Who references or cites what?
119
120* RefTeXs Menu:: The Ref menu in the menubar.
121* Key Bindings:: The default key bindings.
122* Faces:: Fontification of RefTeX's buffers.
123* Multifile Documents:: Document spread over many files.
124* Language Support:: How to support other languages.
4f595e15 125* Finding Files:: Included @TeX{} files and @BibTeX{} .bib files.
4009494e 126* Optimizations:: When RefTeX is too slow.
6d1962b3 127* AUCTeX:: Cooperation with @AUCTeX{}.
4009494e
GM
128* Problems and Work-Arounds:: First Aid.
129* Imprint:: Author, Web-site, Thanks
130
131* Commands:: Which are the available commands.
132* Options:: How to extend and configure RefTeX.
4009494e
GM
133* Changes:: A List of recent changes to RefTeX.
134* GNU Free Documentation License:: The license for this documentation.
135
136The Index
137
138* Index:: The full index.
139
140@detailmenu
4f595e15 141 --- The Detailed Node Listing ---
4009494e
GM
142
143Introduction
144
145* Installation:: How to install and activate RefTeX.
146* RefTeX in a Nutshell:: A brief summary and quick guide.
147
148Labels and References
149
150* Creating Labels::
151* Referencing Labels::
152* Builtin Label Environments:: The environments RefTeX knows about.
153* Defining Label Environments:: ... and environments it doesn't.
154* Reference Info:: View the label corresponding to a \ref.
4f595e15 155* Reference Styles:: Macros to be used instead of \ref.
4009494e 156* xr (LaTeX package):: References to external documents.
4009494e
GM
157
158Defining Label Environments
159
160* Theorem and Axiom:: Defined with @code{\newenvironment}.
161* Quick Equation:: When a macro sets the label type.
162* Figure Wrapper:: When a macro argument is a label.
163* Adding Magic Words:: Other words for other languages.
164* Using \eqref:: How to switch to this AMS-LaTeX macro.
165* Non-Standard Environments:: Environments without \begin and \end
166* Putting it Together:: How to combine many entries.
167
168Citations
169
170* Creating Citations:: How to create them.
171* Citation Styles:: Natbib, Harvard, Chicago and Co.
172* Citation Info:: View the corresponding database entry.
173* Chapterbib and Bibunits:: Multiple bibliographies in a Document.
174* Citations Outside LaTeX:: How to make citations in Emails etc.
9858f6c3 175* BibTeX Database Subsets:: Extract parts of a big database.
4009494e
GM
176
177Index Support
178
179* Creating Index Entries:: Macros and completion of entries.
180* The Index Phrases File:: A special file for global indexing.
181* Displaying and Editing the Index:: The index editor.
182* Builtin Index Macros:: The index macros RefTeX knows about.
183* Defining Index Macros:: ... and macros it doesn't.
184
185The Index Phrases File
186
187* Collecting Phrases:: Collecting from document or external.
188* Consistency Checks:: Check for duplicates etc.
189* Global Indexing:: The interactive indexing process.
190
191AUCTeX
192
193* AUCTeX-RefTeX Interface:: How both packages work together
4f595e15 194* Style Files:: @AUCTeX{}'s style files can support RefTeX
4009494e
GM
195* Bib-Cite:: Hypertext reading of a document
196
197Options, Keymaps, Hooks
198
199* Options (Table of Contents)::
200* Options (Defining Label Environments)::
201* Options (Creating Labels)::
202* Options (Referencing Labels)::
203* Options (Creating Citations)::
204* Options (Index Support)::
205* Options (Viewing Cross-References)::
206* Options (Finding Files)::
207* Options (Optimizations)::
208* Options (Fontification)::
209* Options (Misc)::
210
211@end detailmenu
212@end menu
213
214@end ifnottex
215
6d1962b3 216@node Introduction
4009494e
GM
217@chapter Introduction
218@cindex Introduction
219
4f595e15
RA
220@RefTeX{} is a specialized package for support of labels, references,
221citations, and the index in @LaTeX{}. @RefTeX{} wraps itself round four
222@LaTeX{} macros: @code{\label}, @code{\ref}, @code{\cite}, and
223@code{\index}. Using these macros usually requires looking up different
224parts of the document and searching through @BibTeX{} database files.
225@RefTeX{} automates these time-consuming tasks almost entirely. It also
226provides functions to display the structure of a document and to move
227around in this structure quickly.
4009494e
GM
228
229@iftex
4f595e15
RA
230Don't be discouraged by the size of this manual, which covers @RefTeX{}
231in great depth. All you need to know to use @RefTeX{} can be
4009494e
GM
232summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
233back later to other parts of this document when needed.
234@end iftex
235
236@xref{Imprint}, for information about who to contact for help, bug
237reports or suggestions.
238
239@menu
240* Installation:: How to install and activate RefTeX.
241* RefTeX in a Nutshell:: A brief summary and quick guide.
242@end menu
243
6d1962b3 244@node Installation
4009494e
GM
245@section Installation
246@cindex Installation
247
4f595e15
RA
248@RefTeX{} has been bundled and pre-installed with Emacs since
249version 20.2. It has also been bundled and pre-installed with XEmacs
25019.16--20.x. XEmacs 21.x users want to install the corresponding
251plug-in package which is available from the @value{XEMACSFTP}. See the
252XEmacs 21.x documentation on package installation for details.
4009494e 253
4f595e15
RA
254Users of earlier Emacs distributions (including Emacs 19) or people
255craving for new features and bugs can get a copy of the @RefTeX{}
256distribution from the maintainer's web page. @xref{Imprint}, for more
257information. The following instructions will guide you through the
258process of installing such a distribution.
4009494e 259
4f595e15 260@subsection Building and Installing
4009494e 261
4f595e15
RA
262Note: Currently installation is supported for Emacs only. XEmacs users
263might want to refer to the @RefTeX{} package available through the
264package system of XEmacs.
265
266@subsubheading Installation with make
267
268In order to install RefTeX, unpack the distribution and edit the header
269of the Makefile. Basically, you need to change the path specifications
270for Emacs Lisp files and info files. Also, enter the name of your Emacs
271executable (usually either @samp{emacs} or @samp{xemacs}).
272
1df7defd 273Then, type
4f595e15
RA
274
275@example
276make
277make install
278@end example
279
280to compile and install the code and documentation.
281
282Per default @RefTeX{} is installed in its own subdirectory which might
283not be on your load path. In this case, add it to load path with a
284command like the following, replacing the sample directory with the one
285where @RefTeX{} is installed in your case.
286
287@example
288(add-to-list 'load-path "/path/to/reftex")
289@end example
4009494e 290
4f595e15
RA
291Put this command into your init file before other @RefTeX{}-related
292settings.
293
294@subsubheading Installation by Hand
295
296If you want to get your hands dirty, there is also the possibility to
297install by manually copying files.
298
299@enumerate a
300@item
301Copy the reftex*.el lisp files to a directory on your load path. Make
302sure that no old copy of @RefTeX{} shadows these files.
303@item
304Byte compile the files. The sequence of compiling should be:
305reftex-var.el, reftex.el, and then all the others.
306@item
307Copy the info file reftex.info to the info directory.
308@end enumerate
309
310@subsection Loading @RefTeX{}
311
312In order to make the most important functions for entering @RefTeX{}
313mode available add the following line to your init file.
314
315@example
316(require 'reftex)
317@end example
318
319@subsection Entering @RefTeX{} Mode
4009494e
GM
320
321@findex turn-on-reftex
322@findex reftex-mode
323@vindex LaTeX-mode-hook
324@vindex latex-mode-hook
4f595e15
RA
325To turn @RefTeX{} Mode on and off in a particular buffer, use
326@kbd{M-x reftex-mode @key{RET}}. To turn on @RefTeX{} Mode for all
327LaTeX files, add the following lines to your @file{.emacs} file:
4009494e
GM
328
329@example
330(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
331(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
332@end example
333
4f595e15
RA
334That's all!
335
336To get started, read the documentation, in particular the
337summary. (@pxref{RefTeX in a Nutshell})
338
339In order to produce a printed version of the documentation, use
340@code{make pdf} to produce a reftex.pdf file. Analogously you can use
341the @code{dvi}, @code{ps}, or @code{html} targets to create DVI,
342PostScript or HTML files.
343
344@subsection Environment
345@cindex Finding files
346@cindex BibTeX database files, not found
347@cindex TeX files, not found
348@cindex @code{TEXINPUTS}, environment variable
349@cindex @code{BIBINPUTS}, environment variable
350
351@RefTeX{} needs to access all files which are part of a multifile
352document, and the BibTeX database files requested by the
353@code{\bibliography} command. To find these files, @RefTeX{} will
1df7defd 354require a search path, i.e., a list of directories to check. Normally
4f595e15
RA
355this list is stored in the environment variables @code{TEXINPUTS} and
356@code{BIBINPUTS} which are also used by @RefTeX{}. However, on some
357systems these variables do not contain the full search path. If
358@RefTeX{} does not work for you because it cannot find some files,
359@xref{Finding Files}.
360
4009494e 361@page
6d1962b3 362@node RefTeX in a Nutshell
4f595e15 363@section @RefTeX{} in a Nutshell
4009494e
GM
364@cindex Quick-Start
365@cindex Getting Started
366@cindex RefTeX in a Nutshell
367@cindex Nutshell, RefTeX in a
368
369@enumerate
370@item
371@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
372a table of contents of the document. This buffer can display sections,
373labels and index entries defined in the document. From the buffer, you
374can jump quickly to every part of your document. Press @kbd{?} to get
375help.
376
377@item
4f595e15 378@b{Labels and References}@* @RefTeX{} helps to create unique labels
4009494e
GM
379and to find the correct key for references quickly. It distinguishes
380labels for different environments, knows about all standard
381environments (and many others), and can be configured to recognize any
382additional labeled environments you have defined yourself (variable
383@code{reftex-label-alist}).
384
385@itemize @bullet
386@item
387@b{Creating Labels}@*
388Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
4f595e15 389@RefTeX{} will either
4009494e
GM
390@itemize @minus
391@item
392derive a label from context (default for section labels)
393@item
394prompt for a label string (default for figures and tables) or
395@item
396insert a simple label made of a prefix and a number (all other
397environments)
398@end itemize
399@noindent
400Which labels are created how is configurable with the variable
401@code{reftex-insert-label-flags}.
402
403@item
404@b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
405(@code{reftex-reference}). This shows an outline of the document with
406all labels of a certain type (figure, equation,...) and some label
407context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
408into the original buffer.
409@end itemize
410
411@item
412@b{Citations}@*
413Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
4f595e15 414regular expression to search in current @BibTeX{} database files (as
4009494e
GM
415specified in the @code{\bibliography} command) and pull out a list of
416matches for you to choose from. The list is @emph{formatted} and
417sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
418(see the variable @code{reftex-cite-format} if you want to insert
419different macros).
420
421@item
422@b{Index Support}@*
4f595e15 423@RefTeX{} helps to enter index entries. It also compiles all
4009494e 424entries into an alphabetically sorted @file{*Index*} buffer which you
4f595e15 425can use to check and edit the entries. @RefTeX{} knows about the
4009494e
GM
426standard index macros and can be configured to recognize any additional
427macros you have defined (@code{reftex-index-macros}). Multiple indices
428are supported.
429
430@itemize @bullet
431@item
432@b{Creating Index Entries}@*
433To index the current selection or the word at point, type @kbd{C-c /}
434(@code{reftex-index-selection-or-word}). The default macro
435@code{reftex-index-default-macro} will be used. For a more complex entry
436type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
437and enter the arguments with completion.
438
439@item
440@b{The Index Phrases File (Delayed Indexing)}@*
441Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
442the current word or selection to a special @emph{index phrase file}.
4f595e15 443@RefTeX{} can later search the document for occurrences of these
4009494e
GM
444phrases and let you interactively index the matches.
445
446@item
447@b{Displaying and Editing the Index}@*
448To display the compiled index in a special buffer, type @kbd{C-c >}
449(@code{reftex-display-index}). From that buffer you can check and edit
450all entries.
451@end itemize
452
453@page
454@item @b{Viewing Cross-References}@*
4f595e15 455When point is on the @var{key} argument of a cross-referencing macro
4009494e 456(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
4f595e15 457@code{\index}, and variations) or inside a @BibTeX{} database entry, you
4009494e 458can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
4f595e15 459corresponding locations in the document and associated @BibTeX{} database
4009494e
GM
460files. @*
461When the enclosing macro is @code{\cite} or @code{\ref} and no other
462message occupies the echo area, information about the citation or label
463will automatically be displayed in the echo area.
464
465@item
466@b{Multifile Documents}@*
467Multifile Documents are fully supported. The included files must have a
468file variable @code{TeX-master} or @code{tex-main-file} pointing to the
4f595e15 469master file. @RefTeX{} provides cross-referencing information from
4009494e
GM
470all parts of the document, and across document borders
471(@file{xr.sty}).
472
473@item
4f595e15 474@b{Document Parsing}@* @RefTeX{} needs to parse the document in
4009494e
GM
475order to find labels and other information. It does it automatically
476once and updates its list internally when @code{reftex-label} and
477@code{reftex-index} are used. To enforce reparsing, call any of the
478commands described above with a raw @kbd{C-u} prefix, or press the
479@kbd{r} key in the label selection buffer, the table of contents
480buffer, or the index buffer.
481
482@item
4f595e15
RA
483@b{@AUCTeX{}} @* If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can
484cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). @AUCTeX{}
4009494e 485contains style files which trigger appropriate settings in
4f595e15 486@RefTeX{}, so that for many of the popular @LaTeX{} packages no
4009494e
GM
487additional customizations will be necessary.
488
489@item
490@b{Useful Settings}@*
4f595e15 491To integrate RefTeX with @AUCTeX{}, use
4009494e
GM
492@lisp
493(setq reftex-plug-into-AUCTeX t)
494@end lisp
495
4f595e15 496To make your own @LaTeX{} macro definitions known to @RefTeX{},
4009494e
GM
497customize the variables
498@example
499@code{reftex-label-alist} @r{(for label macros/environments)}
500@code{reftex-section-levels} @r{(for sectioning commands)}
501@code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
502@code{reftex-index-macros} @r{(for @code{\index}-like macros)}
503@code{reftex-index-default-macro} @r{(to set the default macro)}
504@end example
505If you have a large number of macros defined, you may want to write
4f595e15
RA
506an @AUCTeX{} style file to support them with both @AUCTeX{} and
507@RefTeX{}.
4009494e 508
4f595e15 509@item @b{Where Next?}@* Go ahead and use @RefTeX{}. Use its menus
4009494e
GM
510until you have picked up the key bindings. For an overview of what you
511can do in each of the different special buffers, press @kbd{?}. Read
4f595e15 512the manual if you get stuck, or if you are curious what else might be
4009494e 513available. The first part of the manual explains in
4f595e15 514a tutorial way how to use and customize @RefTeX{}. The second
4009494e
GM
515part is a command and variable reference.
516@end enumerate
517
6d1962b3 518@node Table of Contents
4009494e
GM
519@chapter Table of Contents
520@cindex @file{*toc*} buffer
521@cindex Structure editing
522@cindex Table of contents buffer
523@findex reftex-toc
524@kindex C-c =
525
526Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
527contents of the document. By default, this @file{*toc*} buffer shows
528only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
529can display all labels and index entries defined in the document as
530well.
531
532With the cursor in any of the lines denoting a location in the
533document, simple key strokes will display the corresponding part in
534another window, jump to that location, or perform other actions.
535
536@kindex ?
537Here is a list of special commands in the @file{*toc*} buffer. A
538summary of this information is always available by pressing
539@kbd{?}.
540
541@table @kbd
542
543@tablesubheading{General}
544@item ?
545Display a summary of commands.
546
547@item 0-9, -
548Prefix argument.
549
550@tablesubheading{Moving around}
551@item n
4f595e15 552Goto next entry in the table of contents.
4009494e
GM
553
554@item p
4f595e15 555Goto previous entry in the table of contents.
4009494e
GM
556
557@item C-c C-n
558Goto next section heading. Useful when many labels and index entries
559separate section headings.
560
561@item C-c C-p
562Goto previous section heading.
563
564@item N z
565Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps
566to section 3.
567
568@tablesubheading{Access to document locations}
569@item @key{SPC}
570Show the corresponding location in another window. This command does
571@emph{not} select that other window.
572
573@item @key{TAB}
574Goto the location in another window.
575
576@item @key{RET}
577Go to the location and hide the @file{*toc*} buffer. This will restore
578the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
579called.
580
581@item mouse-2
582@vindex reftex-highlight-selection
583Clicking with mouse button 2 on a line has the same effect as @key{RET}.
584See also variable @code{reftex-highlight-selection}, @ref{Options
585(Fontification)}.
586
587@item f
588@vindex reftex-toc-follow-mode
589@vindex reftex-revisit-to-follow
590Toggle follow mode. When follow mode is active, the other window will
591always show the location corresponding to the line at point in the
592@file{*toc*} buffer. This is similar to pressing @key{SPC} after each
593cursor motion. The default for this flag can be set with the variable
594@code{reftex-toc-follow-mode}. Note that only context in files already
4f595e15 595visited is shown. @RefTeX{} will not visit a file just for follow
4009494e
GM
596mode. See, however, the variable
597@code{reftex-revisit-to-follow}.
598
599@item .
600Show calling point in another window. This is the point from where
601@code{reftex-toc} was last called.
602
603@page
604@tablesubheading{Promotion and Demotion}
605
606@item <
607Promote the current section. This will convert @code{\section} to
608@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
609an active region, all sections in the region will be promoted, including
4f595e15 610the one at point. To avoid mistakes, @RefTeX{} requires a fresh
f99f1641 611document scan before executing this command; if necessary, it will
4009494e
GM
612automatically do this scan and ask the user to repeat the promotion
613command.
614
615@item >
616Demote the current section. This is the opposite of promotion. It will
617convert @code{\chapter} to @code{\section} etc. If there is an active
618region, all sections in the region will be demoted, including the one at
619point.
620
621@item M-%
622Rename the label at point. While generally not recommended, this can be
623useful when a package like @file{fancyref} is used where the label
624prefix determines the wording of a reference. After a
625promotion/demotion it may be necessary to change a few labels from
626@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be
f99f1641 627used to do this; it launches a query replace to rename the definition
4009494e
GM
628and all references of a label.
629
630@tablesubheading{Exiting}
631@item q
632Hide the @file{*toc*} buffer, return to the position where
633@code{reftex-toc} was last called.
634
635@item k
636Kill the @file{*toc*} buffer, return to the position where
637@code{reftex-toc} was last called.
638
639@item C-c >
640Switch to the @file{*Index*} buffer of this document. With prefix
641@samp{2}, restrict the index to the section at point in the @file{*toc*}
642buffer.
643
644@tablesubheading{Controlling what gets displayed}
645
646@item t
647@vindex reftex-toc-max-level
648Change the maximum level of toc entries displayed in the @file{*toc*}
649buffer. Without prefix arg, all levels will be included. With prefix
650arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
651@var{arg} (3 in this case). Chapters are level 1, sections are level 2.
652The mode line @samp{T<>} indicator shows the current value. The default
653depth can be configured with the variable
654@code{reftex-toc-max-level}.
655
656@item F
657@vindex reftex-toc-include-file-boundaries
658Toggle the display of the file borders of a multifile document in the
659@file{*toc*} buffer. The default for this flag can be set with the
660variable @code{reftex-toc-include-file-boundaries}.
661
662@item l
663@vindex reftex-toc-include-labels
664Toggle the display of labels in the @file{*toc*} buffer. The default
665for this flag can be set with the variable
666@code{reftex-toc-include-labels}. When called with a prefix argument,
4f595e15 667@RefTeX{} will prompt for a label type and include only labels of
4009494e
GM
668the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
669indicator shows which labels are included.
670
671@item i
672@vindex reftex-toc-include-index-entries
673Toggle the display of index entries in the @file{*toc*} buffer. The
674default for this flag can be set with the variable
675@code{reftex-toc-include-index-entries}. When called with a prefix
4f595e15 676argument, @RefTeX{} will prompt for a specific index and include
4009494e
GM
677only entries in the selected index in the @file{*toc*} buffer. The mode
678line @samp{I<>} indicator shows which index is used.
679
680@item c
681@vindex reftex-toc-include-context
682Toggle the display of label and index context in the @file{*toc*}
683buffer. The default for this flag can be set with the variable
684@code{reftex-toc-include-context}.
685
686@tablesubheading{Updating the buffer}
687
688@item g
689Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
690document.
691
692@item r
693@vindex reftex-enable-partial-scans
4f595e15 694Reparse the @LaTeX{} document and rebuild the @file{*toc*} buffer. When
4009494e
GM
695@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
696location is defined in, not the entire document.
697
698@item C-u r
4f595e15 699Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*toc*}
4009494e
GM
700buffer.
701
702@item x
703Switch to the @file{*toc*} buffer of an external document. When the
704current document is using the @code{xr} package (@pxref{xr (LaTeX
4f595e15 705package)}), @RefTeX{} will switch to one of the external
4009494e
GM
706documents.
707
708
709@tablesubheading{Automatic recentering}
710
711@item d
712Toggle the display of a dedicated frame displaying just the @file{*toc*}
713buffer. Follow mode and visiting locations will not work that frame,
714but automatic recentering will make this frame always show your current
715editing location in the document (see below).
716
717@item a
718Toggle the automatic recentering of the @file{*toc*} buffer. When this
719option is on, moving around in the document will cause the @file{*toc*}
720to always highlight the current section. By default, this option is
721active while the dedicated @file{*TOC*} frame exists. See also the
722variable @code{reftex-auto-recenter-toc}.
723
724@end table
725
726@vindex reftex-toc-map
727In order to define additional commands for the @file{*toc*} buffer, the
728keymap @code{reftex-toc-map} may be used.
729
730@findex reftex-toc-recenter
731@vindex reftex-auto-recenter-toc
732@vindex reftex-idle-time
733@cindex @file{*toc*} buffer, recentering
734@cindex Table of contents buffer, recentering
735@kindex C-c -
736If you call @code{reftex-toc} while the @file{*toc*} buffer already
1df7defd 737exists, the cursor will immediately jump to the right place, i.e., the
4009494e
GM
738section from which @code{reftex-toc} was called will be highlighted.
739The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
740the @file{*toc*} buffer and highlight the correct line without actually
741selecting the @file{*toc*} window. This can be useful to quickly find
742out where in the document you currently are. You can also automate this
743by asking RefTeX to keep track of your current editing position in the
1df7defd 744TOC@. The TOC window will then be updated whenever you stop typing for
4009494e
GM
745more than @code{reftex-idle-time} seconds. By default this works only
746with the dedicated @file{*TOC*} frame. But you can also force automatic
747recentering of the TOC window on the current frame with
748@lisp
749(setq reftex-auto-recenter-toc t)
750@end lisp
751
752
753@cindex Sectioning commands
754@cindex KOMA-Script, LaTeX classes
755@cindex LaTeX classes, KOMA-Script
756@cindex TOC entries for environments
757@vindex reftex-section-levels
4f595e15 758The section macros recognized by @RefTeX{} are all @LaTeX{} section
4009494e
GM
759macros (from @code{\part} to @code{\subsubparagraph}) and the commands
760@code{\addchap} and @code{\addsec} from the KOMA-Script classes.
761Additional macros can be configured with the variable
4f595e15 762@code{reftex-section-levels}. It is also possible to add certain @LaTeX{}
4009494e
GM
763environments to the table of contents. This is probably only useful for
764theorem-like environments. @xref{Defining Label Environments}, for an
765example.
766
6d1962b3 767@node Labels and References
4009494e
GM
768@chapter Labels and References
769@cindex Labels in LaTeX
770@cindex References in LaTeX
771@cindex Label category
772@cindex Label environment
773@cindex @code{\label}
774
4f595e15 775@LaTeX{} provides a powerful mechanism to deal with cross-references in a
4009494e 776document. When writing a document, any part of it can be marked with a
4f595e15 777label, like @samp{\label@{mark@}}. @LaTeX{} records the current value of a
4009494e
GM
778certain counter when a label is defined. Later references to this label
779(like @samp{\ref@{mark@}}) will produce the recorded value of the
780counter.
781
782Labels can be used to mark sections, figures, tables, equations,
4f595e15 783footnotes, items in enumerate lists etc. @LaTeX{} is context sensitive in
4009494e
GM
784doing this: A label defined in a figure environment automatically
785records the figure counter, not the section counter.
786
787Several different environments can share a common counter and therefore
4f595e15 788a common label category. For example labels in both @code{equation} and
f99f1641 789@code{eqnarray} environments record the value of the same counter: the
4009494e
GM
790equation counter.
791
792@menu
793* Creating Labels::
794* Referencing Labels::
795* Builtin Label Environments:: The environments RefTeX knows about.
796* Defining Label Environments:: ... and environments it doesn't.
797* Reference Info:: View the label corresponding to a \ref.
4f595e15 798* Reference Styles:: Macros to be used instead of \ref.
4009494e 799* xr (LaTeX package):: References to external documents.
4009494e
GM
800@end menu
801
6d1962b3 802@node Creating Labels
4009494e
GM
803@section Creating Labels
804@cindex Creating labels
805@cindex Labels, creating
806@cindex Labels, deriving from context
807@kindex C-c (
808@findex reftex-label
809
4f595e15
RA
810In order to create a label in a @LaTeX{} document, press @kbd{C-c (}
811(@code{reftex-label}). Just like @LaTeX{}, @RefTeX{} is context sensitive
4009494e
GM
812and will figure out the environment it currently is in and adapt the
813label to that environment. A label usually consists of a short prefix
4f595e15
RA
814indicating the type of the label and a unique mark. @RefTeX{} has
815three different modes to create this mark.
4009494e
GM
816
817@enumerate
818@item
819@vindex reftex-translate-to-ascii-function
820@vindex reftex-derive-label-parameters
821@vindex reftex-label-illegal-re
822@vindex reftex-abbrev-parameters
4f595e15 823A label can be derived from context. This means, @RefTeX{} takes
4009494e
GM
824the context of the label definition and constructs a label from
825that@footnote{Note that the context may contain constructs which are
4f595e15 826invalid in labels. @RefTeX{} will therefore strip the accent from
4009494e
GM
827accented Latin-1 characters and remove everything else which is not
828valid in labels. This mechanism is safe, but may not be satisfactory
829for non-western languages. Check the following variables if you need to
830change things: @code{reftex-translate-to-ascii-function},
831@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
832@code{reftex-abbrev-parameters}.}. This works best for section labels,
833where the section heading is used to construct a label. In fact,
4f595e15 834@RefTeX{}'s default settings use this method only for section
4009494e
GM
835labels. You will be asked to confirm the derived label, or edit
836it.
837
838@item
839We may also use a simple unique number to identify a label. This is
840mostly useful for labels where it is difficult to come up with a very
4f595e15
RA
841good descriptive name. @RefTeX{}'s default settings use this method
842for equations, enumerate items and footnotes. The author of @RefTeX{}
4009494e
GM
843tends to write documents with many equations and finds it impossible
844to come up with good names for each of them. These simple labels are
845inserted without query, and are therefore very fast. Good descriptive
4f595e15 846names are not really necessary as @RefTeX{} will provide context to
4009494e
GM
847reference a label (@pxref{Referencing Labels}).
848
849@item
850The third method is to ask the user for a label. This is most
851useful for things which are easy to describe briefly and do not turn up
4f595e15 852too frequently in a document. @RefTeX{} uses this for figures and
4009494e
GM
853tables. Of course, one can enter the label directly by typing the full
854@samp{\label@{mark@}}. The advantage of using @code{reftex-label}
4f595e15 855anyway is that @RefTeX{} will know that a new label has been defined.
4009494e
GM
856It will then not be necessary to rescan the document in order to access
857this label later.
858@end enumerate
859
860@vindex reftex-insert-label-flags
861If you want to change the way certain labels are created, check out the
862variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
863Labels)}).
864
4f595e15 865If you are using @AUCTeX{} to write your @LaTeX{} documents, you can
4009494e 866set it up to delegate the creation of labels to
4f595e15 867@RefTeX{}. @xref{AUCTeX}, for more information.
4009494e 868
6d1962b3 869@node Referencing Labels
4009494e
GM
870@section Referencing Labels
871@cindex Referencing labels
872@cindex Labels, referencing
873@cindex Selection buffer, labels
874@cindex Selection process
875@cindex @code{\ref}
876@kindex C-c )
877@findex reftex-reference
878
879@vindex reftex-trust-label-prefix
4f595e15 880@RefTeX{} scans the document in order to find all labels. To make
4009494e
GM
881referencing labels easier, it assigns to each label a category, the
882@emph{label type} (for example section, table, figure, equation, etc.).
4f595e15 883In order to determine the label type, @RefTeX{} parses around each label
4009494e
GM
884to see in what kind of environments it is located. You can speed up
885the parsing by using type-specific prefixes for labels and configuring
886the variable @code{reftex-trust-label-prefix}.
887
4f595e15
RA
888Referencing Labels is really at the heart of @RefTeX{}. Press @kbd{C-c
889)} in order to reference a label (@code{reftex-reference}). This will
890start a selection process and finally insert the complete
891@samp{\ref@{label@}} into the buffer.
892
893@vindex reftex-ref-macro-prompt
894First, you can select which reference macro you want to use,
1df7defd 895e.g., @samp{\ref} or @samp{\pageref}. Later in the process you have
4f595e15
RA
896another chance to make this selection and you can therefore disable this
897step by customizing @code{reftex-ref-macro-prompt} if you find it too
898intrusive. @xref{Reference Styles}.
4009494e 899
4f595e15
RA
900Then, @RefTeX{} will determine the label category which is required.
901Often that can be figured out from context. For example, if you write
902@samp{As shown in eq.} and then press @kbd{C-c )}, @RefTeX{} knows that
903an equation label is going to be referenced. If it cannot figure out
904what label category is needed, it will query for one.
4009494e
GM
905
906You will then be presented with a label selection menu. This is a
907special buffer which contains an outline of the document along with all
908labels of the given label category. In addition, next to the label
909there will be one line of context of the label definition, which is some
910text in the buffer near the label definition. Usually this is
911sufficient to identify the label. If you are unsure about a certain
912label, pressing @key{SPC} will show the label definition point in
913another window.
914
4f595e15 915In order to reference a label, move the cursor to the correct label and
4009494e
GM
916press @key{RET}. You can also reference several labels with a single
917call to @code{reftex-reference} by marking entries with the @kbd{m}
918key (see below).
919
920@kindex ?
921Here is a list of special commands in the selection buffer. A summary
922of this information is always available from the selection process by
923pressing @kbd{?}.
924
925
926
927@table @kbd
928@tablesubheading{General}
929@item ?
930Show a summary of available commands.
931
932@item 0-9,-
933Prefix argument.
934
935@tablesubheading{Moving around}
936@item n
937Go to next label.
938
939@item p
940Go to previous label.
941
942@item b
943Jump back to the position where you last left the selection buffer.
944Normally this should get you back to the last referenced label.
945
946@item C-c C-n
947Goto next section heading.
948
949@item C-c C-p
950Goto previous section heading.
951
952@item N z
953Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to
954section 3.
955
956@tablesubheading{Displaying Context}
957@item @key{SPC}
958Show the surroundings of the definition of the current label in another
959window. See also the @kbd{f} key.
960
961@item f
962@vindex reftex-revisit-to-follow
963Toggle follow mode. When follow mode is active, the other window will
964always display the full context of the current label. This is similar
965to pressing @key{SPC} after each cursor motion. Note that only context
4f595e15 966in files already visited is shown. @RefTeX{} will not visit a file
4009494e
GM
967just for follow mode. See, however, the variable
968@code{reftex-revisit-to-follow}.
969
970@item .
971Show insertion point in another window. This is the point from where you
972called @code{reftex-reference}.
973
974@tablesubheading{Selecting a label and creating the reference}
975@item @key{RET}
976Insert a reference to the label at point into the buffer from which the
977selection process was started. When entries have been marked, @key{RET}
978references all marked labels.
979
980@item mouse-2
981@vindex reftex-highlight-selection
982Clicking with mouse button 2 on a label will accept it like @key{RET}
4f595e15
RA
983would. See also variable @code{reftex-highlight-selection},
984@ref{Options (Misc)}.
4009494e
GM
985
986@vindex reftex-multiref-punctuation
987@item m - + ,
988Mark the current entry. When several entries have been marked, pressing
989@kbd{RET} will accept all of them and place them into several
990@code{\ref} macros. The special markers @samp{,-+} also store a
991separator to be inserted before the corresponding reference. So marking
992six entries with the keys @samp{m , , - , +} will give a reference list
993like this (see the variable @code{reftex-multiref-punctuation})
994@example
995In eqs. (1), (2), (3)--(4), (5) and (6)
996@end example
997
998@item u
999Unmark a marked entry.
1000
1001@c FIXME: Do we need `A' as well for consistency?
1002@cindex LaTeX packages, @code{saferef}
1003@cindex @code{saferef}, LaTeX package
1004@item a
1005Accept the marked entries and put all labels as a comma-separated list
1006into one @emph{single} @code{\ref} macro. Some packages like
1007@file{saferef.sty} support multiple references in this way.
1008
1009@item l
1010Use the last referenced label(s) again. This is equivalent to moving to
1011that label and pressing @key{RET}.
1012
1013@item @key{TAB}
1014Enter a label with completion. This may also be a label which does not
1015yet exist in the document.
1016
1017@item v
4f595e15
RA
1018Cycle forward through active reference macros. The selected macro is
1019displayed by the @samp{S<...>} indicator in the mode line of the
1020selection buffer. This mechanism comes in handy if you are using
1021@LaTeX{} packages like @code{varioref} or @code{fancyref} and want to
1df7defd 1022use the special referencing macros they provide (e.g., @code{\vref} or
4f595e15 1023@code{\fref}) instead of @code{\ref}.
4009494e
GM
1024
1025@item V
4f595e15 1026Cycle backward through active reference macros.
4009494e
GM
1027
1028@tablesubheading{Exiting}
1029
1030@item q
1031Exit the selection process without inserting any reference into the
1032buffer.
1033
1034@tablesubheading{Controlling what gets displayed}
1035@vindex reftex-label-menu-flags
1036The defaults for the following flags can be configured with the variable
1037@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
1038
1039@item c
1040Toggle the display of the one-line label definition context in the
1041selection buffer.
1042
1043@item F
1044Toggle the display of the file borders of a multifile document in the
1045selection buffer.
1046
1047@item t
1048Toggle the display of the table of contents in the selection buffer.
1049With prefix @var{arg}, change the maximum level of toc entries displayed
4f595e15 1050to @var{arg}. Chapters are level 1, sections are level 2.
4009494e
GM
1051
1052@item #
1053Toggle the display of a label counter in the selection buffer.
1054
1055@item %
1056Toggle the display of labels hidden in comments in the selection
1057buffers. Sometimes, you may have commented out parts of your document.
4f595e15 1058If these parts contain label definitions, @RefTeX{} can still display
4009494e
GM
1059and reference these labels.
1060
1061@tablesubheading{Updating the buffer}
1062@item g
1063Update the menu. This will rebuilt the menu from the internal label
1064list, but not reparse the document (see @kbd{r}).
1065
1066@item r
1067@vindex reftex-enable-partial-scans
1068Reparse the document to update the information on all labels and rebuild
1069the menu. If the variable @code{reftex-enable-partial-scans} is
1070non-@code{nil} and your document is a multifile document, this will
1071reparse only a part of the document (the file in which the label at
1072point was defined).
1073
1074@item C-u r
1075Reparse the @emph{entire} document.
1076
1077@item s
1078Switch the label category. After prompting for another label category,
1079a menu for that category will be shown.
1080
1081@item x
4f595e15 1082Reference a label from an external document. With the @LaTeX{} package
4009494e
GM
1083@code{xr} it is possible to reference labels defined in another
1084document. This key will switch to the label menu of an external
1085document and let you select a label from there (@pxref{xr (LaTeX
1086package),,xr}).
1087
1088@end table
1089
1090@vindex reftex-select-label-map
1091In order to define additional commands for the selection process, the
1092keymap @code{reftex-select-label-map} may be used.
1093
6d1962b3 1094@node Builtin Label Environments
4009494e
GM
1095@section Builtin Label Environments
1096@cindex Builtin label environments
1097@cindex Label environments, builtin
1098@cindex Environments, builtin
1099@vindex reftex-label-alist
1100@vindex reftex-label-alist-builtin
1101
4f595e15 1102@RefTeX{} needs to be aware of the environments which can be referenced
1df7defd 1103with a label (i.e., which carry their own counters). By default, @RefTeX{}
4009494e 1104recognizes all labeled environments and macros discussed in @cite{The
4f595e15 1105@LaTeX{} Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
4009494e
GM
11061994.}. These are:
1107
1108@itemize @minus
1109@item
1110@cindex @code{figure}, LaTeX environment
1111@cindex @code{figure*}, LaTeX environment
1112@cindex @code{table}, LaTeX environment
1113@cindex @code{table*}, LaTeX environment
1114@cindex @code{equation}, LaTeX environment
1115@cindex @code{eqnarray}, LaTeX environment
1116@cindex @code{enumerate}, LaTeX environment
1117@cindex @code{\footnote}, LaTeX macro
1118@cindex LaTeX macro @code{footnote}
1119@cindex LaTeX core
1120@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
1121@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
4f595e15 1122the @LaTeX{} core stuff)
4009494e
GM
1123@item
1124@cindex AMS-LaTeX
1125@cindex @code{amsmath}, LaTeX package
1126@cindex LaTeX packages, @code{amsmath}
1127@cindex @code{align}, AMS-LaTeX environment
1128@cindex @code{gather}, AMS-LaTeX environment
1129@cindex @code{multline}, AMS-LaTeX environment
1130@cindex @code{flalign}, AMS-LaTeX environment
1131@cindex @code{alignat}, AMS-LaTeX environment
1132@cindex @code{xalignat}, AMS-LaTeX environment
1133@cindex @code{xxalignat}, AMS-LaTeX environment
1134@cindex @code{subequations}, AMS-LaTeX environment
1135@code{align}, @code{gather}, @code{multline}, @code{flalign},
1136@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
4f595e15 1137(from AMS-@LaTeX{}'s @file{amsmath.sty} package)
4009494e
GM
1138@item
1139@cindex @code{endnote}, LaTeX package
1140@cindex LaTeX packages, @code{endnote}
1141@cindex @code{\endnote}, LaTeX macro
1142the @code{\endnote} macro (from @file{endnotes.sty})
1143@item
1144@cindex @code{fancybox}, LaTeX package
1145@cindex LaTeX packages, @code{fancybox}
1146@cindex @code{Beqnarray}, LaTeX environment
1147@code{Beqnarray} (@file{fancybox.sty})
1148@item
1149@cindex @code{floatfig}, LaTeX package
1150@cindex LaTeX packages, @code{floatfig}
1151@cindex @code{floatingfig}, LaTeX environment
1152@code{floatingfig} (@file{floatfig.sty})
1153@item
1154@cindex @code{longtable}, LaTeX package
1155@cindex LaTeX packages, @code{longtable}
1156@cindex @code{longtable}, LaTeX environment
1157@code{longtable} (@file{longtable.sty})
1158@item
1159@cindex @code{picinpar}, LaTeX package
1160@cindex LaTeX packages, @code{picinpar}
1161@cindex @code{figwindow}, LaTeX environment
1162@cindex @code{tabwindow}, LaTeX environment
1163@code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
1164@item
1165@cindex @code{sidecap}, LaTeX package
1166@cindex LaTeX packages, @code{sidecap}
1167@cindex @code{SCfigure}, LaTeX environment
1168@cindex @code{SCtable}, LaTeX environment
1169@code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
1170@item
1171@cindex @code{rotating}, LaTeX package
1172@cindex LaTeX packages, @code{rotating}
1173@cindex @code{sidewaysfigure}, LaTeX environment
1174@cindex @code{sidewaystable}, LaTeX environment
1175@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
1176@item
1177@cindex @code{subfig}, LaTeX package
1178@cindex LaTeX packages, @code{subfigure}
1179@cindex @code{subfigure}, LaTeX environment
1180@cindex @code{subfigure*}, LaTeX environment
1181@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
1182(@file{subfigure.sty})
1183@item
1184@cindex @code{supertab}, LaTeX package
1185@cindex LaTeX packages, @code{supertab}
1186@cindex @code{supertabular}, LaTeX environment
1187@code{supertabular} (@file{supertab.sty})
1188@item
1189@cindex @code{wrapfig}, LaTeX package
1190@cindex LaTeX packages, @code{wrapfig}
1191@cindex @code{wrapfigure}, LaTeX environment
1192@code{wrapfigure} (@file{wrapfig.sty})
1193@end itemize
1194
1195If you want to use other labeled environments, defined with
4f595e15 1196@code{\newtheorem}, @RefTeX{} needs to be configured to recognize
4009494e
GM
1197them (@pxref{Defining Label Environments}).
1198
6d1962b3 1199@node Defining Label Environments
4009494e
GM
1200@section Defining Label Environments
1201@cindex Label environments, defining
1202
1203@vindex reftex-label-alist
4f595e15 1204@RefTeX{} can be configured to recognize additional labeled
4009494e
GM
1205environments and macros. This is done with the variable
1206@code{reftex-label-alist} (@pxref{Options (Defining Label
1207Environments)}). If you are not familiar with Lisp, you can use the
1208@code{custom} library to configure this rather complex variable. To do
1209this, use
1210
1211@example
1212@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
1213@end example
1214
1215@vindex reftex-label-alist-builtin
1216Here we will discuss a few examples, in order to make things clearer.
1217It can also be instructive to look at the constant
1218@code{reftex-label-alist-builtin} which contains the entries for
1219all the builtin environments and macros (@pxref{Builtin Label
1220Environments}).
1221
1222@menu
1223* Theorem and Axiom:: Defined with @code{\newenvironment}.
1224* Quick Equation:: When a macro sets the label type.
1225* Figure Wrapper:: When a macro argument is a label.
1226* Adding Magic Words:: Other words for other languages.
4f595e15 1227* Using \eqref:: How to switch to this AMS-@LaTeX{} macro.
4009494e
GM
1228* Non-Standard Environments:: Environments without \begin and \end
1229* Putting it Together:: How to combine many entries.
1230@end menu
1231
6d1962b3 1232@node Theorem and Axiom
4009494e
GM
1233@subsection Theorem and Axiom Environments
1234@cindex @code{theorem}, newtheorem
1235@cindex @code{axiom}, newtheorem
1236@cindex @code{\newtheorem}
1237
4f595e15 1238Suppose you are using @code{\newtheorem} in @LaTeX{} in order to define two
4009494e
GM
1239new environments, @code{theorem} and @code{axiom}
1240
1241@example
1242\newtheorem@{axiom@}@{Axiom@}
1243\newtheorem@{theorem@}@{Theorem@}
1244@end example
1245
1246@noindent
1247to be used like this:
1248
1249@example
1250\begin@{axiom@}
1251\label@{ax:first@}
1252 ....
1253\end@{axiom@}
1254@end example
1255
4f595e15 1256So we need to tell @RefTeX{} that @code{theorem} and @code{axiom} are new
4009494e 1257labeled environments which define their own label categories. We can
1df7defd 1258either use Lisp to do this (e.g., in @file{.emacs}) or use the custom
4009494e
GM
1259library. With Lisp it would look like this
1260
1261@lisp
1262(setq reftex-label-alist
1263 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1264 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3)))
1265@end lisp
1266
1267The type indicator characters @code{?a} and @code{?h} are used for
4f595e15 1268prompts when @RefTeX{} queries for a label type. @code{?h}
4009494e
GM
1269was chosen for @code{theorem} since @code{?t} is already taken by
1270@code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
1271@code{?i}, @code{?n} are already used for standard environments.
1272
1273@noindent
1274The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
1275@samp{thr:}, respectively. @xref{AUCTeX}, for information on how
4f595e15
RA
1276@AUCTeX{} can use @RefTeX{} to automatically create labels when a new
1277environment is inserted into a buffer. Additionally, the following
1278needs to be added to one's .emacs file before @AUCTeX{} will
1279automatically create labels for the new environments.
4009494e
GM
1280
1281@lisp
1282(add-hook 'LaTeX-mode-hook
1283 (lambda ()
1284 (LaTeX-add-environments
1285 '("axiom" LaTeX-env-label)
1286 '("theorem" LaTeX-env-label))))
1287@end lisp
1288
1289
1290@noindent
1291The @samp{~\ref@{%s@}} is a format string indicating how to insert
1292references to these labels.
1293
1294@noindent
1295The next item indicates how to grab context of the label definition.
1296@itemize @minus
1297@item
1298@code{t} means to get it from a default location (from the beginning of
1299a @code{\macro} or after the @code{\begin} statement). @code{t} is
1300@emph{not} a good choice for eqnarray and similar environments.
1301@item
1302@code{nil} means to use the text right after the label definition.
1303@item
1304For more complex ways of getting context, see the variable
1305@code{reftex-label-alist} (@ref{Options (Defining Label
1306Environments)}).
1307@end itemize
1308
1309The following list of strings is used to guess the correct label type
4f595e15 1310from the word before point when creating a reference. For example if you
4009494e 1311write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
4f595e15 1312@RefTeX{} will know that you are looking for a theorem label and
4009494e
GM
1313restrict the menu to only these labels without even asking.
1314
1315The final item in each entry is the level at which the environment
1316should produce entries in the table of context buffer. If the number is
1317positive, the environment will produce numbered entries (like
1318@code{\section}), if it is negative the entries will be unnumbered (like
1319@code{\section*}). Use this only for environments which structure the
1320document similar to sectioning commands. For everything else, omit the
1321item.
1322
1323To do the same configuration with @code{customize}, you need to click on
1324the @code{[INS]} button twice to create two templates and fill them in
1325like this:
1326
1327@example
1328Reftex Label Alist: [Hide]
1329[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1330 Environment or \macro : [Value Menu] String: axiom
1331 Type specification : [Value Menu] Char : a
1332 Label prefix string : [Value Menu] String: ax:
1333 Label reference format: [Value Menu] String: ~\ref@{%s@}
1334 Context method : [Value Menu] After label
1335 Magic words:
1336 [INS] [DEL] String: axiom
1337 [INS] [DEL] String: ax.
1338 [INS]
1339 [X] Make TOC entry : [Value Menu] Level: -2
1340[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1341 Environment or \macro : [Value Menu] String: theorem
1342 Type specification : [Value Menu] Char : h
1343 Label prefix string : [Value Menu] String: thr:
1344 Label reference format: [Value Menu] String: ~\ref@{%s@}
1345 Context method : [Value Menu] Default position
1346 Magic words:
1347 [INS] [DEL] String: theorem
1348 [INS] [DEL] String: theor.
1349 [INS] [DEL] String: th.
1350 [INS]
1351 [X] Make TOC entry : [Value Menu] Level: -3
1352@end example
1353
1354@vindex reftex-insert-label-flags
1355@vindex reftex-label-menu-flags
1356Depending on how you would like the label insertion and selection for
1357the new environments to work, you might want to add the letters @samp{a}
1358and @samp{h} to some of the flags in the variables
1359@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
1360and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
1361Labels)}).
1362
1363
6d1962b3 1364@node Quick Equation
4009494e
GM
1365@subsection Quick Equation Macro
1366@cindex Quick equation macro
1367@cindex Macros as environment wrappers
1368
1369Suppose you would like to have a macro for quick equations. It
1370could be defined like this:
1371
1372@example
1373\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
1374@end example
1375
1376@noindent
1377and used like this:
1378
1379@example
1380Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
1381@end example
1382
4f595e15 1383We need to tell @RefTeX{} that any label defined in the argument of the
4009494e
GM
1384@code{\quickeq} is an equation label. Here is how to do this with lisp:
1385
1386@lisp
1387(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
1388@end lisp
1389
1390The first element in this list is now the macro with empty braces as an
1391@emph{image} of the macro arguments. @code{?e} indicates that this is
1392an equation label, the different @code{nil} elements indicate to use the
1393default values for equations. The @samp{1} as the fifth element
4f595e15 1394indicates that the context of the label definition should be the first
4009494e
GM
1395argument of the macro.
1396
1397Here is again how this would look in the customization buffer:
1398
1399@example
1400Reftex Label Alist: [Hide]
1401[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1402 Environment or \macro : [Value Menu] String: \quickeq@{@}
1403 Type specification : [Value Menu] Char : e
1404 Label prefix string : [Value Menu] Default
1405 Label reference format: [Value Menu] Default
1406 Context method : [Value Menu] Macro arg nr: 1
1407 Magic words:
1408 [INS]
1409 [ ] Make TOC entry : [Value Menu] No entry
1410@end example
1411
6d1962b3 1412@node Figure Wrapper
4009494e
GM
1413@subsection Figure Wrapping Macro
1414@cindex Macros as environment wrappers
1415@cindex Figure wrapping macro
1416
1417Suppose you want to make figures not directly with the figure
1418environment, but with a macro like
1419
1420@example
1421\newcommand@{\myfig@}[5][tbp]@{%
1422 \begin@{figure@}[#1]
1423 \epsimp[#5]@{#2@}
1424 \caption@{#3@}
1425 \label@{#4@}
1426 \end@{figure@}@}
1427@end example
1428
1429@noindent
1430which would be called like
1431
1432@example
1433\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
1434@end example
1435
4f595e15 1436Now we need to tell @RefTeX{} that the fourth argument of the
4009494e
GM
1437@code{\myfig} macro @emph{is itself} a figure label, and where to find
1438the context.
1439
1440@lisp
1441(setq reftex-label-alist
1442 '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
1443@end lisp
1444
1445The empty pairs of brackets indicate the different arguments of the
1446@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
1447indicates that this is a figure label which will be listed together with
1448labels from normal figure environments. The @code{nil} entries for
1449prefix and reference format mean to use the defaults for figure labels.
f99f1641
PE
1450The @samp{3} for the context method means to grab the third macro argument:
1451the caption.
4009494e
GM
1452
1453As a side effect of this configuration, @code{reftex-label} will now
1454insert the required naked label (without the @code{\label} macro) when
1455point is directly after the opening parenthesis of a @code{\myfig} macro
1456argument.
1457
1458Again, here the configuration in the customization buffer:
1459
1460@example
1461[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
1462 Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
1463 Type specification : [Value Menu] Char : f
1464 Label prefix string : [Value Menu] Default
1465 Label reference format: [Value Menu] Default
1466 Context method : [Value Menu] Macro arg nr: 3
1467 Magic words:
1468 [INS]
1469 [ ] Make TOC entry : [Value Menu] No entry
1470@end example
1471
6d1962b3 1472@node Adding Magic Words
4009494e
GM
1473@subsection Adding Magic Words
1474@cindex Magic words
1475@cindex German magic words
1476@cindex Label category
1477
1478Sometimes you don't want to define a new label environment or macro, but
1479just change the information associated with a label category. Maybe you
1480want to add some magic words, for another language. Changing only the
1481information associated with a label category is done by giving
1482@code{nil} for the environment name and then specify the items you want
1483to define. Here is an example which adds German magic words to all
1484predefined label categories.
1485
1486@lisp
1487(setq reftex-label-alist
1488 '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
1489 (nil ?e nil nil nil ("Gleichung" "Gl."))
1490 (nil ?t nil nil nil ("Tabelle"))
1491 (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
1492 (nil ?n nil nil nil ("Anmerkung" "Anm."))
1493 (nil ?i nil nil nil ("Punkt"))))
1494@end lisp
1495
6d1962b3 1496@node Using \eqref
4009494e
GM
1497@subsection Using @code{\eqref}
1498@cindex @code{\eqref}, AMS-LaTeX macro
1499@cindex AMS-LaTeX
1500@cindex Label category
1501
1502Another case where one only wants to change the information associated
1503with the label category is to change the macro which is used for
4f595e15 1504referencing the label. When working with the AMS-@LaTeX{}, you might
4009494e
GM
1505prefer @code{\eqref} for doing equation references. Here is how to
1506do this:
1507
1508@lisp
1509(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
1510@end lisp
1511
4f595e15 1512@RefTeX{} has also a predefined symbol for this special purpose. The
4009494e
GM
1513following is equivalent to the line above.
1514
1515@lisp
1516(setq reftex-label-alist '(AMSTeX))
1517@end lisp
1518
1519Note that this is automatically done by the @file{amsmath.el} style file
f99f1641 1520of @AUCTeX{} (@pxref{Style Files}); so if you use @AUCTeX{},
4009494e
GM
1521this configuration will not be necessary.
1522
6d1962b3 1523@node Non-Standard Environments
4009494e
GM
1524@subsection Non-standard Environments
1525@cindex Non-standard environments
1526@cindex Environments without @code{\begin}
1527@cindex Special parser functions
1528@cindex Parser functions, for special environments
1529
4f595e15
RA
1530Some @LaTeX{} packages define environment-like structures without using the
1531standard @samp{\begin..\end} structure. @RefTeX{} cannot parse
4009494e
GM
1532these directly, but you can write your own special-purpose parser and
1533use it instead of the name of an environment in an entry for
1534@code{reftex-label-alist}. The function should check if point is
1535currently in the special environment it was written to detect. If so,
1536it must return a buffer position indicating the start of this
1537environment. The return value must be @code{nil} on failure to detect
1538the environment. The function is called with one argument @var{bound}.
1539If non-@code{nil}, @var{bound} is a boundary for backwards searches
1540which should be observed. We will discuss two examples.
1541
1542@cindex LaTeX commands, abbreviated
1543
1544Some people define abbreviations for
1545environments, like @code{\be} for @code{\begin@{equation@}}, and
1546@code{\ee} for @code{\end@{equation@}}. The parser function would have
1547to search backward for these macros. When the first match is
1548@code{\ee}, point is not in this environment. When the first match is
1549@code{\be}, point is in this environment and the function must return
1550the beginning of the match. To avoid scanning too far, we can also look
1551for empty lines which cannot occur inside an equation environment.
1552Here is the setup:
1553
1554@lisp
1555;; Setup entry in reftex-label-alist, using all defaults for equations
1556(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
1557
1558(defun detect-be-ee (bound)
1559 ;; Search backward for the macros or an empty line
1560 (if (re-search-backward
1561 "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
1562 (if (match-beginning 2)
1563 (match-beginning 2) ; Return start of environment
1564 nil) ; Return nil because env is closed
1565 nil)) ; Return nil for not found
1566@end lisp
1567
1568@cindex @code{linguex}, LaTeX package
1569@cindex LaTeX packages, @code{linguex}
1570A more complex example is the @file{linguex.sty} package which defines
1571list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
1572terminated by @samp{\z.} or by an empty line.
1573
1574@example
1575\ex. \label@{ex:12@} Some text in an exotic language ...
1576 \a. \label@{ex:13@} more stuff
1577 \b. \label@{ex:14@} still more stuff
1578 \a. List on a deeper level
1579 \b. Another item
1580 \b. and the third one
1581 \z.
1582 \b. Third item on this level.
1583
1584... text after the empty line terminating all lists
1585@end example
1586
1587The difficulty is that the @samp{\a.} lists can nest and that an empty
1588line terminates all list levels in one go. So we have to count nesting
1589levels between @samp{\a.} and @samp{\z.}. Here is the implementation
4f595e15 1590for @RefTeX{}.
4009494e
GM
1591
1592@lisp
1593(setq reftex-label-alist
1594 '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1595
1596(defun detect-linguex (bound)
1597 (let ((cnt 0))
1598 (catch 'exit
1599 (while
1600 ;; Search backward for all possible delimiters
1601 (re-search-backward
1602 (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
1603 "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
1604 nil t)
1605 ;; Check which delimiter was matched.
1606 (cond
1607 ((match-beginning 1)
1608 ;; empty line terminates all - return nil
1609 (throw 'exit nil))
1610 ((match-beginning 2)
1611 ;; \z. terminates one list level - decrease nesting count
1612 (decf cnt))
1613 ((match-beginning 3)
1614 ;; \ex. : return match unless there was a \z. on this level
1615 (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
1616 ((match-beginning 4)
1617 ;; \a. : return match when on level 0, otherwise
1618 ;; increment nesting count
1619 (if (>= cnt 0)
1620 (throw 'exit (match-beginning 4))
1621 (incf cnt))))))))
1622@end lisp
1623
6d1962b3 1624@node Putting it Together
4009494e
GM
1625@subsection Putting it all together
1626
1627When you have to put several entries into @code{reftex-label-alist}, just
1628put them after each other in a list, or create that many templates in
1629the customization buffer. Here is a lisp example which uses several of
1630the entries described above:
1631
1632@lisp
1633(setq reftex-label-alist
1634 '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2)
1635 ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3)
1636 ("\\quickeq@{@}" ?e nil nil 1 nil)
1637 AMSTeX
1638 ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
1639 (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
1640@end lisp
1641
6d1962b3 1642@node Reference Info
4009494e
GM
1643@section Reference Info
1644@findex reftex-view-crossref
1645@findex reftex-mouse-view-crossref
1646@cindex Cross-references, displaying
1647@cindex Reference info
1648@cindex Displaying cross-references
1649@cindex Viewing cross-references
1650@kindex C-c &
1651@kindex S-mouse-2
1652
1653When point is idle for more than @code{reftex-idle-time} seconds on the
1654argument of a @code{\ref} macro, the echo area will display some
1655information about the label referenced there. Note that the information
1656is only displayed if the echo area is not occupied by a different
1657message.
1658
4f595e15 1659@RefTeX{} can also display the label definition corresponding to a
4009494e
GM
1660@code{\ref} macro, or all reference locations corresponding to a
1661@code{\label} macro. @xref{Viewing Cross-References}, for more
1662information.
1663
6d1962b3 1664@node Reference Styles
4f595e15
RA
1665@section Reference Styles
1666
1667In case you defined your own macros for referencing or you are using
1668@LaTeX{} packages providing specialized macros to be used instead of
1669@code{\ref}, @RefTeX{} provides ways to select and insert them in a
1670convenient way.
1671
1672@RefTeX{} comes equipped with a set of so-called reference styles where
1673each relates to one or more reference macros. The standard macros
1674@samp{\ref} and @samp{\pageref} or provided by the ``Default'' style.
1675The ``Varioref'' style offers macros for the @samp{varioref} @LaTeX{}
1676package (@samp{\vref}, @samp{\Vref}, @samp{\Ref}, @samp{\vpageref}),
1677``Fancyref'' for the @samp{fancyref} package (@samp{\fref},
1678@samp{\Fref}) and ``Hyperref'' for the @samp{hyperref} package
1679(@samp{\autoref}, @samp{\autopageref}).
1680
1681@vindex reftex-ref-style-default-list
1682A style can be toggled by selecting the respective entry in the
1683@samp{Reference Style} menu. Changes made through the menu will only
1684last for the Emacs session. In order to configure a preference
1685permanently, the variable @code{reftex-ref-style-default-list} should be
1686customized. This variable specifies the list of styles to be activated.
1687It can also be set as a file variable if the preference should be set
1688for a specific file.
1689
1690@vindex reftex-ref-style-alist
1691In case the built-in styles do not suffice, you can add additional
1692macros and styles to the variable @code{reftex-ref-style-alist}. Those
1693do not necessarily have to be related to a certain @LaTeX{} package but
1694can follow an arbitrary grouping rule. For example you could define a
1695style called ``Personal'' for your personal referencing macros. (When
1696changing the variable you should be aware that other Emacs packages,
1697like @AUCTeX{}, might rely on the entries from the default value to be
1698present.)
1699
1700Once a style is active the macros it relates to are available for
1701selection when you are about to insert a reference. In general this
1702process involves three steps: the selection of a reference macro, a
1703label type and a label. Reference macros can be chosen in the first and
1704last step.
1705
1706@vindex reftex-ref-macro-prompt
1707In the first step you will be presented with a list of macros from which
1708you can select one by typing a single key. If you dislike having an
1709extra step for reference macro selection, you can disable it by
1710customizing @code{reftex-ref-macro-prompt} and relying only on the
1711selection facilities provided in the last step.
1712
1df7defd 1713In the last step, i.e., the label selection, two key bindings are
4f595e15
RA
1714provided to set the reference macro. Type @key{v} in order to cycle
1715forward through the list of available macros or @key{V} to cycle
1716backward. The mode line of the selection buffer shows the macro
1717currently selected.
1718
1719In case you are not satisfied with the order of macros when cycling
1720through them you should adapt the order of entries in the variable
1721@code{reftex-ref-style-alist} to fit your liking.
1722
1723For each entry in @code{reftex-ref-style-alist} a function with the name
1df7defd 1724@code{reftex-<package>-<macro>} (e.g., @code{reftex-varioref-vref}) will
4f595e15
RA
1725be created automatically by @RefTeX{}. These functions can be used
1726instead of @kbd{C-c )} and provide an alternative way of having your
1727favorite referencing macro preselected and if cycling through the macros
1df7defd 1728seems inconvenient to you.@footnote{You could, e.g., bind
4f595e15
RA
1729@code{reftex-varioref-vref} to @kbd{C-c v} and
1730@code{reftex-fancyref-fref} to @kbd{C-c f}.}
1731
1732@cindex @code{varioref}, LaTeX package
1733@cindex LaTeX packages, @code{varioref}
1734@cindex @code{fancyref}, LaTeX package
1735@cindex LaTeX packages, @code{fancyref}
1736@vindex reftex-vref-is-default (deprecated)
1737@vindex reftex-fref-is-default (deprecated)
1738In former versions of @RefTeX{} only support for @code{varioref} and
1739@code{fancyref} was included. @code{varioref} is a @LaTeX{} package to
1740create cross-references with page information. @code{fancyref} is a
1741package where a macro call like @code{\fref@{@var{fig:map-of-germany}@}}
1742creates not only the number of the referenced counter but also the
1743complete text around it, like @samp{Figure 3 on the preceding page}. In
1744order to make it work you need to use label prefixes like @samp{fig:}
f99f1641 1745consistently---something @RefTeX{} does automatically. For each of
4f595e15
RA
1746these packages a variable could be configured to make its macros to take
1747precedence over @code{\ref}. Those were @code{reftex-vref-is-default}
1748and @code{reftex-fref-is-default} respectively. While still working,
1749these variables are deprecated now. Instead of setting them, the
1750variable @code{reftex-ref-style-default-list} should be adapted now.
1751
6d1962b3 1752@node xr (LaTeX package)
4009494e
GM
1753@section @code{xr}: Cross-Document References
1754@cindex @code{xr}, LaTeX package
1755@cindex LaTeX packages, @code{xr}
1756@cindex @code{\externaldocument}
1757@cindex External documents
1758@cindex References to external documents
1759@cindex Cross-document references
1760
4f595e15 1761The @LaTeX{} package @code{xr} makes it possible to create references to
4009494e
GM
1762labels defined in external documents. The preamble of a document using
1763@code{xr} will contain something like this:
1764
1765@example
1766\usepackage@{xr@}
1767\externaldocument[V1-]@{volume1@}
1768\externaldocument[V3-]@{volume3@}
1769@end example
1770
1771@noindent
1772and we can make references to any labels defined in these
1773external documents by using the prefixes @samp{V1-} and @samp{V3-},
1774respectively.
1775
4f595e15 1776@RefTeX{} can be used to create such references as well. Start the
4009494e
GM
1777referencing process normally, by pressing @kbd{C-c )}. Select a label
1778type if necessary. When you see the label selection buffer, pressing
1779@kbd{x} will switch to the label selection buffer of one of the external
4f595e15 1780documents. You may then select a label as before and @RefTeX{} will
4009494e
GM
1781insert it along with the required prefix.
1782
1783For this kind of inter-document cross-references, saving of parsing
1784information and the use of multiple selection buffers can mean a large
1785speed-up (@pxref{Optimizations}).
1786
6d1962b3 1787@node Citations
4009494e
GM
1788@chapter Citations
1789@cindex Citations
1790@cindex @code{\cite}
1791
4f595e15 1792Citations in @LaTeX{} are done with the @code{\cite} macro or variations of
4009494e 1793it. The argument of the macro is a citation key which identifies an
4f595e15
RA
1794article or book in either a @BibTeX{} database file or in an explicit
1795@code{thebibliography} environment in the document. @RefTeX{}'s
4009494e
GM
1796support for citations helps to select the correct key quickly.
1797
1798@menu
1799* Creating Citations:: How to create them.
1800* Citation Styles:: Natbib, Harvard, Chicago and Co.
1801* Citation Info:: View the corresponding database entry.
1802* Chapterbib and Bibunits:: Multiple bibliographies in a Document.
1803* Citations Outside LaTeX:: How to make citations in Emails etc.
9858f6c3 1804* BibTeX Database Subsets:: Extract parts of a big database.
4009494e
GM
1805@end menu
1806
6d1962b3 1807@node Creating Citations
4009494e
GM
1808@section Creating Citations
1809@cindex Creating citations
1810@cindex Citations, creating
1811@findex reftex-citation
1812@kindex C-c [
1813@cindex Selection buffer, citations
1814@cindex Selection process
1815
4f595e15 1816In order to create a citation, press @kbd{C-c [}. @RefTeX{} then
4009494e
GM
1817prompts for a regular expression which will be used to search through
1818the database and present the list of matches to choose from in a
1819selection process similar to that for selecting labels
1820(@pxref{Referencing Labels}).
1821
1822The regular expression uses an extended syntax: @samp{&&} defines a
1823logic @code{and} for regular expressions. For example
1824@samp{Einstein&&Bose} will match all articles which mention
1825Bose-Einstein condensation, or which are co-authored by Bose and
1826Einstein. When entering the regular expression, you can complete on
4f595e15
RA
1827known citation keys. @RefTeX{} also offers a default when prompting for
1828a regular expression. This default is the word before the cursor or the
4009494e
GM
1829word before the current @samp{\cite} command. Sometimes this may be a
1830good search key.
1831
1832@cindex @code{\bibliography}
1833@cindex @code{thebibliography}, LaTeX environment
1834@cindex @code{BIBINPUTS}, environment variable
1835@cindex @code{TEXBIB}, environment variable
4f595e15 1836@RefTeX{} prefers to use @BibTeX{} database files specified with a
4009494e 1837@code{\bibliography} macro to collect its information. Just like
4f595e15 1838@BibTeX{}, it will search for the specified files in the current directory
4009494e 1839and along the path given in the environment variable @code{BIBINPUTS}.
4f595e15
RA
1840If you do not use @BibTeX{}, but the document contains an explicit
1841@code{thebibliography} environment, @RefTeX{} will collect its
4009494e
GM
1842information from there. Note that in this case the information
1843presented in the selection buffer will just be a copy of relevant
1844@code{\bibitem} entries, not the structured listing available with
4f595e15 1845@BibTeX{} database files.
4009494e
GM
1846
1847@kindex ?
1848In the selection buffer, the following keys provide special commands. A
1849summary of this information is always available from the selection
1850process by pressing @kbd{?}.
1851
1852@table @kbd
1853@tablesubheading{General}
1854@item ?
1855Show a summary of available commands.
1856
1857@item 0-9,-
1858Prefix argument.
1859
1860@tablesubheading{Moving around}
1861@item n
1862Go to next article.
1863
1864@item p
1865Go to previous article.
1866
1867@tablesubheading{Access to full database entries}
1868@item @key{SPC}
1869Show the database entry corresponding to the article at point, in
1870another window. See also the @kbd{f} key.
1871
1872@item f
1873Toggle follow mode. When follow mode is active, the other window will
1874always display the full database entry of the current article. This is
4f595e15 1875equivalent to pressing @key{SPC} after each cursor motion. With @BibTeX{}
4009494e
GM
1876entries, follow mode can be rather slow.
1877
1878@tablesubheading{Selecting entries and creating the citation}
1879@item @key{RET}
1880Insert a citation referencing the article at point into the buffer from
1881which the selection process was started.
1882
1883@item mouse-2
1884@vindex reftex-highlight-selection
1885Clicking with mouse button 2 on a citation will accept it like @key{RET}
1886would. See also variable @code{reftex-highlight-selection}, @ref{Options
1887(Misc)}.
1888
1889@item m
1890Mark the current entry. When one or several entries are marked,
1891pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
1892@key{RET} behaves like the @kbd{a} key.
1893
1894@item u
1895Unmark a marked entry.
1896
1897@item a
1898Accept all (marked) entries in the selection buffer and create a single
1899@code{\cite} macro referring to them.
1900
1901@item A
1902Accept all (marked) entries in the selection buffer and create a
1903separate @code{\cite} macro for each of it.
1904
1905@item e
4f595e15 1906Create a new @BibTeX{} database file which contains all @i{marked} entries
4009494e 1907in the selection buffer. If no entries are marked, all entries are
9858f6c3 1908selected.
4009494e
GM
1909
1910@item E
4f595e15 1911Create a new @BibTeX{} database file which contains all @i{unmarked}
4009494e 1912entries in the selection buffer. If no entries are marked, all entries
9858f6c3 1913are selected.
4009494e
GM
1914
1915@item @key{TAB}
1916Enter a citation key with completion. This may also be a key which does
1917not yet exist.
1918
1919@item .
1920Show insertion point in another window. This is the point from where you
1921called @code{reftex-citation}.
1922
1923@tablesubheading{Exiting}
1924@item q
1925Exit the selection process without inserting a citation into the
1926buffer.
1927
1928@tablesubheading{Updating the buffer}
1929
1930@item g
1931Start over with a new regular expression. The full database will be
1932rescanned with the new expression (see also @kbd{r}).
1933
1934@c FIXME: Should we use something else here? r is usually rescan!
1935@item r
1936Refine the current selection with another regular expression. This will
1937@emph{not} rescan the entire database, but just the already selected
1938entries.
1939
1940@end table
1941
1942@vindex reftex-select-bib-map
1943In order to define additional commands for this selection process, the
1944keymap @code{reftex-select-bib-map} may be used.
1945
4f595e15
RA
1946Note that if you do not use Emacs to edit the @BibTeX{} database files,
1947@RefTeX{} will ask if the related buffers should be updated once it
1948detects that the files were changed externally. If you do not want to
1949be bothered by such queries, you can activate Auto Revert mode for these
1950buffers by adding the following expression to your init file:
1951
1952@lisp
1953(add-hook 'bibtex-mode-hook 'turn-on-auto-revert-mode)
1954@end lisp
1955
1956
6d1962b3 1957@node Citation Styles
4009494e
GM
1958@section Citation Styles
1959@cindex Citation styles
1960@cindex Citation styles, @code{natbib}
1961@cindex Citation styles, @code{harvard}
1962@cindex Citation styles, @code{chicago}
1963@cindex Citation styles, @code{jurabib}
4f595e15 1964@cindex Citation styles, @ConTeXt{}
4009494e
GM
1965@cindex @code{natbib}, citation style
1966@cindex @code{harvard}, citation style
1967@cindex @code{chicago}, citation style
1968@cindex @code{jurabib}, citation style
4f595e15 1969@cindex @ConTeXt{}, citation style
4009494e
GM
1970
1971@vindex reftex-cite-format
4f595e15
RA
1972The standard @LaTeX{} macro @code{\cite} works well with numeric or
1973simple key citations. To deal with the more complex task of author-year
4009494e
GM
1974citations as used in many natural sciences, a variety of packages has
1975been developed which define derived forms of the @code{\cite} macro.
4f595e15
RA
1976@RefTeX{} can be configured to produce these citation macros as well by
1977setting the variable @code{reftex-cite-format}. For the most commonly
1978used @LaTeX{} packages (@code{natbib}, @code{harvard}, @code{chicago},
1979@code{jurabib}) and for @ConTeXt{} this may be done from the menu, under
4009494e
GM
1980@code{Ref->Citation Styles}. Since there are usually several macros to
1981create the citations, executing @code{reftex-citation} (@kbd{C-c [})
1982starts by prompting for the correct macro. For the Natbib style, this
1983looks like this:
1984
1985@example
1986SELECT A CITATION FORMAT
1987
1988[^M] \cite@{%l@}
1989[t] \citet@{%l@}
1990[T] \citet*@{%l@}
1991[p] \citep@{%l@}
1992[P] \citep*@{%l@}
1993[e] \citep[e.g.][]@{%l@}
1994[s] \citep[see][]@{%l@}
1995[a] \citeauthor@{%l@}
1996[A] \citeauthor*@{%l@}
1997[y] \citeyear@{%l@}
1998@end example
1999
2000@vindex reftex-cite-prompt-optional-args
4f595e15 2001If citation formats contain empty pairs of square brackets, @RefTeX{}
4009494e
GM
2002will prompt for values of these optional arguments if you call the
2003@code{reftex-citation} command with a @kbd{C-u} prefix.
2004Following the most generic of these packages, @code{natbib}, the builtin
2005citation packages always accept the @kbd{t} key for a @emph{textual}
2006citation (like: @code{Jones et al. (1997) have shown...}) as well as
2007the @kbd{p} key for a parenthetical citation (like: @code{As shown
2008earlier (Jones et al, 1997)}).
2009
2010To make one of these styles the default, customize the variable
2011@code{reftex-cite-format} or put into @file{.emacs}:
2012
2013@lisp
2014(setq reftex-cite-format 'natbib)
2015@end lisp
2016
4f595e15 2017You can also use @AUCTeX{} style files to automatically set the
4009494e
GM
2018citation style based on the @code{usepackage} commands in a given
2019document. @xref{Style Files}, for information on how to set up the style
2020files correctly.
2021
6d1962b3 2022@node Citation Info
4009494e
GM
2023@section Citation Info
2024@cindex Displaying citations
2025@cindex Citations, displaying
2026@cindex Citation info
2027@cindex Viewing citations
2028@kindex C-c &
2029@kindex S-mouse-2
2030@findex reftex-view-crossref
2031@findex reftex-mouse-view-crossref
2032
2033When point is idle for more than @code{reftex-idle-time} seconds on the
2034argument of a @code{\cite} macro, the echo area will display some
2035information about the article cited there. Note that the information is
2036only displayed if the echo area is not occupied by a different message.
2037
4f595e15 2038@RefTeX{} can also display the @code{\bibitem} or @BibTeX{} database
4009494e 2039entry corresponding to a @code{\cite} macro, or all citation locations
4f595e15 2040corresponding to a @code{\bibitem} or @BibTeX{} database entry.
4009494e
GM
2041@xref{Viewing Cross-References}.
2042
6d1962b3 2043@node Chapterbib and Bibunits
4009494e
GM
2044@section Chapterbib and Bibunits
2045@cindex @code{chapterbib}, LaTeX package
2046@cindex @code{bibunits}, LaTeX package
2047@cindex Bibliographies, multiple
2048
4f595e15 2049@code{chapterbib} and @code{bibunits} are two @LaTeX{} packages which
4009494e 2050produce multiple bibliographies in a document. This is no problem for
4f595e15 2051@RefTeX{} as long as all bibliographies use the same @BibTeX{} database
4009494e
GM
2052files. If they do not, it is best to have each document part in a
2053separate file (as it is required for @code{chapterbib} anyway). Then
4f595e15 2054@RefTeX{} will still scan the locally relevant databases correctly. If
4009494e
GM
2055you have multiple bibliographies within a @emph{single file}, this may
2056or may not be the case.
2057
6d1962b3 2058@node Citations Outside LaTeX
4f595e15 2059@section Citations outside @LaTeX{}
4009494e
GM
2060@cindex Citations outside LaTeX
2061@vindex reftex-default-bibliography
2062
4f595e15 2063The command @code{reftex-citation} can also be executed outside a @LaTeX{}
4009494e
GM
2064buffer. This can be useful to reference articles in the mail buffer and
2065other documents. You should @emph{not} enter @code{reftex-mode} for
4f595e15 2066this, just execute the command. The list of @BibTeX{} files will in this
4009494e
GM
2067case be taken from the variable @code{reftex-default-bibliography}.
2068Setting the variable @code{reftex-cite-format} to the symbol
2069@code{locally} does a decent job of putting all relevant information
2070about a citation directly into the buffer. Here is the lisp code to add
2071the @kbd{C-c [} binding to the mail buffer. It also provides a local
2072binding for @code{reftex-cite-format}.
2073
2074@lisp
2075(add-hook 'mail-setup-hook
2076 (lambda () (define-key mail-mode-map "\C-c["
2077 (lambda ()
2078 (interactive)
2079 (let ((reftex-cite-format 'locally))
2080 (reftex-citation))))))
2081@end lisp
2082
6d1962b3 2083@node BibTeX Database Subsets
4009494e
GM
2084@section Database Subsets
2085@cindex BibTeX database subsets
2086@findex reftex-create-bibtex-file
2087
4f595e15 2088@RefTeX{} offers two ways to create a new @BibTeX{} database file.
4009494e
GM
2089
2090The first option produces a file which contains only the entries
2091actually referenced in the current document. This can be useful if
4f595e15 2092the database is only meant for a single document and you want to clean
4009494e
GM
2093it of old and unused ballast. It can also be useful while writing a
2094document together with collaborators, in order to avoid sending around
2095the entire (possibly very large) database. To create the file, use
2096@kbd{M-x reftex-create-bibtex-file}, also available from the menu
2097under @code{Ref->Global Actions->Create Bibtex File}. The command will
4f595e15 2098prompt for a @BibTeX{} file name and write the extracted entries to that
4009494e
GM
2099file.
2100
2101The second option makes use of the selection process started by the
2102command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a
2103regular expression to select entries, and lists them in a formatted
2104selection buffer. After pressing the @kbd{e} key (mnemonics: Export),
4f595e15 2105the command will prompt for the name of a new @BibTeX{} file and write
4009494e
GM
2106the selected entries to that file. You can also first mark some
2107entries in the selection buffer with the @kbd{m} key and then export
2108either the @i{marked} entries (with the @kbd{e} key) or the
2109@i{unmarked} entries (with the @kbd{E} key).
2110
6d1962b3 2111@node Index Support
4009494e
GM
2112@chapter Index Support
2113@cindex Index Support
2114@cindex @code{\index}
2115
4f595e15 2116@LaTeX{} has builtin support for creating an Index. The @LaTeX{} core
4009494e 2117supports two different indices, the standard index and a glossary. With
4f595e15 2118the help of special @LaTeX{} packages (@file{multind.sty} or
4009494e
GM
2119@file{index.sty}), any number of indices can be supported.
2120
2121Index entries are created with the @code{\index@{@var{entry}@}} macro.
2122All entries defined in a document are written out to the @file{.aux}
2123file. A separate tool must be used to convert this information into a
4f595e15 2124nicely formatted index. Tools used with @LaTeX{} include @code{MakeIndex}
4009494e
GM
2125and @code{xindy}.
2126
2127Indexing is a very difficult task. It must follow strict conventions to
2128make the index consistent and complete. There are basically two
2129approaches one can follow, and both have their merits.
2130
2131@enumerate
2132@item
2133Part of the indexing should already be done with the markup. The
2134document structure should be reflected in the index, so when starting
2135new sections, the basic topics of the section should be indexed. If the
2136document contains definitions, theorems or the like, these should all
2137correspond to appropriate index entries. This part of the index can
2138very well be developed along with the document. Often it is worthwhile
2139to define special purpose macros which define an item and at the same
2140time make an index entry, possibly with special formatting to make the
4f595e15 2141reference page in the index bold or underlined. To make @RefTeX{}
4009494e 2142support for indexing possible, these special macros must be added to
4f595e15 2143@RefTeX{}'s configuration (@pxref{Defining Index Macros}).
4009494e
GM
2144
2145@item
2146The rest of the index is often just a collection of where in the
2147document certain words or phrases are being used. This part is
2148difficult to develop along with the document, because consistent entries
2149for each occurrence are needed and are best selected when the document
4f595e15 2150is ready. @RefTeX{} supports this with an @emph{index phrases file}
4009494e
GM
2151which collects phrases and helps indexing the phrases globally.
2152@end enumerate
2153
4f595e15
RA
2154Before you start, you need to make sure that @RefTeX{} knows about
2155the index style being used in the current document. @RefTeX{} has
4009494e 2156builtin support for the default @code{\index} and @code{\glossary}
4f595e15 2157macros. Other @LaTeX{} packages, like the @file{multind} or @file{index}
4009494e 2158package, redefine the @code{\index} macro to have an additional
4f595e15
RA
2159argument, and @RefTeX{} needs to be configured for those. A
2160sufficiently new version of @AUCTeX{} (9.10c or later) will do this
2161automatically. If you really don't use @AUCTeX{} (you should!), this
4009494e
GM
2162configuration needs to be done by hand with the menu (@code{Ref->Index
2163Style}), or globally for all your documents with
2164
2165@lisp
2166(setq reftex-index-macros '(multind)) @r{or}
2167(setq reftex-index-macros '(index))
2168@end lisp
2169
2170@menu
2171* Creating Index Entries:: Macros and completion of entries.
2172* The Index Phrases File:: A special file for global indexing.
2173* Displaying and Editing the Index:: The index editor.
2174* Builtin Index Macros:: The index macros RefTeX knows about.
2175* Defining Index Macros:: ... and macros it doesn't.
2176@end menu
2177
6d1962b3 2178@node Creating Index Entries
4009494e
GM
2179@section Creating Index Entries
2180@cindex Creating index entries
2181@cindex Index entries, creating
2182@kindex C-c <
2183@findex reftex-index
2184@kindex C-c /
2185@findex reftex-index-selection-or-word
2186
2187In order to index the current selection or the word at the cursor press
2188@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
2189selection or word @samp{@var{word}} to be replaced with
2190@samp{\index@{@var{word}@}@var{word}}. The macro which is used
2191(@code{\index} by default) can be configured with the variable
2192@code{reftex-index-default-macro}. When the command is called with a
2193prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
2194generated index entry. Use this to change the case of the word or to
2195make the entry a subentry, for example by entering
2196@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
2197(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
2198When there is nothing selected and no word at point, this command will
2199just call @code{reftex-index}, described below.
2200
2201In order to create a general index entry, press @kbd{C-c <}
4f595e15 2202(@code{reftex-index}). @RefTeX{} will prompt for one of the
4009494e
GM
2203available index macros and for its arguments. Completion will be
2204available for the index entry and, if applicable, the index tag. The
2205index tag is a string identifying one of multiple indices. With the
2206@file{multind} and @file{index} packages, this tag is the first argument
2207to the redefined @code{\index} macro.
2208
6d1962b3 2209@node The Index Phrases File
4009494e
GM
2210@section The Index Phrases File
2211@cindex Index phrase file
2212@cindex Phrase file
2213@kindex C-c |
2214@findex reftex-index-visit-phrases-buffer
2215@cindex Macro definition lines, in phrase buffer
2216
4f595e15 2217@RefTeX{} maintains a file in which phrases can be collected for
4009494e
GM
2218later indexing. The file is located in the same directory as the master
2219file of the document and has the extension @file{.rip} (@b{R}eftex
2220@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c
2221|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it
2222is initialized by inserting a file header which contains the definition
2223of the available index macros. This list is initialized from
2224@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can
4f595e15 2225edit the header as needed, but if you define new @LaTeX{} indexing macros,
4009494e
GM
2226don't forget to add them to @code{reftex-index-macros} as well. Here is
2227a phrase file header example:
2228
2229@example
2230% -*- mode: reftex-index-phrases -*-
2231% Key Macro Format Repeat
2232%----------------------------------------------------------
2233>>>INDEX_MACRO_DEFINITION: i \index@{%s@} t
2234>>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil
2235>>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t
2236>>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil
2237%----------------------------------------------------------
2238@end example
2239
2240The macro definition lines consist of a unique letter identifying a
2241macro, a format string and the @var{repeat} flag, all separated by
2242@key{TAB}. The format string shows how the macro is to be applied, the
2243@samp{%s} will be replaced with the index entry. The repeat flag
2244indicates if @var{word} is indexed by the macro as
2245@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
2246@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the
2247above example it is assumed that the macro @code{\index*@{@var{word}@}}
2248already typesets its argument in the text, so that it is unnecessary to
2249repeat @var{word} outside the macro.
2250
2251@menu
2252* Collecting Phrases:: Collecting from document or external.
2253* Consistency Checks:: Check for duplicates etc.
2254* Global Indexing:: The interactive indexing process.
2255@end menu
2256
6d1962b3 2257@node Collecting Phrases
4009494e
GM
2258@subsection Collecting Phrases
2259@cindex Collecting index phrases
2260@cindex Index phrases, collection
2261@cindex Phrases, collecting
2262
2263Phrases for indexing can be collected while writing the document. The
2264command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
2265copies the current selection (if active) or the word near point into the
2266phrases buffer. It then selects this buffer, so that the phrase line
4f595e15 2267can be edited. To return to the @LaTeX{} document, press @kbd{C-c C-c}
4009494e
GM
2268(@code{reftex-index-phrases-save-and-return}).
2269
2270You can also prepare the list of index phrases in a different way and
2271copy it into the phrases file. For example you might want to start from
2272a word list of the document and remove all words which should not be
2273indexed.
2274
2275The phrase lines in the phrase buffer must have a specific format.
4f595e15 2276@RefTeX{} will use font-lock to indicate if a line has the proper
4009494e
GM
2277format. A phrase line looks like this:
2278
2279@example
2280[@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
2281@end example
2282
2283@code{<TABs>} stands for white space containing at least one @key{TAB}.
2284@var{key} must be at the start of the line and is the character
2285identifying one of the macros defined in the file header. It is
f99f1641 2286optional; when omitted, the first macro definition line in the file
4009494e
GM
2287will be used for this phrase. The @var{phrase} is the phrase to be
2288searched for when indexing. It may contain several words separated by
2289spaces. By default the search phrase is also the text entered as
2290argument of the index macro. If you want the index entry to be
2291different from the search phrase, enter another @key{TAB} and the index
2292argument @var{arg}. If you want to have each match produce several
2293index entries, separate the different index arguments with @samp{ &&
2294}@footnote{@samp{&&} with optional spaces, see
2295@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be
2296able to choose at each match between several different index arguments,
2297separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
2298see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an
2299example:
2300
2301@example
2302%--------------------------------------------------------------------
2303I Sun
2304i Planet Planets
2305i Vega Stars!Vega
2306 Jupiter Planets!Jupiter
2307i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars
2308i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto
2309@end example
2310
2311
2312So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
2313@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
2314@samp{Vega} will be indexed as a subitem of @samp{Stars}. The
2315@samp{Jupiter} line will also use the @samp{i} macro as it was the first
2316macro definition in the file header (see above example). At each
2317occurrence of @samp{Mars} you will be able choose between indexing it as
2318a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
2319Finally, every occurrence of @samp{Pluto} will be indexed as
2320@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
2321and will therefore create two different index entries.
2322
6d1962b3 2323@node Consistency Checks
4009494e
GM
2324@subsection Consistency Checks
2325@cindex Index phrases, consistency checks
2326@cindex Phrases, consistency checks
2327@cindex Consistency check for index phrases
2328
2329@kindex C-c C-s
2330Before indexing the phrases in the phrases buffer, they should be
2331checked carefully for consistency. A first step is to sort the phrases
f99f1641 2332alphabetically; this is done with the command @kbd{C-c C-s}
4009494e
GM
2333(@code{reftex-index-sort-phrases}). It will sort all phrases in the
2334buffer alphabetically by search phrase. If you want to group certain
2335phrases and only sort within the groups, insert empty lines between the
2336groups. Sorting will only change the sequence of phrases within each
2337group (see the variable @code{reftex-index-phrases-sort-in-blocks}).
2338
2339@kindex C-c C-i
2340A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
2341which lists information about the phrase at point, including an example
2342of how the index entry will look like and the number of expected matches
2343in the document.
2344
2345@kindex C-c C-t
2346Another important check is to find out if there are double or
2347overlapping entries in the buffer. For example if you are first
2348searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
2349second phrase will not match because of the index macro inserted before
2350@samp{Mars} earlier. The command @kbd{C-c C-t}
2351(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
2352the buffer which is either duplicate or a subphrase of another phrase.
2353In order to check the whole buffer like this, start at the beginning and
2354execute this command repeatedly.
2355
6d1962b3 2356@node Global Indexing
4009494e
GM
2357@subsection Global Indexing
2358@cindex Global indexing
2359@cindex Indexing, global
2360@cindex Indexing, from @file{phrases} buffer
2361
2362Once the index phrases have been collected and organized, you are set
2363for global indexing. I recommend to do this only on an otherwise
2364finished document. Global indexing starts from the phrases buffer.
2365There are several commands which start indexing: @kbd{C-c C-x} acts on
2366the current phrase line, @kbd{C-c C-r} on all lines in the current
2367region and @kbd{C-c C-a} on all phrase lines in the buffer. It is
2368probably good to do indexing in small chunks since your concentration
2369may not last long enough to do everything in one go.
2370
4f595e15 2371@RefTeX{} will start at the first phrase line and search the phrase
4009494e
GM
2372globally in the whole document. At each match it will stop, compute the
2373replacement string and offer you the following choices@footnote{Windows
2374users: Restrict yourself to the described keys during indexing. Pressing
2375@key{Help} at the indexing prompt can apparently hang Emacs.}:
2376
2377@table @kbd
2378@item y
2379Replace this match with the proposed string.
2380@item n
2381Skip this match.
2382@item !
2383Replace this and all further matches in this file.
2384@item q
2385Skip this match, start with next file.
2386@item Q
2387Skip this match, start with next phrase.
2388@item o
2389Select a different indexing macro for this match.
2390@item 1-9
2391Select one of multiple index keys (those separated with @samp{||}).
2392@item e
2393Edit the replacement text.
2394@item C-r
2395Recursive edit. Use @kbd{C-M-c} to return to the indexing process.
2396@item s
2397Save this buffer and ask again about the current match.
2398@item S
2399Save all document buffers and ask again about the current match.
2400@item C-g
2401Abort the indexing process.
2402@end table
2403
2404The @samp{Find and Index in Document} menu in the phrases buffer also
2405lists a few options for the indexing process. The options have
2406associated customization variables to set the defaults (@pxref{Options
2407(Index Support)}). Here is a short explanation of what the options do:
2408
2409@table @i
2410@item Match Whole Words
2411When searching for index phrases, make sure whole words are matched.
2412This should probably always be on.
2413@item Case Sensitive Search
2414Search case sensitively for phrases. I recommend to have this setting
2415off, in order to match the capitalized words at the beginning of a
2416sentence, and even typos. You can always say @emph{no} at a match you
2417do not like.
2418@item Wrap Long Lines
2419Inserting index macros increases the line length. Turn this option on
4f595e15 2420to allow @RefTeX{} to wrap long lines.
4009494e 2421@item Skip Indexed Matches
4f595e15 2422When this is on, @RefTeX{} will at each match try to figure out if
4009494e
GM
2423this match is already indexed. A match is considered indexed if it is
2424either the argument of an index macro, or if an index macro is directly
2425(without whitespace separation) before or after the match. Index macros
2426are those configured in @code{reftex-index-macros}. Intended for
2427re-indexing a documents after changes have been made.
2428@end table
2429
2430Even though indexing should be the last thing you do to a document, you
2431are bound to make changes afterwards. Indexing then has to be applied
2432to the changed regions. The command
2433@code{reftex-index-phrases-apply-to-region} is designed for this
4f595e15 2434purpose. When called from a @LaTeX{} document with active region, it will
4009494e
GM
2435apply @code{reftex-index-all-phrases} to the current region.
2436
6d1962b3 2437@node Displaying and Editing the Index
4009494e
GM
2438@section Displaying and Editing the Index
2439@cindex Displaying the Index
2440@cindex Editing the Index
2441@cindex Index entries, creating
2442@cindex Index, displaying
2443@cindex Index, editing
2444@kindex C-c >
2445@findex reftex-display-index
2446
2447In order to compile and display the index, press @kbd{C-c >}. If the
4f595e15 2448document uses multiple indices, @RefTeX{} will ask you to select
4009494e
GM
2449one. Then, all index entries will be sorted alphabetically and
2450displayed in a special buffer, the @file{*Index*} buffer. From that
2451buffer you can check and edit each entry.
2452
2453The index can be restricted to the current section or the region. Then
2454only entries in that part of the document will go into the compiled
2455index. To restrict to the current section, use a numeric prefix
2456@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
2457region, make the region active and use a numeric prefix @samp{3} (press
2458@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
2459restriction can be moved from one section to the next by pressing the
2460@kbd{<} and @kbd{>} keys.
2461
4f595e15 2462One caveat: @RefTeX{} finds the definition point of an index entry
4009494e
GM
2463by searching near the buffer position where it had found to macro during
2464scanning. If you have several identical index entries in the same
2465buffer and significant changes have shifted the entries around, you must
2466rescan the buffer to ensure the correspondence between the
2467@file{*Index*} buffer and the definition locations. It is therefore
2468advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
2469frequently while editing the index from the @file{*Index*}
2470buffer.
2471
2472@kindex ?
2473Here is a list of special commands available in the @file{*Index*} buffer. A
2474summary of this information is always available by pressing
2475@kbd{?}.
2476
2477@table @kbd
2478@tablesubheading{General}
2479@item ?
2480Display a summary of commands.
2481
2482@item 0-9, -
2483Prefix argument.
2484
2485@tablesubheading{Moving around}
2486@item ! A..Z
2487Pressing any capital letter will jump to the corresponding section in
2488the @file{*Index*} buffer. The exclamation mark is special and jumps to
2489the first entries alphabetically sorted below @samp{A}. These are
2490usually non-alphanumeric characters.
2491@item n
2492Go to next entry.
2493@item p
2494Go to previous entry.
2495
2496@tablesubheading{Access to document locations}
2497@item @key{SPC}
2498Show the place in the document where this index entry is defined.
2499
2500@item @key{TAB}
2501Go to the definition of the current index entry in another
2502window.
2503
2504@item @key{RET}
2505Go to the definition of the current index entry and hide the
2506@file{*Index*} buffer window.
2507
2508@item f
2509@vindex reftex-index-follow-mode
2510@vindex reftex-revisit-to-follow
2511Toggle follow mode. When follow mode is active, the other window will
2512always show the location corresponding to the line in the @file{*Index*}
2513buffer at point. This is similar to pressing @key{SPC} after each
2514cursor motion. The default for this flag can be set with the variable
2515@code{reftex-index-follow-mode}. Note that only context in files
4f595e15 2516already visited is shown. @RefTeX{} will not visit a file just for
4009494e
GM
2517follow mode. See, however, the variable
2518@code{reftex-revisit-to-follow}.
2519
2520@tablesubheading{Entry editing}
2521@item e
2522Edit the current index entry. In the minibuffer, you can edit the
2523index macro which defines this entry.
2524
2525@item C-k
2526Kill the index entry. Currently not implemented because I don't know
2527how to implement an @code{undo} function for this.
2528
2529@item *
2530Edit the @var{key} part of the entry. This is the initial part of the
2531entry which determines the location of the entry in the index.
2532
2533@item |
2534Edit the @var{attribute} part of the entry. This is the part after the
2535vertical bar. With @code{MakeIndex}, this part is an encapsulating
2536macro. With @code{xindy}, it is called @emph{attribute} and is a
2537property of the index entry that can lead to special formatting. When
2538called with @kbd{C-u} prefix, kill the entire @var{attribute}
2539part.
2540
2541@item @@
2542Edit the @var{visual} part of the entry. This is the part after the
2543@samp{@@} which is used by @code{MakeIndex} to change the visual
2544appearance of the entry in the index. When called with @kbd{C-u}
2545prefix, kill the entire @var{visual} part.
2546
2547@item (
2548Toggle the beginning of page range property @samp{|(} of the
2549entry.
2550
2551@item )
2552Toggle the end of page range property @samp{|)} of the entry.
2553
2554@item _
2555Make the current entry a subentry. This command will prompt for the
2556superordinate entry and insert it.
2557
2558@item ^
2559Remove the highest superordinate entry. If the current entry is a
2560subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
2561(@samp{bbb!ccc}).
2562
2563@tablesubheading{Exiting}
2564@item q
2565Hide the @file{*Index*} buffer.
2566
2567@item k
2568Kill the @file{*Index*} buffer.
2569
2570@item C-c =
2571Switch to the Table of Contents buffer of this document.
2572
2573@tablesubheading{Controlling what gets displayed}
2574@item c
2575@vindex reftex-index-include-context
2576Toggle the display of short context in the @file{*Index*} buffer. The
2577default for this flag can be set with the variable
2578@code{reftex-index-include-context}.
2579
2580@item @}
2581Restrict the index to a single document section. The corresponding
2582section number will be displayed in the @code{R<>} indicator in the
2583mode line and in the header of the @file{*Index*} buffer.
2584
2585@item @{
2586Widen the index to contain all entries of the document.
2587
2588@item <
2589When the index is currently restricted, move the restriction to the
2590previous section.
2591
2592@item >
2593When the index is currently restricted, move the restriction to the
2594next section.
2595
2596@tablesubheading{Updating the buffer}
2597@item g
2598Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
2599document. However, it sorts the entries again, so that edited entries
2600will move to the correct position.
2601
2602@item r
2603@vindex reftex-enable-partial-scans
4f595e15 2604Reparse the @LaTeX{} document and rebuild the @file{*Index*} buffer. When
4009494e
GM
2605@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this
2606location is defined in, not the entire document.
2607
2608@item C-u r
4f595e15 2609Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*Index*}
4009494e
GM
2610buffer.
2611
2612@item s
2613Switch to a different index (for documents with multiple
2614indices).
2615@end table
2616
2617
6d1962b3 2618@node Builtin Index Macros
4009494e
GM
2619@section Builtin Index Macros
2620@cindex Builtin index macros
2621@cindex Index macros, builtin
2622@vindex reftex-index-macros
2623@cindex @code{multind}, LaTeX package
2624@cindex @code{index}, LaTeX package
2625@cindex LaTeX packages, @code{multind}
2626@cindex LaTeX packages, @code{index}
2627
4f595e15
RA
2628@RefTeX{} by default recognizes the @code{\index} and
2629@code{\glossary} macros which are defined in the @LaTeX{} core. It has
4009494e
GM
2630also builtin support for the re-implementations of @code{\index}
2631in the @file{multind} and @file{index} packages. However, since
2632the different definitions of the @code{\index} macro are incompatible,
2633you will have to explicitly specify the index style used.
2634@xref{Creating Index Entries}, for information on how to do that.
2635
6d1962b3 2636@node Defining Index Macros
4009494e
GM
2637@section Defining Index Macros
2638@cindex Defining Index Macros
2639@cindex Index macros, defining
2640@vindex reftex-index-macros
2641
2642When writing a document with an index you will probably define
2643additional macros which make entries into the index.
2644Let's look at an example.
2645
2646@example
2647\newcommand@{\ix@}[1]@{#1\index@{#1@}@}
2648\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
2649\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
2650@end example
2651
2652The first macro @code{\ix} typesets its argument in the text and places
2653it into the index. The second macro @code{\nindex} typesets its
2654argument in the text and places it into a separate index with the tag
2655@samp{name}@footnote{We are using the syntax of the @file{index} package
2656here.}. The last macro also places its argument into the index, but as
2657subitems under the main index entry @samp{Astronomical Objects}. Here
4f595e15 2658is how to make @RefTeX{} recognize and correctly interpret these
4009494e
GM
2659macros, first with Emacs Lisp.
2660
2661@lisp
2662(setq reftex-index-macros
2663 '(("\\ix@{*@}" "idx" ?x "" nil nil)
2664 ("\\nindex@{*@}" "name" ?n "" nil nil)
2665 ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
2666@end lisp
2667
2668Note that the index tag is @samp{idx} for the main index, and
2669@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
2670for the default index and for the glossary.
2671
2672The character arguments @code{?x}, @code{?n}, and @code{?o} are for
4f595e15 2673quick identification of these macros when @RefTeX{} inserts new
4009494e
GM
2674index entries with @code{reftex-index}. These codes need to be
2675unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
2676@code{\index}, @code{\index*}, and @code{\glossary} macros,
2677respectively.
2678
2679The following string is empty unless your macro adds a superordinate
f99f1641 2680entry to the index key; this is the case for the @code{\astobj} macro.
4009494e
GM
2681
2682The next entry can be a hook function to exclude certain matches, it
2683almost always can be @code{nil}.
2684
2685The final element in the list indicates if the text being indexed needs
2686to be repeated outside the macro. For the normal index macros, this
2687should be @code{t}. Only if the macro typesets the entry in the text
2688(like @code{\ix} and @code{\nindex} in the example do), this should be
2689@code{nil}.
2690
2691To do the same thing with customize, you need to fill in the templates
2692like this:
2693
2694@example
2695Repeat:
2696[INS] [DEL] List:
2697 Macro with args: \ix@{*@}
2698 Index Tag : [Value Menu] String: idx
2699 Access Key : x
2700 Key Prefix :
2701 Exclusion hook : nil
2702 Repeat Outside : [Toggle] off (nil)
2703[INS] [DEL] List:
2704 Macro with args: \nindex@{*@}
2705 Index Tag : [Value Menu] String: name
2706 Access Key : n
2707 Key Prefix :
2708 Exclusion hook : nil
2709 Repeat Outside : [Toggle] off (nil)
2710[INS] [DEL] List:
2711 Macro with args: \astobj@{*@}
2712 Index Tag : [Value Menu] String: idx
2713 Access Key : o
2714 Key Prefix : Astronomical Objects!
2715 Exclusion hook : nil
2716 Repeat Outside : [Toggle] on (non-nil)
2717[INS]
2718@end example
2719
2720With the macro @code{\ix} defined, you may want to change the default
2721macro used for indexing a text phrase (@pxref{Creating Index Entries}).
2722This would be done like this
2723
2724@lisp
2725(setq reftex-index-default-macro '(?x "idx"))
2726@end lisp
2727
2728which specifies that the macro identified with the character @code{?x} (the
2729@code{\ix} macro) should be used for indexing phrases and words already
2730in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
2731The index tag is "idx".
2732
6d1962b3 2733@node Viewing Cross-References
4f595e15 2734@chapter Viewing Cross-References
4009494e
GM
2735@findex reftex-view-crossref
2736@findex reftex-mouse-view-crossref
2737@kindex C-c &
2738@kindex S-mouse-2
2739
4f595e15
RA
2740@RefTeX{} can display cross-referencing information. This means,
2741if two document locations are linked, @RefTeX{} can display the
4009494e
GM
2742matching location(s) in another window. The @code{\label} and @code{\ref}
2743macros are one way of establishing such a link. Also, a @code{\cite}
4f595e15 2744macro is linked to the corresponding @code{\bibitem} macro or a @BibTeX{}
4009494e
GM
2745database entry.
2746
2747The feature is invoked by pressing @kbd{C-c &}
2748(@code{reftex-view-crossref}) while point is on the @var{key} argument
4f595e15 2749of a macro involved in cross-referencing. You can also click with
4009494e
GM
2750@kbd{S-mouse-2} on the macro argument. Here is what will happen for
2751individual classes of macros:
2752
2753@table @asis
2754
2755@item @code{\ref}
2756@cindex @code{\ref}
2757Display the corresponding label definition. All usual
2758variants@footnote{all macros that start with @samp{ref} or end with
2759@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
4f595e15 2760cross-reference display. This works also for labels defined in an
4009494e
GM
2761external document when the current document refers to them through the
2762@code{xr} interface (@pxref{xr (LaTeX package)}).
2763
2764@item @code{\label}
2765@cindex @code{\label}
2766@vindex reftex-label-alist
2767Display a document location which references this label. Pressing
2768@kbd{C-c &} several times moves through the entire document and finds
2769all locations. Not only the @code{\label} macro but also other macros
2770with label arguments (as configured with @code{reftex-label-alist}) are
4f595e15 2771active for cross-reference display.
4009494e
GM
2772
2773@item @code{\cite}
2774@cindex @code{\cite}
4f595e15 2775Display the corresponding @BibTeX{} database entry or @code{\bibitem}.
4009494e 2776All usual variants@footnote{all macros that either start or end with
4f595e15 2777@samp{cite}} of the @code{\cite} macro are active for cross-reference
4009494e
GM
2778display.
2779
2780@item @code{\bibitem}
2781@cindex @code{\bibitem}
2782Display a document location which cites this article. Pressing
2783@kbd{C-c &} several times moves through the entire document and finds
2784all locations.
2785
4f595e15 2786@item @BibTeX{}
4009494e
GM
2787@cindex BibTeX buffer, viewing cite locations from
2788@cindex Viewing cite locations from BibTeX buffer
4f595e15 2789@kbd{C-c &} is also active in @BibTeX{} buffers. All locations in a
4009494e 2790document where the database entry at point is cited will be displayed.
4f595e15 2791On first use, @RefTeX{} will prompt for a buffer which belongs to
4009494e
GM
2792the document you want to search. Subsequent calls will use the same
2793document, until you break this link with a prefix argument to @kbd{C-c
2794&}.
2795
2796@item @code{\index}
2797@cindex @code{\index}
2798Display other locations in the document which are marked by an index
2799macro with the same key argument. Along with the standard @code{\index}
2800and @code{\glossary} macros, all macros configured in
2801@code{reftex-index-macros} will be recognized.
2802@end table
2803
2804@vindex reftex-view-crossref-extra
2805While the display of cross referencing information for the above
4f595e15 2806mentioned macros is hard-coded, you can configure additional relations
4009494e
GM
2807in the variable @code{reftex-view-crossref-extra}.
2808
2809@iftex
2810@chapter All the Rest
2811@end iftex
6d1962b3
GM
2812@ifnottex
2813@raisesections
2814@end ifnottex
4009494e 2815
6d1962b3 2816@node RefTeXs Menu
4f595e15 2817@section @RefTeX{}'s Menu
4009494e
GM
2818@cindex RefTeXs Menu
2819@cindex Menu, in the menu bar
2820
4f595e15 2821@RefTeX{} installs a @code{Ref} menu in the menu bar on systems
4009494e 2822which support this. From this menu you can access all of
4f595e15
RA
2823@RefTeX{}'s commands and a few of its options. There is also a
2824@code{Customize} submenu which can be used to access @RefTeX{}'s
4009494e
GM
2825entire set of options.
2826
6d1962b3 2827@node Key Bindings
4009494e
GM
2828@section Default Key Bindings
2829@cindex Key Bindings, summary
2830
2831Here is a summary of the available key bindings.
2832
2833@kindex C-c =
2834@kindex C-c -
2835@kindex C-c (
2836@kindex C-c )
2837@kindex C-c [
2838@kindex C-c &
2839@kindex S-mouse-2
2840@kindex C-c /
2841@kindex C-c \
2842@kindex C-c |
2843@kindex C-c <
2844@kindex C-c >
2845@example
2846@kbd{C-c =} @code{reftex-toc}
2847@kbd{C-c -} @code{reftex-toc-recenter}
2848@kbd{C-c (} @code{reftex-label}
2849@kbd{C-c )} @code{reftex-reference}
2850@kbd{C-c [} @code{reftex-citation}
2851@kbd{C-c &} @code{reftex-view-crossref}
2852@kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
2853@kbd{C-c /} @code{reftex-index-selection-or-word}
2854@kbd{C-c \} @code{reftex-index-phrase-selection-or-word}
2855@kbd{C-c |} @code{reftex-index-visit-phrases-buffer}
2856@kbd{C-c <} @code{reftex-index}
2857@kbd{C-c >} @code{reftex-display-index}
2858@end example
2859
2860Note that the @kbd{S-mouse-2} binding is only provided if this key is
4f595e15 2861not already used by some other package. @RefTeX{} will not override an
4009494e
GM
2862existing binding to @kbd{S-mouse-2}.
2863
2864Personally, I also bind some functions in the users @kbd{C-c} map for
2865easier access.
2866
2867@c FIXME: Do we need bindings for the Index macros here as well?
2868@c C-c i C-c I or so????
2869@c How about key bindings for reftex-reset-mode and reftex-parse-document?
2870@kindex C-c t
2871@kindex C-c l
2872@kindex C-c r
2873@kindex C-c c
2874@kindex C-c v
2875@kindex C-c s
2876@kindex C-c g
2877@example
2878@kbd{C-c t} @code{reftex-toc}
2879@kbd{C-c l} @code{reftex-label}
2880@kbd{C-c r} @code{reftex-reference}
2881@kbd{C-c c} @code{reftex-citation}
2882@kbd{C-c v} @code{reftex-view-crossref}
2883@kbd{C-c s} @code{reftex-search-document}
2884@kbd{C-c g} @code{reftex-grep-document}
2885@end example
2886
2887@noindent These keys are reserved for the user, so I cannot bind them by
2888default. If you want to have these key bindings available, set in your
2889@file{.emacs} file:
2890
2891@vindex reftex-extra-bindings
2892@lisp
2893(setq reftex-extra-bindings t)
2894@end lisp
2895
2896@vindex reftex-load-hook
4f595e15 2897Changing and adding to @RefTeX{}'s key bindings is best done in the hook
4009494e
GM
2898@code{reftex-load-hook}. For information on the keymaps
2899which should be used to add keys, see @ref{Keymaps and Hooks}.
2900
6d1962b3 2901@node Faces
4009494e
GM
2902@section Faces
2903@cindex Faces
2904
4f595e15 2905@RefTeX{} uses faces when available to structure the selection and
4009494e 2906table of contents buffers. It does not create its own faces, but uses
4f595e15 2907the ones defined in @file{font-lock.el}. Therefore, @RefTeX{} will
4009494e
GM
2908use faces only when @code{font-lock} is loaded. This seems to be
2909reasonable because people who like faces will very likely have it
2910loaded. If you wish to turn off fontification or change the involved
2911faces, see @ref{Options (Fontification)}.
2912
6d1962b3 2913@node Multifile Documents
4009494e
GM
2914@section Multifile Documents
2915@cindex Multifile documents
2916@cindex Documents, spread over files
2917
2918The following is relevant when working with documents spread over many
2919files:
2920
2921@itemize @bullet
2922@item
4f595e15 2923@RefTeX{} has full support for multifile documents. You can edit parts of
4009494e 2924several (multifile) documents at the same time without conflicts.
4f595e15 2925@RefTeX{} provides functions to run @code{grep}, @code{search} and
4009494e
GM
2926@code{query-replace} on all files which are part of a multifile
2927document.
2928
2929@item
2930@vindex tex-main-file
2931@vindex TeX-master
2932All files belonging to a multifile document should define a File
4f595e15
RA
2933Variable (@code{TeX-master} for @AUCTeX{} or @code{tex-main-file} for the
2934standard Emacs @LaTeX{} mode) containing the name of the master file. For
4009494e 2935example, to set the file variable @code{TeX-master}, include something
4f595e15 2936like the following at the end of each @TeX{} file:
4009494e
GM
2937
2938@example
2939%%% Local Variables: ***
2940%%% mode:latex ***
2941%%% TeX-master: "thesis.tex" ***
2942%%% End: ***
2943@end example
2944
4f595e15 2945@AUCTeX{} with the setting
4009494e
GM
2946
2947@lisp
2948(setq-default TeX-master nil)
2949@end lisp
2950
2951will actually ask you for each new file about the master file and insert
2952this comment automatically. For more details see the documentation of
4f595e15 2953the @AUCTeX{} (@pxref{Multifile,,,auctex, The AUCTeX User Manual}), the
4009494e
GM
2954documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
2955The GNU Emacs Manual}) and the Emacs documentation on File Variables
2956(@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
2957
2958@item
2959The context of a label definition must be found in the same file as the
4f595e15 2960label itself in order to be processed correctly by @RefTeX{}. The only
4009494e
GM
2961exception is that section labels referring to a section statement
2962outside the current file can still use that section title as
2963context.
2964@end itemize
2965
6d1962b3 2966@node Language Support
4009494e
GM
2967@section Language Support
2968@cindex Language support
2969
4f595e15 2970Some parts of @RefTeX{} are language dependent. The default
4009494e
GM
2971settings work well for English. If you are writing in a different
2972language, the following hints may be useful:
2973
2974@itemize @bullet
2975@item
2976@vindex reftex-derive-label-parameters
2977@vindex reftex-abbrev-parameters
2978The mechanism to derive a label from context includes the abbreviation
2979of words and omission of unimportant words. These mechanisms may have
2980to be changed for other languages. See the variables
2981@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
2982
2983@item
2984@vindex reftex-translate-to-ascii-function
2985@vindex reftex-label-illegal-re
4f595e15 2986Also, when a label is derived from context, @RefTeX{} clears the
4009494e
GM
2987context string from non-ASCII characters in order to make a valid label.
2988If there should ever be a version of @TeX{} which allows extended
2989characters @emph{in labels}, then we will have to look at the
2990variables @code{reftex-translate-to-ascii-function} and
2991@code{reftex-label-illegal-re}.
2992
2993@item
4f595e15 2994When a label is referenced, @RefTeX{} looks at the word before point
4009494e
GM
2995to guess which label type is required. These @emph{magic words} are
2996different in every language. For an example of how to add magic words,
2997see @ref{Adding Magic Words}.
2998
2999@vindex reftex-multiref-punctuation
3000@vindex reftex-cite-punctuation
3001@item
4f595e15 3002@RefTeX{} inserts ``punctuation'' for multiple references and
4009494e
GM
3003for the author list in citations. Some of this may be language
3004dependent. See the variables @code{reftex-multiref-punctuation} and
3005@code{reftex-cite-punctuation}.
3006@end itemize
3007
6d1962b3 3008@node Finding Files
4009494e
GM
3009@section Finding Files
3010@cindex Finding files
3011
3012In order to find files included in a document via @code{\input} or
4f595e15 3013@code{\include}, @RefTeX{} searches all directories specified in the
4009494e
GM
3014environment variable @code{TEXINPUTS}. Similarly, it will search the
3015path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
4f595e15 3016@BibTeX{} database files.
4009494e 3017
4f595e15 3018When searching, @RefTeX{} will also expand recursive path
4009494e
GM
3019definitions (directories ending in @samp{//} or @samp{!!}). But it will
3020only search and expand directories @emph{explicitly} given in these
3021variables. This may cause problems under the following circumstances:
3022
3023@itemize @bullet
3024@item
4f595e15 3025Most @TeX{} system have a default search path for both @TeX{} files and @BibTeX{}
4009494e 3026files which is defined in some setup file. Usually this default path is
4f595e15
RA
3027for system files which @RefTeX{} does not need to see. But if your
3028document needs @TeX{} files or @BibTeX{} database files in a directory only
3029given in the default search path, @RefTeX{} will fail to find them.
4009494e 3030@item
4f595e15 3031Some @TeX{} systems do not use environment variables at all in order to
4009494e
GM
3032specify the search path. Both default and user search path are then
3033defined in setup files.
3034@end itemize
3035
3036@noindent
3037There are three ways to solve this problem:
3038
3039@itemize @bullet
3040@item
3041Specify all relevant directories explicitly in the environment
3042variables. If for some reason you don't want to mess with the default
3043variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
4f595e15 3044variables and configure @RefTeX{} to use them instead:
4009494e
GM
3045
3046@lisp
3047(setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
3048(setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
3049@end lisp
3050
3051@item
4f595e15 3052Specify the full search path directly in @RefTeX{}'s variables.
4009494e
GM
3053
3054@lisp
3055(setq reftex-texpath-environment-variables
3056 '("./inp:/home/cd/tex//:/usr/local/tex//"))
3057(setq reftex-bibpath-environment-variables
3058 '("/home/cd/tex/lit/"))
3059@end lisp
3060
3061@item
4f595e15 3062Some @TeX{} systems provide stand-alone programs to do the file search just
1df7defd 3063like @TeX{} and @BibTeX{}. E.g., Thomas Esser's @code{teTeX} uses the
4009494e 3064@code{kpathsearch} library which provides the command @code{kpsewhich}
4f595e15 3065to search for files. @RefTeX{} can be configured to use this
4009494e
GM
3066program. Note that the exact syntax of the @code{kpsewhich}
3067command depends upon the version of that program.
3068
3069@lisp
3070(setq reftex-use-external-file-finders t)
3071(setq reftex-external-file-finders
3072 '(("tex" . "kpsewhich -format=.tex %f")
3073 ("bib" . "kpsewhich -format=.bib %f")))
3074@end lisp
3075@end itemize
3076
3077@cindex Noweb files
3078@vindex reftex-file-extensions
3079@vindex TeX-file-extensions
3080Some people like to use RefTeX with noweb files, which usually have the
3081extension @file{.nw}. In order to deal with such files, the new
3082extension must be added to the list of valid extensions in the variable
4f595e15
RA
3083@code{reftex-file-extensions}. When working with @AUCTeX{} as major mode,
3084the new extension must also be known to @AUCTeX{} via the variable
4009494e
GM
3085@code{TeX-file-extension}. For example:
3086
3087@lisp
3088(setq reftex-file-extensions
3089 '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
3090(setq TeX-file-extensions
3091 '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
3092@end lisp
3093
6d1962b3 3094@node Optimizations
4009494e
GM
3095@section Optimizations
3096@cindex Optimizations
3097
3098@b{Note added 2002. Computers have gotten a lot faster, so most of the
3099optimizations discussed below will not be necessary on new machines. I
3100am leaving this stuff in the manual for people who want to write thick
3101books, where some of it still might be useful.}
3102
3103Implementing the principle of least surprises, the default settings of
4f595e15
RA
3104@RefTeX{} ensure a safe ride for beginners and casual users. However,
3105when using @RefTeX{} for a large project and/or on a small computer,
4009494e
GM
3106there are ways to improve speed or memory usage.
3107
3108@itemize @bullet
3109@item
3110@b{Removing Lookup Buffers}@*
3111@cindex Removing lookup buffers
4f595e15 3112@RefTeX{} will load other parts of a multifile document as well as @BibTeX{}
4009494e
GM
3113database files for lookup purposes. These buffers are kept, so that
3114subsequent use of the same files is fast. If you can't afford keeping
3115these buffers around, and if you can live with a speed penalty, try
3116
3117@vindex reftex-keep-temporary-buffers
3118@lisp
3119(setq reftex-keep-temporary-buffers nil)
3120@end lisp
3121
3122@item
3123@b{Partial Document Scans}@*
3124@cindex Partial documents scans
3125@cindex Document scanning, partial
4f595e15 3126A @kbd{C-u} prefix on the major @RefTeX{} commands @code{reftex-label}
4009494e
GM
3127(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
3128@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
3129=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
3130re-parsing of the entire document in order to update the parsing
3131information. For a large document this can be unnecessary, in
4f595e15 3132particular if only one file has changed. @RefTeX{} can be configured
4009494e
GM
3133to do partial scans instead of full ones. @kbd{C-u} re-parsing then
3134does apply only to the current buffer and files included from it.
3135Likewise, the @kbd{r} key in both the label selection buffer and the
3136table-of-contents buffer will only prompt scanning of the file in which
3137the label or section macro near the cursor was defined. Re-parsing of
3138the entire document is still available by using @kbd{C-u C-u} as a
3139prefix, or the capital @kbd{R} key in the menus. To use this feature,
3140try
3141
3142@vindex reftex-enable-partial-scans
3143@lisp
3144(setq reftex-enable-partial-scans t)
3145@end lisp
3146
3147@item
3148@b{Saving Parser Information}@*
3149@cindex Saving parser information
3150@cindex Parse information, saving to a file
3151@vindex reftex-parse-file-extension
4f595e15 3152Even with partial scans enabled, @RefTeX{} still has to make one full
4009494e
GM
3153scan, when you start working with a document. To avoid this, parsing
3154information can be stored in a file. The file @file{MASTER.rel} is used
3155for storing information about a document with master file
3156@file{MASTER.tex}. It is written automatically when you kill a buffer
3157in @code{reftex-mode} or when you exit Emacs. The information is
3158restored when you begin working with a document in a new editing
3159session. To use this feature, put into @file{.emacs}:
3160
3161@vindex reftex-save-parse-info
3162@lisp
3163(setq reftex-save-parse-info t)
3164@end lisp
3165
3166@item
3167@b{Identifying label types by prefix}@*
3168@cindex Parse information, saving to a file
3169@vindex reftex-trust-label-prefix
4f595e15 3170@RefTeX{} normally parses around each label to check in which
4009494e
GM
3171environment this label is located, in order to assign a label type to
3172the label. If your document contains thousands of labels, document
3173parsing will take considerable time. If you have been using label prefixes
4f595e15 3174like tab: and fn: consistently, you can tell @RefTeX{} to get the
4009494e
GM
3175label type directly from the prefix, without additional parsing. This
3176will be faster and also allow labels to end up in the correct category
3177if for some reason it is not possible to derive the correct type from
3178context. For example, to enable this feature for footnote and
3179equation labels, use
3180
3181@lisp
3182(setq reftex-trust-label-prefix '("fn:" "eq:"))
3183@end lisp
3184
3185@item
3186@b{Automatic Document Scans}@*
3187@cindex Automatic document scans
3188@cindex Document scanning, automatic
4f595e15 3189At rare occasions, @RefTeX{} will automatically rescan a part of the
4009494e
GM
3190document. If this gets into your way, it can be turned off with
3191
3192@vindex reftex-allow-automatic-rescan
3193@lisp
3194(setq reftex-allow-automatic-rescan nil)
3195@end lisp
3196
4f595e15 3197@RefTeX{} will then occasionally annotate new labels in the selection
4009494e
GM
3198buffer, saying that their position in the label list in uncertain. A
3199manual document scan will fix this.
3200
3201@item
3202@b{Multiple Selection Buffers}@*
3203@cindex Multiple selection buffers
3204@cindex Selection buffers, multiple
3205Normally, the selection buffer @file{*RefTeX Select*} is re-created for
3206every selection process. In documents with very many labels this can
4f595e15 3207take several seconds. @RefTeX{} provides an option to create a
4009494e
GM
3208separate selection buffer for each label type and to keep this buffer
3209from one selection to the next. These buffers are updated automatically
3210only when a new label has been added in the buffers category with
3211@code{reftex-label}. Updating the buffer takes as long as recreating it
3212- so the time saving is limited to cases where no new labels of that
3213category have been added. To turn on this feature, use
3214
3215@vindex reftex-use-multiple-selection-buffers
3216@lisp
3217(setq reftex-use-multiple-selection-buffers t)
3218@end lisp
3219
3220@noindent
3221@cindex Selection buffers, updating
3222You can also inhibit the automatic updating entirely. Then the
3223selection buffer will always pop up very fast, but may not contain the
3224most recently defined labels. You can always update the buffer by hand,
3225with the @kbd{g} key. To get this behavior, use instead
3226
3227@vindex reftex-auto-update-selection-buffers
3228@lisp
3229(setq reftex-use-multiple-selection-buffers t
3230 reftex-auto-update-selection-buffers nil)
3231@end lisp
3232@end itemize
3233
3234@need 2000
3235@noindent
3236@b{As a summary}, here are the settings I recommend for heavy use of
4f595e15 3237@RefTeX{} with large documents:
4009494e
GM
3238
3239@lisp
3240@group
3241(setq reftex-enable-partial-scans t
3242 reftex-save-parse-info t
3243 reftex-use-multiple-selection-buffers t)
3244@end group
3245@end lisp
3246
6d1962b3 3247@node AUCTeX
4f595e15 3248@section @AUCTeX{}
4009494e
GM
3249@cindex @code{AUCTeX}, Emacs package
3250@cindex Emacs packages, @code{AUCTeX}
3251
4f595e15 3252@AUCTeX{} is without doubt the best major mode for editing @TeX{} and @LaTeX{}
4009494e 3253files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
4f595e15 3254If @AUCTeX{} is not part of your Emacs distribution, you can get
4009494e 3255it@footnote{XEmacs 21.x users may want to install the corresponding
4f595e15 3256XEmacs package.} by FTP from the @value{AUCTEXSITE}.
4009494e
GM
3257
3258@menu
3259* AUCTeX-RefTeX Interface:: How both packages work together
4f595e15 3260* Style Files:: @AUCTeX{}'s style files can support RefTeX
4009494e
GM
3261* Bib-Cite:: Hypertext reading of a document
3262@end menu
3263
6d1962b3 3264@node AUCTeX-RefTeX Interface
4f595e15 3265@subsection The @AUCTeX{}-@RefTeX{} Interface
4009494e 3266
4f595e15 3267@RefTeX{} contains code to interface with @AUCTeX{}. When this
4009494e 3268interface is turned on, both packages will interact closely. Instead of
4f595e15
RA
3269using @RefTeX{}'s commands directly, you can then also use them
3270indirectly as part of the @AUCTeX{}
3271environment@footnote{@RefTeX{} 4.0 and @AUCTeX{} 9.10c will be
4009494e
GM
3272needed for all of this to work. Parts of it work also with earlier
3273versions.}. The interface is turned on with
3274
3275@lisp
3276(setq reftex-plug-into-AUCTeX t)
3277@end lisp
3278
3279If you need finer control about which parts of the interface are used
3280and which not, read the docstring of the variable
3281@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
3282customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
3283
3284The following list describes the individual parts of the interface.
3285
3286@itemize @bullet
3287@item
3288@findex reftex-label
3289@vindex LaTeX-label-function, @r{AUCTeX}
3290@kindex C-c C-e
3291@kindex C-c C-s
3292@findex LaTeX-section, @r{AUCTeX}
3293@findex TeX-insert-macro, @r{AUCTeX}
4f595e15 3294@b{@AUCTeX{} calls @code{reftex-label} to insert labels}@*
4009494e 3295When a new section is created with @kbd{C-c C-s}, or a new environment
4f595e15 3296is inserted with @kbd{C-c C-e}, @AUCTeX{} normally prompts for a label to
4009494e 3297go with it. With the interface, @code{reftex-label} is called instead.
4f595e15
RA
3298For example, if you type @kbd{C-c C-e equation @key{RET}}, @AUCTeX{} and
3299@RefTeX{} will insert
4009494e
GM
3300
3301@example
3302\begin@{equation@}
3303\label@{eq:1@}
3304
3305\end@{equation@}
3306@end example
3307
3308@noindent
3309without further prompts.
3310
4f595e15 3311Similarly, when you type @kbd{C-c C-s section @key{RET}}, @RefTeX{}
4009494e
GM
3312will offer its default label which is derived from the section title.
3313
3314@item
4f595e15
RA
3315@b{@AUCTeX{} tells @RefTeX{} about new sections}@*
3316When creating a new section with @kbd{C-c C-s}, @RefTeX{} will not
4009494e
GM
3317have to rescan the buffer in order to see it.
3318
3319@item
3320@findex reftex-arg-label
3321@findex TeX-arg-label, @r{AUCTeX function}
3322@findex reftex-arg-ref
3323@findex TeX-arg-ref, @r{AUCTeX function}
3324@findex reftex-arg-cite
3325@findex TeX-arg-cite, @r{AUCTeX function}
3326@findex reftex-arg-index
3327@findex TeX-arg-index, @r{AUCTeX function}
3328@findex TeX-insert-macro, @r{AUCTeX function}
3329@kindex C-c @key{RET}
4f595e15
RA
3330@b{@RefTeX{} supplies macro arguments}@* When you insert a macro
3331interactively with @kbd{C-c @key{RET}}, @AUCTeX{} normally prompts for
4009494e
GM
3332macro arguments. Internally, it uses the functions
3333@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
3334prompt for arguments which are labels, citation keys and index entries.
3335The interface takes over these functions@footnote{@code{fset} is used to
4f595e15 3336do this, which is not reversible. However, @RefTeX{} implements the
4009494e 3337old functionality when you later decide to turn off the interface.} and
4f595e15
RA
3338supplies the macro arguments with @b{@RefTeX{}'s} mechanisms. For
3339example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @RefTeX{}
4009494e
GM
3340will supply its label selection process (@pxref{Referencing
3341Labels}).
3342
3343@item
4f595e15
RA
3344@b{@RefTeX{} tells @AUCTeX{} about new labels, citation and index keys}@*
3345@RefTeX{} will add all newly created labels to @AUCTeX{}'s completion list.
4009494e
GM
3346@end itemize
3347
6d1962b3 3348@node Style Files
4009494e
GM
3349@subsection Style Files
3350@cindex Style files, AUCTeX
3351@findex TeX-add-style-hook, @r{AUCTeX}
4f595e15 3352Style files are Emacs Lisp files which are evaluated by @AUCTeX{} in
4009494e
GM
3353association with the @code{\documentclass} and @code{\usepackage}
3354commands of a document (@pxref{Style Files,,,auctex}). Support for
4f595e15 3355@RefTeX{} in such a style file is useful when the @LaTeX{} style
4009494e 3356defines macros or environments connected with labels, citations, or the
1df7defd 3357index. Many style files (e.g., @file{amsmath.el} or @file{natbib.el})
4f595e15 3358distributed with @AUCTeX{} already support @RefTeX{} in this
4009494e
GM
3359way.
3360
4f595e15 3361Before calling a @RefTeX{} function, the style hook should always
4009494e 3362test for the availability of the function, so that the style file will
4f595e15 3363also work for people who do not use @RefTeX{}.
4009494e
GM
3364
3365Additions made with style files in the way described below remain local
3366to the current document. For example, if one package uses AMSTeX, the
4f595e15 3367style file will make @RefTeX{} switch over to @code{\eqref}, but
4009494e
GM
3368this will not affect other documents.
3369
3370@findex reftex-add-label-environments
3371@findex reftex-add-to-label-alist
3372A style hook may contain calls to
3373@code{reftex-add-label-environments}@footnote{This used to be the
3374function @code{reftex-add-to-label-alist} which is still available as an
3375alias for compatibility.} which defines additions to
3376@code{reftex-label-alist}. The argument taken by this function must have
3377the same format as @code{reftex-label-alist}. The @file{amsmath.el}
4f595e15 3378style file of @AUCTeX{} for example contains the following:
4009494e
GM
3379
3380@lisp
3381@group
3382(TeX-add-style-hook "amsmath"
3383 (lambda ()
3384 (if (fboundp 'reftex-add-label-environments)
3385 (reftex-add-label-environments '(AMSTeX)))))
3386@end group
3387@end lisp
3388
3389@noindent
3390@findex LaTeX-add-environments, @r{AUCTeX}
3391while a package @code{myprop} defining a @code{proposition} environment
3392with @code{\newtheorem} might use
3393
3394@lisp
3395@group
3396(TeX-add-style-hook "myprop"
3397 (lambda ()
3398 (LaTeX-add-environments '("proposition" LaTeX-env-label))
3399 (if (fboundp 'reftex-add-label-environments)
3400 (reftex-add-label-environments
3401 '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
3402 ("Proposition" "Prop.") -3))))))
3403@end group
3404@end lisp
3405
3406@findex reftex-set-cite-format
3407Similarly, a style hook may contain a call to
3408@code{reftex-set-cite-format} to set the citation format. The style
3409file @file{natbib.el} for the Natbib citation style does switch
4f595e15 3410@RefTeX{}'s citation format like this:
4009494e
GM
3411
3412@lisp
3413(TeX-add-style-hook "natbib"
3414 (lambda ()
3415 (if (fboundp 'reftex-set-cite-format)
3416 (reftex-set-cite-format 'natbib))))
3417@end lisp
3418
3419@findex reftex-add-index-macros
3420The hook may contain a call to @code{reftex-add-index-macros} to
3421define additional @code{\index}-like macros. The argument must have
3422the same format as @code{reftex-index-macros}. It may be a symbol, to
3423trigger support for one of the builtin index packages. For example,
3424the style @file{multind.el} contains
3425
3426@lisp
3427(TeX-add-style-hook "multind"
3428 (lambda ()
3429 (and (fboundp 'reftex-add-index-macros)
9360256a 3430 (reftex-add-index-macros '(multind)))))
4009494e
GM
3431@end lisp
3432
3433If you have your own package @file{myindex} which defines the
4f595e15 3434following macros to be used with the @LaTeX{} @file{index.sty} file
4009494e
GM
3435@example
3436\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
3437\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
3438@end example
3439
3440you could write this in the style file @file{myindex.el}:
3441
3442@lisp
3443(TeX-add-style-hook "myindex"
3444 (lambda ()
3445 (TeX-add-symbols
3446 '("molec" TeX-arg-index)
3447 '("aindex" TeX-arg-index))
3448 (if (fboundp 'reftex-add-index-macros)
3449 (reftex-add-index-macros
3450 '(("molec@{*@}" "idx" ?m "Molecules!" nil nil)
3451 ("aindex@{*@}" "author" ?a "" nil nil))))))
3452@end lisp
3453
3454@findex reftex-add-section-levels
3455Finally the hook may contain a call to @code{reftex-add-section-levels}
3456to define additional section statements. For example, the FoilTeX class
3457has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
4f595e15 3458is a style file @file{foils.el} that will inform @RefTeX{} about these:
4009494e
GM
3459
3460@lisp
3461(TeX-add-style-hook "foils"
3462 (lambda ()
3463 (if (fboundp 'reftex-add-section-levels)
3464 (reftex-add-section-levels '(("foilhead" . 3)
3465 ("rotatefoilhead" . 3))))))
3466@end lisp
3467
6d1962b3 3468@node Bib-Cite
4009494e
GM
3469@subsection Bib-Cite
3470@cindex @code{bib-cite}, Emacs package
3471@cindex Emacs packages, @code{bib-cite}
3472
3473Once you have written a document with labels, references and citations,
4f595e15 3474it can be nice to read it like a hypertext document. @RefTeX{} has
4009494e
GM
3475support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
3476&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
3477@code{reftex-search-document}. A somewhat fancier interface with mouse
3478highlighting is provided (among other things) by Peter S. Galbraith's
3479@file{bib-cite.el}. There is some overlap in the functionalities of
4f595e15
RA
3480Bib-cite and @RefTeX{}. Bib-cite.el comes bundled with
3481@AUCTeX{}.
4009494e
GM
3482
3483Bib-cite version 3.06 and later can be configured so that bib-cite's
4f595e15
RA
3484mouse functions use @RefTeX{} for displaying references and citations.
3485This can be useful in particular when working with the @LaTeX{} @code{xr}
4009494e 3486package or with an explicit @code{thebibliography} environment (rather
4f595e15 3487than @BibTeX{}). Bib-cite cannot handle those, but @RefTeX{} does. To
4009494e
GM
3488make use of this feature, try
3489
3490@vindex bib-cite-use-reftex-view-crossref
3491@lisp
3492(setq bib-cite-use-reftex-view-crossref t)
3493@end lisp
3494
3495@page
6d1962b3 3496@node Problems and Work-Arounds
4009494e
GM
3497@section Problems and Work-arounds
3498@cindex Problems and work-arounds
3499
3500@itemize @bullet
3501@item
4f595e15 3502@b{@LaTeX{} commands}@*
4009494e
GM
3503@cindex LaTeX commands, not found
3504@code{\input}, @code{\include}, and @code{\section} (etc.) statements
3505have to be first on a line (except for white space).
3506
3507@item
3508@b{Commented regions}@*
3509@cindex Labels, commented out
4f595e15 3510@RefTeX{} sees also labels in regions commented out and will refuse to
4009494e
GM
3511make duplicates of such labels. This is considered to be a feature.
3512
3513@item
3514@b{Wrong section numbers}@*
3515@cindex Section numbers, wrong
3516@vindex reftex-enable-partial-scans
3517When using partial scans (@code{reftex-enable-partial-scans}), the section
3518numbers in the table of contents may eventually become wrong. A full
3519scan will fix this.
3520
3521@item
3522@b{Local settings}@*
3523@cindex Settings, local
3524@findex reftex-add-label-environments
3525@findex reftex-set-cite-format
3526@findex reftex-add-section-levels
3527The label environment definitions in @code{reftex-label-alist} are
3528global and apply to all documents. If you need to make definitions
3529local to a document, because they would interfere with settings in other
4f595e15 3530documents, you should use @AUCTeX{} and set up style files with calls to
4009494e
GM
3531@code{reftex-add-label-environments}, @code{reftex-set-cite-format},
3532@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
3533Settings made with these functions remain local to the current
3534document. @xref{AUCTeX}.
3535
3536@item
3537@b{Funny display in selection buffer}@*
3538@cindex @code{x-symbol}, Emacs package
3539@cindex Emacs packages, @code{x-symbol}
3540@cindex @code{isotex}, Emacs package
3541@cindex Emacs packages, @code{isotex}
3542@cindex @code{iso-cvt}, Emacs package
3543@cindex Emacs packages, @code{iso-cvt}
3544When using packages which make the buffer representation of a file
1df7defd 3545different from its disk representation (e.g., x-symbol, isotex,
4f595e15 3546iso-cvt) you may find that @RefTeX{}'s parsing information sometimes
4009494e 3547reflects the disk state of a file. This happens only in @emph{unvisited}
4f595e15 3548parts of a multifile document, because @RefTeX{} visits these files
4009494e
GM
3549literally for speed reasons. Then both short context and section
3550headings may look different from what you usually see on your screen.
3551In rare cases @code{reftex-toc} may have problems to jump to an affected
3552section heading. There are three possible ways to deal with
3553this:
3554@itemize @minus
3555@item
3556@vindex reftex-keep-temporary-buffers
3557@code{(setq reftex-keep-temporary-buffers t)}@*
4f595e15 3558This implies that @RefTeX{} will load all parts of a multifile
1df7defd 3559document into Emacs (i.e., there won't be any temporary buffers).
4009494e
GM
3560@item
3561@vindex reftex-initialize-temporary-buffers
3562@code{(setq reftex-initialize-temporary-buffers t)}@*
3563This means full initialization of temporary buffers. It involves
3564a penalty when the same unvisited file is used for lookup often.
3565@item
3566Set @code{reftex-initialize-temporary-buffers} to a list of hook
3567functions doing a minimal initialization.
3568@end itemize
3569@vindex reftex-refontify-context
3570See also the variable @code{reftex-refontify-context}.
3571
3572@item
3573@b{Labels as arguments to \begin}@*
3574@cindex @code{pf}, LaTeX package
3575@cindex LaTeX packages, @code{pf}
3576Some packages use an additional argument to a @code{\begin} macro
1df7defd 3577to specify a label. E.g., Lamport's @file{pf.sty} uses both
4009494e
GM
3578@example
3579\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
3580 @var{claim}
3581 \end@{step+@}
3582@end example
3583
3584@noindent
4f595e15 3585We need to trick @RefTeX{} into swallowing this:
4009494e
GM
3586
3587@lisp
3588@group
3589;; Configuration for Lamport's pf.sty
3590(setq reftex-label-alist
3591 '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
3592 ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
3593@end group
3594@end lisp
3595
3596@noindent
3597The first line is just a normal configuration for a macro. For the
4f595e15 3598@code{step+} environment we actually tell @RefTeX{} to look for the
4009494e
GM
3599@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
3600argument (which really is a second argument to the macro @code{\begin})
3601as a label of type @code{?p}. Argument count for this macro starts only
3602after the @samp{@{step+@}}, also when specifying how to get
3603context.
3604
3605@item
3606@b{Idle timers in XEmacs}@*
3607@cindex Idle timer restart
3608@vindex reftex-use-itimer-in-xemacs
3609In XEmacs, idle timer restart does not work reliably after fast
4f595e15 3610keystrokes. Therefore @RefTeX{} currently uses the post command
4009494e
GM
3611hook to start the timer used for automatic crossref information. When
3612this bug gets fixed, a real idle timer can be requested with
3613@lisp
3614(setq reftex-use-itimer-in-xemacs t)
3615@end lisp
3616
3617@item
3618@b{Viper mode}@*
3619@cindex Viper mode
3620@cindex Key bindings, problems with Viper mode
3621@findex viper-harness-minor-mode
3622With @i{Viper} mode prior to Vipers version 3.01, you need to protect
4f595e15 3623@RefTeX{}'s keymaps with
4009494e
GM
3624
3625@lisp
3626(viper-harness-minor-mode "reftex")
3627@end lisp
3628
3629@end itemize
3630
3631@page
6d1962b3 3632@node Imprint
4009494e
GM
3633@section Imprint
3634@cindex Imprint
3635@cindex Maintainer
3636@cindex Acknowledgments
3637@cindex Thanks
3638@cindex Bug reports
4f595e15
RA
3639@cindex @code{http}, @RefTeX{} home page
3640@cindex @code{ftp}, @RefTeX{} site
4009494e 3641
4f595e15 3642@RefTeX{} was written by @i{Carsten Dominik}
4009494e 3643@email{dominik@@science.uva.nl}, with contributions by @i{Stephen
4f595e15 3644Eglen}. @RefTeX{} is currently maintained by @value{MAINTAINER}, see
4009494e
GM
3645the @value{MAINTAINERSITE} for detailed information.
3646
4f595e15 3647If you have questions about @RefTeX{}, you can send email to the
4009494e
GM
3648@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write
3649to the @value{DEVELADDRESS}. And in the rare case of finding a bug,
3650please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a
3651bug report with useful information about your setup. Remember to add
3652essential information like a recipe for reproducing the bug, what you
3653expected to happen, and what actually happened. Send the bug report to
3654the @value{BUGADDRESS}.
3655
3656There are also several Usenet groups which have competent readers who
3657might be able to help: @code{comp.emacs}, @code{gnu.emacs.help},
3658@code{comp.emacs.xemacs}, and @code{comp.text.tex}.
3659
4f595e15 3660Thanks to the people on the Net who have used @RefTeX{} and helped
4009494e
GM
3661developing it with their reports. In particular thanks to @i{Ralf
3662Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton,
3663Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai
3664Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan
3665Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz,
4f595e15
RA
3666Juri Linkov, Wolfgang Mayer, Rory Molinari, Stefan Monnier, Laurent
3667Mugnier, Dan Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko,
3668Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph
3669Wedler, Alan Williams, Roland Winkler, Hans-Christoph Wirth, Eli
3670Zaretskii}.
4009494e
GM
3671
3672The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
3673@file{bib-cite.el}.
3674
3675Finally thanks to @i{Uwe Bolick} who first got me interested in
4f595e15 3676supporting @LaTeX{} labels and references with an editor (which was
4009494e
GM
3677MicroEmacs at the time).
3678
6d1962b3
GM
3679@c Turn off the raising that we turned on in ``All the rest''.
3680@ifnottex
3681@lowersections
3682@end ifnottex
3683
3684@node Commands
4009494e
GM
3685@chapter Commands
3686@cindex Commands, list of
3687
4f595e15
RA
3688Here is a summary of @RefTeX{}'s commands which can be executed from
3689@LaTeX{} files. Command which are executed from the special buffers are
4009494e
GM
3690not described here. All commands are available from the @code{Ref}
3691menu. See @xref{Key Bindings}.
3692
3693@deffn Command reftex-toc
3694Show the table of contents for the current document. When called with
3695one ore two @kbd{C-u} prefixes, rescan the document first.
3696@end deffn
3697
3698@deffn Command reftex-label
3699Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
3700document rescan first.
3701@end deffn
3702
3703@deffn Command reftex-reference
3704Start a selection process to select a label, and insert a reference to
3705it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
3706@end deffn
3707
3708@deffn Command reftex-citation
4f595e15
RA
3709Make a citation using @BibTeX{} database files. After prompting for a regular
3710expression, scans the buffers with @BibTeX{} entries (taken from the
4009494e
GM
3711@code{\bibliography} command or a @code{thebibliography} environment)
3712and offers the matching entries for selection. The selected entry is
3713formatted according to @code{reftex-cite-format} and inserted into the
3714buffer. @*
3715When called with a @kbd{C-u} prefix, prompt for optional arguments in
3716cite macros. When called with a numeric prefix, make that many citations.
3717When called with point inside the braces of a @code{\cite} command, it
3718will add another key, ignoring the value of
3719@code{reftex-cite-format}. @*
3720The regular expression uses an expanded syntax: @samp{&&} is interpreted
3721as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
3722both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
3723on knows citation keys is possible. @samp{=} is a good regular
3724expression to match all entries in all files.
3725@end deffn
3726
3727@deffn Command reftex-index
3728Query for an index macro and insert it along with its arguments. The
3729index macros available are those defined in @code{reftex-index-macro} or
4f595e15
RA
3730by a call to @code{reftex-add-index-macros}, typically from an @AUCTeX{}
3731style file. @RefTeX{} provides completion for the index tag and the
4009494e
GM
3732index key, and will prompt for other arguments.
3733@end deffn
3734
3735@deffn Command reftex-index-selection-or-word
3736Put current selection or the word near point into the default index
3737macro. This uses the information in @code{reftex-index-default-macro}
3738to make an index entry. The phrase indexed is the current selection or
3739the word near point. When called with one @kbd{C-u} prefix, let the
3740user have a chance to edit the index entry. When called with 2
3741@kbd{C-u} as prefix, also ask for the index macro and other stuff. When
4f595e15
RA
3742called inside @TeX{} math mode as determined by the @file{texmathp.el}
3743library which is part of @AUCTeX{}, the string is first processed with the
4009494e
GM
3744@code{reftex-index-math-format}, which see.
3745@end deffn
3746
3747@deffn Command reftex-index-phrase-selection-or-word
3748Add current selection or the word at point to the phrases buffer.
3749When you are in transient-mark-mode and the region is active, the
f99f1641
PE
3750selection will be used; otherwise the word at point.
3751You get a chance to edit the entry in the phrases buffer; to save the
4f595e15 3752buffer and return to the @LaTeX{} document, finish with @kbd{C-c C-c}.
4009494e
GM
3753@end deffn
3754
3755@deffn Command reftex-index-visit-phrases-buffer
3756Switch to the phrases buffer, initialize if empty.
3757@end deffn
3758
3759@deffn Command reftex-index-phrases-apply-to-region
3760Index all index phrases in the current region.
3761This works exactly like global indexing from the index phrases buffer,
3762but operation is restricted to the current region.
3763@end deffn
3764
3765@deffn Command reftex-display-index
3766Display a buffer with an index compiled from the current document.
3767When the document has multiple indices, first prompts for the correct one.
3768When index support is turned off, offer to turn it on.
3769With one or two @kbd{C-u} prefixes, rescan document first.
3770With prefix 2, restrict index to current document section.
3771With prefix 3, restrict index to active region.
3772@end deffn
3773
3774@deffn Command reftex-view-crossref
3775View cross reference of macro at point. Point must be on the @var{key}
3776argument. Works with the macros @code{\label}, @code{\ref},
3777@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
3778these. Where it makes sense, subsequent calls show additional
3779locations. See also the variable @code{reftex-view-crossref-extra} and
3780the command @code{reftex-view-crossref-from-bibtex}. With one or two
3781@kbd{C-u} prefixes, enforce rescanning of the document. With argument
37822, select the window showing the cross reference.
3783@end deffn
3784
3785@deffn Command reftex-view-crossref-from-bibtex
4f595e15
RA
3786View location in a @LaTeX{} document which cites the @BibTeX{} entry at point.
3787Since @BibTeX{} files can be used by many @LaTeX{} documents, this function
3788prompts upon first use for a buffer in @RefTeX{} mode. To reset this
4009494e
GM
3789link to a document, call the function with a prefix arg. Calling
3790this function several times find successive citation locations.
3791@end deffn
3792
3793@deffn Command reftex-create-tags-file
3794Create TAGS file by running @code{etags} on the current document. The
3795TAGS file is also immediately visited with
3796@code{visit-tags-table}.
3797@end deffn
3798
3799@deffn Command reftex-grep-document
3800Run grep query through all files related to this document.
3801With prefix arg, force to rescan document.
3802No active TAGS table is required.
3803@end deffn
3804
3805@deffn Command reftex-search-document
3806Regexp search through all files of the current document.
3807Starts always in the master file. Stops when a match is found.
3808No active TAGS table is required.
3809@end deffn
3810
3811@deffn Command reftex-query-replace-document
3812Run a query-replace-regexp of @var{from} with @var{to} over the entire
3813document. With prefix arg, replace only word-delimited matches. No
3814active TAGS table is required.
3815@end deffn
3816
3817@deffn Command reftex-isearch-minor-mode
3818Toggle a minor mode which enables incremental search to work globally
4f595e15 3819on the entire multifile document. Files will be searched in the
4009494e
GM
3820sequence they appear in the document.
3821@end deffn
3822
3823@deffn Command reftex-goto-label
3824Prompt for a label (with completion) and jump to the location of this
3825label. Optional prefix argument @var{other-window} goes to the label in
3826another window.
3827@end deffn
3828
3829
3830@deffn Command reftex-change-label
3831Query replace @var{from} with @var{to} in all @code{\label} and
3832@code{\ref} commands. Works on the entire multifile document. No
3833active TAGS table is required.
3834@end deffn
3835
3836@deffn Command reftex-renumber-simple-labels
3837Renumber all simple labels in the document to make them sequentially.
3838Simple labels are the ones created by RefTeX, consisting only of the
3839prefix and a number. After the command completes, all these labels will
3840have sequential numbers throughout the document. Any references to the
4f595e15 3841labels will be changed as well. For this, @RefTeX{} looks at the
4009494e
GM
3842arguments of any macros which either start or end with the string
3843@samp{ref}. This command should be used with care, in particular in
3844multifile documents. You should not use it if another document refers
3845to this one with the @code{xr} package.
3846@end deffn
3847
3848@deffn Command reftex-find-duplicate-labels
3849Produce a list of all duplicate labels in the document.
3850@end deffn
3851
3852@deffn Command reftex-create-bibtex-file
4f595e15
RA
3853@vindex reftex-create-bibtex-header
3854@vindex reftex-create-bibtex-footer
3855Create a new @BibTeX{} database file with all entries referenced in
3856document. The command prompts for a filename and writes the collected
3857entries to that file. Only entries referenced in the current document
3858with any @code{\cite}-like macros are used. The sequence in the new
3859file is the same as it was in the old database.
3860
3861Entries referenced from other entries must appear after all referencing
3862entries.
3863
3864You can define strings to be used as header or footer for the created
3865files in the variables @code{reftex-create-bibtex-header} or
3866@code{reftex-create-bibtex-footer} respectively.
4009494e
GM
3867@end deffn
3868
3869@deffn Command reftex-customize
4f595e15 3870Run the customize browser on the @RefTeX{} group.
4009494e
GM
3871@end deffn
3872@deffn Command reftex-show-commentary
3873Show the commentary section from @file{reftex.el}.
3874@end deffn
3875@deffn Command reftex-info
4f595e15 3876Run info on the top @RefTeX{} node.
4009494e
GM
3877@end deffn
3878@deffn Command reftex-parse-document
3879Parse the entire document in order to update the parsing information.
3880@end deffn
3881@deffn Command reftex-reset-mode
3882Enforce rebuilding of several internal lists and variables. Also
3883removes the parse file associated with the current document.
3884@end deffn
3885
6d1962b3 3886@node Options
4009494e
GM
3887@chapter Options, Keymaps, Hooks
3888@cindex Options, list of
3889
4f595e15 3890Here is a complete list of @RefTeX{}'s configuration variables. All
f99f1641 3891variables have customize support, so if you are not familiar with Emacs
4009494e
GM
3892Lisp (and even if you are) you might find it more comfortable to use
3893@code{customize} to look at and change these variables. @kbd{M-x
3894reftex-customize} will get you there.
3895
3896@menu
3897* Options (Table of Contents)::
3898* Options (Defining Label Environments)::
3899* Options (Creating Labels)::
3900* Options (Referencing Labels)::
3901* Options (Creating Citations)::
3902* Options (Index Support)::
3903* Options (Viewing Cross-References)::
3904* Options (Finding Files)::
3905* Options (Optimizations)::
3906* Options (Fontification)::
3907* Options (Misc)::
6d1962b3 3908* Keymaps and Hooks::
4009494e
GM
3909@end menu
3910
6d1962b3 3911@node Options (Table of Contents)
4009494e
GM
3912@section Table of Contents
3913@cindex Options, table of contents
3914@cindex Table of contents, options
3915
3916@defopt reftex-include-file-commands
4f595e15 3917List of @LaTeX{} commands which input another file.
4009494e
GM
3918The file name is expected after the command, either in braces or separated
3919by whitespace.
3920@end defopt
3921
3922@defopt reftex-max-section-depth
3923Maximum depth of section levels in document structure.
4f595e15 3924Standard @LaTeX{} needs 7, default is 12.
4009494e
GM
3925@end defopt
3926
3927@defopt reftex-section-levels
3928Commands and levels used for defining sections in the document. The
3929@code{car} of each cons cell is the name of the section macro. The
3930@code{cdr} is a number indicating its level. A negative level means the
3931same as the positive value, but the section will never get a number.
3932The @code{cdr} may also be a function which then has to return the
3933level. This list is also used for promotion and demotion of sectioning
3934commands. If you are using a document class which has several sets of
3935sectioning commands, promotion only works correctly if this list is
3936sorted first by set, then within each set by level. The promotion
3937commands always select the nearest entry with the correct new level.
3938
3939@end defopt
3940
3941@defopt reftex-toc-max-level
1df7defd 3942The maximum level of toc entries which will be included in the TOC@.
4009494e
GM
3943Section headings with a bigger level will be ignored. In RefTeX,
3944chapters are level 1, sections level 2 etc. This variable can be
3945changed from within the @file{*toc*} buffer with the @kbd{t} key.
3946@end defopt
3947
3948@defopt reftex-part-resets-chapter
3949Non-@code{nil} means, @code{\part} is like any other sectioning command.
3950This means, part numbers will be included in the numbering of chapters, and
3951chapter counters will be reset for each part.
3952When @code{nil} (the default), parts are special, do not reset the
3953chapter counter and also do not show up in chapter numbers.
3954@end defopt
3955
3956@defopt reftex-auto-recenter-toc
3957Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
3958When active, the @file{*TOC*} window will always show the section you
3959are currently working in. Recentering happens whenever Emacs is idle for
3960more than @code{reftex-idle-time} seconds.
3961
3962Value @code{t} means, turn on immediately when RefTeX gets started. Then,
3963recentering will work for any toc window created during the session.
3964
3965Value @code{frame} (the default) means, turn automatic recentering on
3966only while the dedicated TOC frame does exist, and do the recentering
3967only in that frame. So when creating that frame (with @kbd{d} key in an
3968ordinary TOC window), the automatic recentering is turned on. When the
3969frame gets destroyed, automatic recentering is turned off again.
3970
9858f6c3 3971This feature can be turned on and off from the menu
4009494e
GM
3972(Ref->Options).
3973@end defopt
3974
3975@defopt reftex-toc-split-windows-horizontally
3976Non-@code{nil} means, create TOC window by splitting window
3977horizontally. The default is to split vertically.
3978@end defopt
3979
3980@defopt reftex-toc-split-windows-fraction
3981Fraction of the width or height of the frame to be used for TOC window.
3982@end defopt
3983
3984@defopt reftex-toc-keep-other-windows
3985Non-@code{nil} means, split the selected window to display the
3986@file{*toc*} buffer. This helps to keep the window configuration, but
3987makes the @file{*toc*} small. When @code{nil}, all other windows except
3988the selected one will be deleted, so that the @file{*toc*} window fills
3989half the frame.
3990@end defopt
3991
3992@defopt reftex-toc-include-file-boundaries
3993Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
3994This flag can be toggled from within the @file{*toc*} buffer with the
3995@kbd{i} key.
3996@end defopt
3997
3998@defopt reftex-toc-include-labels
3999Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
4000can be toggled from within the @file{*toc*} buffer with the @kbd{l}
4001key.
4002@end defopt
4003
4004@defopt reftex-toc-include-index-entries
4005Non-@code{nil} means, include index entries in @file{*toc*} buffer.
4006This flag can be toggled from within the @file{*toc*} buffer with the
4007@kbd{i} key.
4008@end defopt
4009
4010@defopt reftex-toc-include-context
4011Non-@code{nil} means, include context with labels in the @file{*toc*}
4012buffer. Context will only be shown if the labels are visible as well.
4013This flag can be toggled from within the @file{*toc*} buffer with the
4014@kbd{c} key.
4015@end defopt
4016
4017@defopt reftex-toc-follow-mode
4018Non-@code{nil} means, point in @file{*toc*} buffer (the
4019table-of-contents buffer) will cause other window to follow. The other
4020window will show the corresponding part of the document. This flag can
4021be toggled from within the @file{*toc*} buffer with the @kbd{f}
4022key.
4023@end defopt
4024
4025@deffn {Normal Hook} reftex-toc-mode-hook
4026Normal hook which is run when a @file{*toc*} buffer is
4027created.
4028@end deffn
4029
4030@deffn Keymap reftex-toc-map
4031The keymap which is active in the @file{*toc*} buffer.
4032(@pxref{Table of Contents}).
4033@end deffn
4034
6d1962b3 4035@node Options (Defining Label Environments)
4009494e
GM
4036@section Defining Label Environments
4037@cindex Options, defining label environments
4038@cindex Defining label environments, options
4039
4040@defopt reftex-default-label-alist-entries
4041Default label alist specifications. It is a list of symbols with
4042associations in the constant @code{reftex-label-alist-builtin}.
4043@code{LaTeX} should always be the last entry.
4044@end defopt
4045
4046@defopt reftex-label-alist
4047Set this variable to define additions and changes to the defaults in
4048@code{reftex-default-label-alist-entries}. The only things you
4049@emph{must not} change is that @code{?s} is the type indicator for
4050section labels, and @key{SPC} for the @code{any} label type. These are
4051hard-coded at other places in the code.
4052
4053The value of the variable must be a list of items. Each item is a list
4054itself and has the following structure:
4055
4056@example
4057 (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
4058 @var{context-method} (@var{magic-word} ... ) @var{toc-level})
4059@end example
4060
4061Each list entry describes either an environment carrying a counter for
4f595e15 4062use with @code{\label} and @code{\ref}, or a @LaTeX{} macro defining a
4009494e
GM
4063label as (or inside) one of its arguments. The elements of each list
4064entry are:
4065
4066@table @asis
4067@item @var{env-or-macro}
4068Name of the environment (like @samp{table}) or macro (like
4069@samp{\myfig}). For macros, indicate the arguments, as in
4070@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
4071arguments, a star to mark the label argument, if any. The macro does
f99f1641 4072not have to have a label argument; you could also use
4009494e
GM
4073@samp{\label@{...@}} inside one of its arguments.
4074
4075Special names: @code{section} for section labels, @code{any} to define a
4076group which contains all labels.
4077
4078This may also be a function to do local parsing and identify point to be
4079in a non-standard label environment. The function must take an
4080argument @var{bound} and limit backward searches to this value. It
4081should return either nil or a cons cell @code{(@var{function}
4082. @var{position})} with the function symbol and the position where the
4083special environment starts. See the Info documentation for an
4084example.
4085
4086Finally this may also be @code{nil} if the entry is only meant to change
4087some settings associated with the type indicator character (see
4088below).
4089
4090@item @var{type-key}
4091Type indicator character, like @code{?t}, must be a printable ASCII
4092character. The type indicator is a single character which defines a
4093label type. Any label inside the environment or macro is assumed to
4094belong to this type. The same character may occur several times in this
4095list, to cover cases in which different environments carry the same
4096label type (like @code{equation} and @code{eqnarray}). If the type
4097indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
4098the macro defines neutral labels just like @code{\label}. In this case
4f595e15 4099the remainder of this entry is ignored.
4009494e
GM
4100
4101@item @var{label-prefix}
4102Label prefix string, like @samp{tab:}. The prefix is a short string
4103used as the start of a label. It may be the empty string. The prefix
4104may contain the following @samp{%} escapes:
4105
4106@example
4107%f Current file name, directory and extension stripped.
4108%F Current file name relative to master file directory.
4109%m Master file name, directory and extension stripped.
4110%M Directory name (without path) where master file is located.
4111%u User login name, on systems which support this.
4112%S A section prefix derived with variable @code{reftex-section-prefixes}.
4113@end example
4114
4115@noindent
4116Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
4117@samp{eq:intro:}.
4118
4119@item @var{reference-format}
4f595e15 4120Format string for reference insertion in buffer. @samp{%s} will be
4009494e
GM
4121replaced by the label. When the format starts with @samp{~}, this
4122@samp{~} will only be inserted when the character before point is
4123@emph{not} a whitespace.
4124
4125@item @var{context-method}
4126Indication on how to find the short context.
4127@itemize @minus
4128@item
4129If @code{nil}, use the text following the @samp{\label@{...@}} macro.
4130@item
4131If @code{t}, use
4132@itemize @minus
4133@item
4134the section heading for section labels.
4135@item
4136text following the @samp{\begin@{...@}} statement of environments (not
4137a good choice for environments like eqnarray or enumerate, where one has
4138several labels in a single environment).
4139@item
4140text after the macro name (starting with the first arg) for
4141macros.
4142@end itemize
4143@item
4144If an integer, use the nth argument of the macro. As a special case,
41451000 means to get text after the last macro argument.
4146@item
4147If a string, use as regexp to search @emph{backward} from the label.
1df7defd 4148Context is then the text following the end of the match. E.g., setting
4009494e
GM
4149this to @samp{\\caption[[@{]} will use the caption in a figure or table
4150environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
4151eqnarrays.
4152@item
4153If any of @code{caption}, @code{item}, @code{eqnarray-like},
4154@code{alignat-like}, this symbol will internally be translated into an
4155appropriate regexp (see also the variable
4156@code{reftex-default-context-regexps}).
4157@item
4158If a function, call this function with the name of the environment/macro
4159as argument. On call, point will be just after the @code{\label} macro.
4160The function is expected to return a suitable context string. It should
4161throw an exception (error) when failing to find context. As an example,
4162here is a function returning the 10 chars following the label macro as
4163context:
4164
4165@example
4166(defun my-context-function (env-or-mac)
4167 (if (> (point-max) (+ 10 (point)))
4168 (buffer-substring (point) (+ 10 (point)))
4169 (error "Buffer too small")))
4170@end example
4171@end itemize
4172
4f595e15 4173Label context is used in two ways by @RefTeX{}: For display in the label
4009494e
GM
4174menu, and to derive a label string. If you want to use a different
4175method for each of these, specify them as a dotted pair.
1df7defd 4176E.g., @code{(nil . t)} uses the text after the label (@code{nil}) for
4009494e
GM
4177display, and text from the default position (@code{t}) to derive a label
4178string. This is actually used for section labels.
4179
4180@item @var{magic-word-list}
4181List of magic words which identify a reference to be of this type. If
4182the word before point is equal to one of these words when calling
4183@code{reftex-reference}, the label list offered will be automatically
4184restricted to labels of the correct type. If the first element of this
4f595e15 4185word list is the symbol `regexp', the strings are interpreted as regular
4009494e
GM
4186expressions.
4187
4188@item @var{toc-level}
4189The integer level at which this environment should be added to the table
4190of contents. See also @code{reftex-section-levels}. A positive value
4191will number the entries mixed with the sectioning commands of the same
4192level. A negative value will make unnumbered entries. Useful only for
4193theorem-like environments which structure the document. Will be ignored
4194for macros. When omitted or @code{nil}, no TOC entries will be
4195made.
4196@end table
4197
4198If the type indicator characters of two or more entries are the same,
4f595e15 4199@RefTeX{} will use
4009494e
GM
4200@itemize @minus
4201@item
4202the first non-@code{nil} format and prefix
4203@item
4204the magic words of all involved entries.
4205@end itemize
4206
4207Any list entry may also be a symbol. If that has an association in
4208@code{reftex-label-alist-builtin}, the @code{cddr} of that association is
4209spliced into the list. However, builtin defaults should normally be set
4210with the variable @code{reftex-default-label-alist-entries}.
4211@end defopt
4212
4213@defopt reftex-section-prefixes
4214Prefixes for section labels. When the label prefix given in an entry in
4215@code{reftex-label-alist} contains @samp{%S}, this list is used to
4216determine the correct prefix string depending on the current section
4217level. The list is an alist, with each entry of the form
4218@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
4219names like @samp{chapter}, integer section levels (as given in
4220@code{reftex-section-levels}), and @code{t} for the default.
4221@end defopt
4222
4223@defopt reftex-default-context-regexps
4224Alist with default regular expressions for finding context. The emacs
4225lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
f99f1641 4226to calculate the final regular expression, so @samp{%s} will be
4009494e
GM
4227replaced with the environment or macro.
4228@end defopt
4229
4230@defopt reftex-trust-label-prefix
4231Non-@code{nil} means, trust the label prefix when determining label type.
4232It is customary to use special label prefixes to distinguish different label
4f595e15 4233types. The label prefixes have no syntactic meaning in @LaTeX{} (unless
4009494e
GM
4234special packages like fancyref) are being used. RefTeX can and by
4235default does parse around each label to detect the correct label type,
4236but this process can be slow when a document contains thousands of
4237labels. If you use label prefixes consistently, you may speed up
4238document parsing by setting this variable to a non-nil value. RefTeX
4239will then compare the label prefix with the prefixes found in
4240`reftex-label-alist' and derive the correct label type in this way.
4241Possible values for this option are:
4242
4243@example
4244t @r{This means to trust any label prefixes found.}
4245regexp @r{If a regexp, only prefixes matched by the regexp are trusted.}
4246list @r{List of accepted prefixes, as strings. The colon is part of}
1df7defd 4247 @r{the prefix, e.g., ("fn:" "eqn:" "item:").}
4009494e
GM
4248nil @r{Never trust a label prefix.}
4249@end example
4250The only disadvantage of using this feature is that the label context
4251displayed in the label selection buffer along with each label is
4252simply some text after the label definition. This is no problem if you
1df7defd 4253place labels keeping this in mind (e.g., @i{before} the equation, @i{at
4009494e
GM
4254the beginning} of a fig/tab caption ...). Anyway, it is probably best
4255to use the regexp or the list value types to fine-tune this feature.
4256For example, if your document contains thousands of footnotes with
4257labels fn:xxx, you may want to set this variable to the value "^fn:$" or
4258("fn:"). Then RefTeX will still do extensive parsing for any
4259non-footnote labels.
4260@end defopt
4261
6d1962b3 4262@node Options (Creating Labels)
4009494e
GM
4263@section Creating Labels
4264@cindex Options, creating labels
4265@cindex Creating labels, options
4266
4267@defopt reftex-insert-label-flags
4268Flags governing label insertion. The value has the form
4269
4270@example
4271(@var{derive} @var{prompt})
4272@end example
4273
4f595e15 4274If @var{derive} is @code{t}, @RefTeX{} will try to derive a sensible
4009494e
GM
4275label from context. A section label for example will be derived from
4276the section heading. The conversion of the context to a valid label is
4277governed by the specifications given in
4278@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
4279the default label will consist of the prefix and a unique number, like
4280@samp{eq:23}.
4281
4282If @var{prompt} is @code{t}, the user will be prompted for a label
4283string. When @var{prompt} is @code{nil}, the default label will be
4284inserted without query.
4285
4286So the combination of @var{derive} and @var{prompt} controls label
4287insertion. Here is a table describing all four possibilities:
4288
4289@example
4290@group
4291@var{derive} @var{prompt} @var{action}
4292-----------------------------------------------------------
4293nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
4294nil t @r{Prompt for label.}
4295t nil @r{Derive a label from context and insert. No query.}
4296t t @r{Derive a label from context, prompt for confirmation.}
4297@end group
4298@end example
4299
4300Each flag may be set to @code{t}, @code{nil}, or a string of label type
4301letters indicating the label types for which it should be true. Thus,
4302the combination may be set differently for each label type. The default
4303settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
4304headings (with confirmation). Prompt for figure and table labels. Use
4305simple labels without confirmation for everything else.
4306
4307The available label types are: @code{s} (section), @code{f} (figure),
4308@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4309(footnote), @code{N} (endnote) plus any definitions in
4310@code{reftex-label-alist}.
4311@end defopt
4312
4313@deffn Hook reftex-format-label-function
4314If non-@code{nil}, should be a function which produces the string to
4315insert as a label definition. The function will be called with two
4316arguments, the @var{label} and the @var{default-format} (usually
4317@samp{\label@{%s@}}). It should return the string to insert into the
4318buffer.
4319@end deffn
4320
4321@deffn Hook reftex-string-to-label-function
4322Function to turn an arbitrary string into a valid label.
4f595e15 4323@RefTeX{}'s default function uses the variable
4009494e
GM
4324@code{reftex-derive-label-parameters}.
4325@end deffn
4326
4327@deffn Hook reftex-translate-to-ascii-function
4328Filter function which will process a context string before it is used to
4329derive a label from it. The intended application is to convert ISO or
4330Mule characters into something valid in labels. The default function
4331@code{reftex-latin1-to-ascii} removes the accents from Latin-1
4332characters. X-Symbol (>=2.6) sets this variable to the much more
4333general @code{x-symbol-translate-to-ascii}.
4334@end deffn
4335
4336@defopt reftex-derive-label-parameters
4337Parameters for converting a string into a label. This variable is a
4338list of the following items:
4339@table @asis
4340@item @var{nwords}
4341Number of words to use.
4342@item @var{maxchar}
4343Maximum number of characters in a label string.
4344@item @var{invalid}
4345@code{nil}: Throw away any words containing characters invalid in labels.@*
4346@code{t}: Throw away only the invalid characters, not the whole word.
4347@item @var{abbrev}
4348@code{nil}: Never abbreviate words.@*
4349@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
4350@code{1}: Abbreviate words if necessary to shorten label string.
4351@item @var{separator}
4352String separating different words in the label.
4353@item @var{ignorewords}
4354List of words which should not be part of labels.
4355@item @var{downcase}
4356@code{t}: Downcase words before putting them into the label.@*
4357@end table
4358@end defopt
4359
4360@defopt reftex-label-illegal-re
4361Regexp matching characters not valid in labels.
4362@end defopt
4363
4364@defopt reftex-abbrev-parameters
4365Parameters for abbreviation of words. A list of four parameters.
4366@table @asis
4367@item @var{min-chars}
4368Minimum number of characters remaining after abbreviation.
4369@item @var{min-kill}
4370Minimum number of characters to remove when abbreviating words.
4371@item @var{before}
4372Character class before abbrev point in word.
4373@item @var{after}
4374Character class after abbrev point in word.
4375@end table
4376@end defopt
4377
6d1962b3 4378@node Options (Referencing Labels)
4009494e
GM
4379@section Referencing Labels
4380@cindex Options, referencing labels
4381@cindex Referencing labels, options
4382
4383@defopt reftex-label-menu-flags
4384List of flags governing the label menu makeup. The flags are:
4385@table @asis
4386@item @var{table-of-contents}
4387Show the labels embedded in a table of context.
4388@item @var{section-numbers}
4389Include section numbers (like 4.1.3) in table of contents.
4390@item @var{counters}
4391Show counters. This just numbers the labels in the menu.
4392@item @var{no-context}
4393Non-@code{nil} means do @emph{not} show the short context.
4394@item @var{follow}
4395Follow full context in other window.
4396@item @var{show-commented}
4397Show labels from regions which are commented out.
4398@item @var{match-everywhere}
4399Obsolete flag.
4400@item @var{show-files}
4401Show begin and end of included files.
4402@end table
4403
4404Each of these flags can be set to @code{t} or @code{nil}, or to a string
4405of type letters indicating the label types for which it should be true.
4406These strings work like character classes in regular expressions. Thus,
4407setting one of the flags to @samp{"sf"} makes the flag true for section
4408and figure labels, @code{nil} for everything else. Setting it to
4409@samp{"^sf"} makes it the other way round.
4410
4411The available label types are: @code{s} (section), @code{f} (figure),
4412@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
4413(footnote), plus any definitions in @code{reftex-label-alist}.
4414
f99f1641 4415Most options can also be switched from the label menu itself, so if you
4009494e
GM
4416decide here to not have a table of contents in the label menu, you can
4417still get one interactively during selection from the label menu.
4418@end defopt
4419
4420@defopt reftex-multiref-punctuation
4421Punctuation strings for multiple references. When marking is used in
4422the selection buffer to select several references, this variable
4423associates the 3 marking characters @samp{,-+} with prefix strings to be
4424inserted into the buffer before the corresponding @code{\ref} macro.
4425This is used to string together whole reference sets, like
4426@samp{eqs. 1,2,3-5,6 and 7} in a single call to
4427@code{reftex-reference}.
4428@end defopt
4429
4f595e15
RA
4430@defopt reftex-ref-style-alist
4431Alist of reference styles. Each element is a list of the style name,
4432the name of the @LaTeX{} package associated with the style or @code{t}
4433for any package, and an alist of macros where the first entry of each
4434item is the reference macro and the second a key for selecting the macro
4435when the macro type is being prompted for. (See also
4436@code{reftex-ref-macro-prompt}.) The keys, represented as characters,
4437have to be unique.
4009494e
GM
4438@end defopt
4439
4f595e15
RA
4440@defopt reftex-ref-style-default-list
4441List of reference styles to be activated by default. The order is
4442significant and controls the order in which macros can be cycled in the
4443buffer for selecting a label. The entries in the list have to match the
4444respective reference style names used in the variable
4445@code{reftex-ref-style-alist}.
4446@end defopt
4447
4448@defopt reftex-ref-macro-prompt
4449Controls if @code{reftex-reference} prompts for the reference macro.
4009494e
GM
4450@end defopt
4451
4452@deffn Hook reftex-format-ref-function
4453If non-@code{nil}, should be a function which produces the string to
4454insert as a reference. Note that the insertion format can also be
4455changed with @code{reftex-label-alist}. This hook also is used by the
1df7defd 4456special commands to insert, e.g., @code{\vref} and @code{\fref}
4f595e15
RA
4457references, so even if you set this, your setting will be ignored by the
4458special commands. The function will be called with three arguments, the
4459@var{label}, the @var{default format} which normally is
4460@samp{~\ref@{%s@}} and the @var{reference style}. The function should
4461return the string to insert into the buffer.
4009494e
GM
4462@end deffn
4463
4464@defopt reftex-level-indent
4465Number of spaces to be used for indentation per section level.
4466@end defopt
4467
4468@defopt reftex-guess-label-type
4469Non-@code{nil} means, @code{reftex-reference} will try to guess the
4f595e15 4470label type. To do that, @RefTeX{} will look at the word before the
4009494e 4471cursor and compare it with the magic words given in
4f595e15 4472@code{reftex-label-alist}. When it finds a match, @RefTeX{} will
f99f1641 4473immediately offer the correct label menu; otherwise it will prompt you
4f595e15 4474for a label type. If you set this variable to @code{nil}, @RefTeX{}
4009494e
GM
4475will always prompt for a label type.
4476@end defopt
4477
4478@deffn {Normal Hook} reftex-display-copied-context-hook
4479Normal Hook which is run before context is displayed anywhere. Designed
4480for @w{@code{X-Symbol}}, but may have other uses as well.
4481@end deffn
4482
4483@deffn Hook reftex-pre-refontification-functions
4484@code{X-Symbol} specific hook. Probably not useful for other purposes.
4485The functions get two arguments, the buffer from where the command
4486started and a symbol indicating in what context the hook is
4487called.
4488@end deffn
4489
4490@deffn {Normal Hook} reftex-select-label-mode-hook
4491Normal hook which is run when a selection buffer enters
4492@code{reftex-select-label-mode}.
4493@end deffn
4494
4495@deffn Keymap reftex-select-label-map
4496The keymap which is active in the labels selection process
4497(@pxref{Referencing Labels}).
4498@end deffn
4499
6d1962b3 4500@node Options (Creating Citations)
4009494e
GM
4501@section Creating Citations
4502@cindex Options, creating citations
4503@cindex Creating citations, options
4504
4505@defopt reftex-bibliography-commands
4f595e15 4506@LaTeX{} commands which specify the @BibTeX{} databases to use with the document.
4009494e
GM
4507@end defopt
4508
4509@defopt reftex-bibfile-ignore-regexps
4510List of regular expressions to exclude files in
4511@code{\\bibliography@{..@}}. File names matched by any of these regexps
4512will not be parsed. Intended for files which contain only
4513@code{@@string} macro definitions and the like, which are ignored by
4f595e15 4514@RefTeX{} anyway.
4009494e
GM
4515@end defopt
4516
4517@defopt reftex-default-bibliography
4f595e15 4518List of @BibTeX{} database files which should be used if none are specified.
4009494e
GM
4519When @code{reftex-citation} is called from a document with neither
4520a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
4f595e15
RA
4521environment, @RefTeX{} will scan these files instead. Intended for
4522using @code{reftex-citation} in non-@LaTeX{} files. The files will be
4009494e
GM
4523searched along the BIBINPUTS or TEXBIB path.
4524@end defopt
4525
4526@defopt reftex-sort-bibtex-matches
4f595e15 4527Sorting of the entries found in @BibTeX{} databases by reftex-citation.
4009494e
GM
4528Possible values:
4529@example
4530nil @r{Do not sort entries.}
4531author @r{Sort entries by author name.}
4532year @r{Sort entries by increasing year.}
4533reverse-year @r{Sort entries by decreasing year.}
4534@end example
4535@end defopt
4536
4537@defopt reftex-cite-format
4538The format of citations to be inserted into the buffer. It can be a
4539string, an alist or a symbol. In the simplest case this is just the string
4540@samp{\cite@{%l@}}, which is also the default. See the definition of
4541@code{reftex-cite-format-builtin} for more complex examples.
4542
4543If @code{reftex-cite-format} is a string, it will be used as the format.
4544In the format, the following percent escapes will be expanded.
4545
4546@table @code
4547@item %l
4f595e15 4548The @BibTeX{} label of the citation.
4009494e
GM
4549@item %a
4550List of author names, see also @code{reftex-cite-punctuation}.
4551@item %2a
4552Like %a, but abbreviate more than 2 authors like Jones et al.
4553@item %A
4554First author name only.
4555@item %e
4556Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
4557@samp{%E} work a well).
4558@end table
4559
4f595e15 4560It is also possible to access all other @BibTeX{} database fields:
4009494e
GM
4561
4562@example
4563%b booktitle %c chapter %d edition %h howpublished
4564%i institution %j journal %k key %m month
4565%n number %o organization %p pages %P first page
4566%r address %s school %u publisher %t title
4567%v volume %y year
4568%B booktitle, abbreviated %T title, abbreviated
4569@end example
4570
4571@noindent
4572Usually, only @samp{%l} is needed. The other stuff is mainly for the
4573echo area display, and for @code{(setq reftex-comment-citations t)}.
4574
4575@samp{%<} as a special operator kills punctuation and space around it
4576after the string has been formatted.
4577
4578A pair of square brackets indicates an optional argument, and RefTeX
4579will prompt for the values of these arguments.
4580
4f595e15 4581Beware that all this only works with @BibTeX{} database files. When
4009494e
GM
4582citations are made from the @code{\bibitems} in an explicit
4583@code{thebibliography} environment, only @samp{%l} is available.
4584
4585If @code{reftex-cite-format} is an alist of characters and strings, the
4586user will be prompted for a character to select one of the possible
4587format strings.
4588
4589In order to configure this variable, you can either set
4590@code{reftex-cite-format} directly yourself or set it to the
4591@emph{symbol} of one of the predefined styles. The predefined symbols
4592are those which have an association in the constant
4593@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
4594'natbib)}.
4595@end defopt
4596
4597@deffn Hook reftex-format-cite-function
4598If non-@code{nil}, should be a function which produces the string to
4599insert as a citation. Note that the citation format can also be changed
4600with the variable @code{reftex-cite-format}. The function will be
4601called with two arguments, the @var{citation-key} and the
4602@var{default-format} (taken from @code{reftex-cite-format}). It should
4603return the string to insert into the buffer.
4604@end deffn
4605
4606@defopt reftex-cite-prompt-optional-args
4607Non-@code{nil} means, prompt for empty optional arguments in cite macros.
4608When an entry in @code{reftex-cite-format} ist given with square brackets to
4609indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
4610prompt for values. Possible values are:
4611@example
4612nil @r{Never prompt for optional arguments}
4613t @r{Always prompt}
4614maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example
4615Unnecessary empty optional arguments are removed before insertion into
4616the buffer. See @code{reftex-cite-cleanup-optional-args}.
4617@end defopt
4618
4619@defopt reftex-cite-cleanup-optional-args
4620Non-@code{nil} means, remove empty optional arguments from cite macros
4621if possible.
4622@end defopt
4623
4624@defopt reftex-comment-citations
4625Non-@code{nil} means add a comment for each citation describing the full
4626entry. The comment is formatted according to
4627@code{reftex-cite-comment-format}.
4628@end defopt
4629
4630@defopt reftex-cite-comment-format
4631Citation format used for commented citations. Must @emph{not} contain
4632@samp{%l}. See the variable @code{reftex-cite-format} for possible
4633percent escapes.
4634@end defopt
4635
4636@defopt reftex-cite-punctuation
4637Punctuation for formatting of name lists in citations. This is a list
4638of 3 strings.
4639@enumerate
4640@item
4641normal names separator, like @samp{, } in Jones, Brown and Miller
4642@item
4643final names separator, like @samp{ and } in Jones, Brown and Miller
4644@item
4645The @samp{et al.} string, like @samp{ @{\it et al.@}} in
4646Jones @{\it et al.@}
4647@end enumerate
4648@end defopt
4649
4650@deffn {Normal Hook} reftex-select-bib-mode-hook
4651Normal hook which is run when a selection buffer enters
4652@code{reftex-select-bib-mode}.
4653@end deffn
4654
4655@deffn Keymap reftex-select-bib-map
4656The keymap which is active in the citation-key selection process
4657(@pxref{Creating Citations}).
4658@end deffn
4659
4f595e15
RA
4660@defopt reftex-cite-key-separator
4661String used to separate several keys in a single @samp{\\cite} macro.
4662Per default this is @samp{","} but if you often have to deal with a lot
4663of entries and need to break the macro across several lines you might
4664want to change it to @samp{", "}.
4665@end defopt
4666
4667@defopt reftex-create-bibtex-header
4668Header to insert in BibTeX files generated by
4669@code{reftex-create-bibtex-file}.
4670@end defopt
4671
4672@defopt reftex-create-bibtex-footer
4673Footer to insert in BibTeX files generated by
4674@code{reftex-create-bibtex-file}.
4675@end defopt
4676
4677
6d1962b3 4678@node Options (Index Support)
4009494e
GM
4679@section Index Support
4680@cindex Options, Index support
4681@cindex Index support, options
4682
4683@defopt reftex-support-index
4684Non-@code{nil} means, index entries are parsed as well. Index support
4685is resource intensive and the internal structure holding the parsed
4686information can become quite big. Therefore it can be turned off. When
4687this is @code{nil} and you execute a command which requires index
4688support, you will be asked for confirmation to turn it on and rescan the
4689document.
4690@end defopt
4691
4692@defopt reftex-index-special-chars
4693List of special characters in index entries, given as strings. These
4694correspond to the @code{MakeIndex} keywords
4695@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
4696@end defopt
4697
4698@defopt reftex-index-macros
4699List of macros which define index entries. The structure of each entry
4700is
4701@lisp
4702(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat})
4703@end lisp
4704
4705@var{macro} is the macro. Arguments should be denoted by empty braces,
4706as for example in @samp{\index[]@{*@}}. Use square brackets to denote
4707optional arguments. The star marks where the index key is.
4708
4709@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
4710are reserved for the default index and the glossary. Other indices can
4711be defined as well. If this is an integer, the Nth argument of the
4712macro holds the index tag.
4713
4714@var{key} is a character which is used to identify the macro for input
4715with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
4716reserved for default index and glossary.
4717
4718@var{prefix} can be a prefix which is added to the @var{key} part of the
4719index entry. If you have a macro
4720@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
4721should be @samp{Molecules!}.
4722
4723@var{exclude} can be a function. If this function exists and returns a
4724non-@code{nil} value, the index entry at point is ignored. This was
4725implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
4f595e15 4726in the @LaTeX{}2e @code{index} package.
4009494e
GM
4727
4728@var{repeat}, if non-@code{nil}, means the index macro does not typeset
4729the entry in the text, so that the text has to be repeated outside the
4730index macro. Needed for @code{reftex-index-selection-or-word} and for
4731indexing from the phrase buffer.
4732
4733The final entry may also be a symbol. It must have an association in
4734the variable @code{reftex-index-macros-builtin} to specify the main
4735indexing package you are using. Valid values are currently
4736@example
f99f1641 4737default @r{The @LaTeX{} default; unnecessary to specify this one}
4009494e
GM
4738multind @r{The multind.sty package}
4739index @r{The index.sty package}
4740index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
f99f1641 4741 @r{Should not be used; only for old documents}
4009494e 4742@end example
4f595e15
RA
4743Note that @AUCTeX{} sets these things internally for @RefTeX{} as well,
4744so with a sufficiently new version of @AUCTeX{}, you should not set the
4009494e
GM
4745package here.
4746@end defopt
4747
4748@defopt reftex-index-default-macro
4749The default index macro for @code{reftex-index-selection-or-word}.
4750This is a list with @code{(@var{macro-key} @var{default-tag})}.
4751
f99f1641 4752@var{macro-key} is a character identifying an index macro; see
4009494e
GM
4753@code{reftex-index-macros}.
4754
4755@var{default-tag} is the tag to be used if the macro requires a
4756@var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
4f595e15 4757@RefTeX{} will ask for it. When this is the empty string and the
4009494e
GM
4758TAG argument of the index macro is optional, the TAG argument will be
4759omitted.
4760@end defopt
4761
4762@defopt reftex-index-default-tag
4763Default index tag. When working with multiple indexes, RefTeX queries
4764for an index tag when creating index entries or displaying a specific
4765index. This variable controls the default offered for these queries.
4766The default can be selected with @key{RET} during selection or
4767completion. Valid values of this variable are:
4768@example
4769nil @r{Do not provide a default index}
1df7defd 4770"tag" @r{The default index tag given as a string, e.g., "idx"}
4009494e
GM
4771last @r{The last used index tag will be offered as default}
4772@end example
4773@end defopt
4774
4775@defopt reftex-index-math-format
4776Format of index entries when copied from inside math mode. When
4f595e15 4777@code{reftex-index-selection-or-word} is executed inside @TeX{} math mode,
4009494e
GM
4778the index key copied from the buffer is processed with this format
4779string through the @code{format} function. This can be used to add the
1df7defd 4780math delimiters (e.g., @samp{$}) to the string. Requires the
4f595e15 4781@file{texmathp.el} library which is part of @AUCTeX{}.
4009494e
GM
4782@end defopt
4783
4784@defopt reftex-index-phrase-file-extension
4785File extension for the index phrase file. This extension will be added
4786to the base name of the master file.
4787@end defopt
4788
4789@defopt reftex-index-phrases-logical-and-regexp
4790Regexp matching the @samp{and} operator for index arguments in phrases
4791file. When several index arguments in a phrase line are separated by
4792this operator, each part will generate an index macro. So each match of
4793the search phrase will produce @emph{several} different index entries.
4794Make sure this does no match things which are not separators. This
4795logical @samp{and} has higher priority than the logical @samp{or}
4796specified in @code{reftex-index-phrases-logical-or-regexp}.
4797@end defopt
4798
4799@defopt reftex-index-phrases-logical-or-regexp
4800Regexp matching the @samp{or} operator for index arguments in phrases
4801file. When several index arguments in a phrase line are separated by
4802this operator, the user will be asked to select one of them at each
4803match of the search phrase. The first index arg will be the default. A
4804number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make
4805sure this does no match things which are not separators. The logical
4806@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
4807has higher priority than this logical @samp{or}.
4808@end defopt
4809
4810@defopt reftex-index-phrases-search-whole-words
4811Non-@code{nil} means phrases search will look for whole words, not subwords.
4812This works by requiring word boundaries at the beginning and end of
4813the search string. When the search phrase already has a non-word-char
4814at one of these points, no word boundary is required there.
4815@end defopt
4816
4817@defopt reftex-index-phrases-case-fold-search
4818Non-@code{nil} means, searching for index phrases will ignore
4819case.
4820@end defopt
4821
4822@defopt reftex-index-verify-function
4823A function which is called at each match during global indexing.
4824If the function returns nil, the current match is skipped.
4825@end defopt
4826
4827@defopt reftex-index-phrases-skip-indexed-matches
4828Non-@code{nil} means, skip matches which appear to be indexed already.
4829When doing global indexing from the phrases buffer, searches for some
4830phrases may match at places where that phrase was already indexed. In
4831particular when indexing an already processed document again, this
4832will even be the norm. When this variable is non-@code{nil},
4f595e15 4833@RefTeX{} checks if the match is an index macro argument, or if an
4009494e
GM
4834index macro is directly before or after the phrase. If that is the
4835case, that match will be ignored.
4836@end defopt
4837
4838@defopt reftex-index-phrases-wrap-long-lines
4839Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
f99f1641 4840Inserting indexing commands in a line makes the line longer, often
4009494e
GM
4841so long that it does not fit onto the screen. When this variable is
4842non-@code{nil}, newlines will be added as necessary before and/or after the
4843indexing command to keep lines short. However, the matched text
4844phrase and its index command will always end up on a single line.
4845@end defopt
4846
4847@defopt reftex-index-phrases-sort-prefers-entry
4848Non-@code{nil} means when sorting phrase lines, the explicit index entry
4849is used. Phrase lines in the phrases buffer contain a search phrase, and
4850sorting is normally based on these. Some phrase lines also have
4851an explicit index argument specified. When this variable is
4852non-@code{nil}, the index argument will be used for sorting.
4853@end defopt
4854
4855@defopt reftex-index-phrases-sort-in-blocks
4856Non-@code{nil} means, empty and comment lines separate phrase buffer
4857into blocks. Sorting will then preserve blocks, so that lines are
4858re-arranged only within blocks.
4859@end defopt
4860
4861@defopt reftex-index-phrases-map
4862Keymap for the Index Phrases buffer.
4863@end defopt
4864
4865@defopt reftex-index-phrases-mode-hook
4866Normal hook which is run when a buffer is put into
4867@code{reftex-index-phrases-mode}.
4868@end defopt
4869
4870@defopt reftex-index-section-letters
4871The letters which denote sections in the index. Usually these are all
4872capital letters. Don't use any downcase letters. Order is not
4873significant, the index will be sorted by whatever the sort function
4f595e15 4874thinks is correct. In addition to these letters, @RefTeX{} will
4009494e
GM
4875create a group @samp{!} which contains all entries sorted below the
4876lowest specified letter. In the @file{*Index*} buffer, pressing any of
4877these capital letters or @kbd{!} will jump to that section.
4878@end defopt
4879
4880@defopt reftex-index-include-context
4881Non-@code{nil} means, display the index definition context in the
4882@file{*Index*} buffer. This flag may also be toggled from the
4883@file{*Index*} buffer with the @kbd{c} key.
4884@end defopt
4885
4886@defopt reftex-index-follow-mode
4887Non-@code{nil} means, point in @file{*Index*} buffer will cause other
4888window to follow. The other window will show the corresponding part of
4889the document. This flag can be toggled from within the @file{*Index*}
4890buffer with the @kbd{f} key.
4891@end defopt
4892
4893@deffn Keymap reftex-index-map
4894The keymap which is active in the @file{*Index*} buffer
4895(@pxref{Index Support}).
4896@end deffn
4897
6d1962b3 4898@node Options (Viewing Cross-References)
4009494e
GM
4899@section Viewing Cross-References
4900@cindex Options, viewing cross-references
4901@cindex Viewing cross-references, options
4902
4903@defopt reftex-view-crossref-extra
4904Macros which can be used for the display of cross references.
4905This is used when `reftex-view-crossref' is called with point in an
4906argument of a macro. Note that crossref viewing for citations,
4907references (both ways) and index entries is hard-coded. This variable
4908is only to configure additional structures for which crossreference
4909viewing can be useful. Each entry has the structure
4910@example
4911(@var{macro-re} @var{search-re} @var{highlight}).
4912@end example
4913@var{macro-re} is matched against the macro. @var{search-re} is the
4914regexp used to search for cross references. @samp{%s} in this regexp is
4915replaced with the macro argument at point. @var{highlight} is an
4916integer indicating which subgroup of the match should be highlighted.
4917@end defopt
4918
4919@defopt reftex-auto-view-crossref
4920Non-@code{nil} means, initially turn automatic viewing of crossref info
4921on. Automatic viewing of crossref info normally uses the echo area.
4922Whenever point is idle for more than @code{reftex-idle-time} seconds on
4923the argument of a @code{\ref} or @code{\cite} macro, and no other
4924message is being displayed, the echo area will display information about
4925that cross reference. You can also set the variable to the symbol
4926@code{window}. In this case a small temporary window is used for the
4927display. This feature can be turned on and off from the menu
4928(Ref->Options).
4929@end defopt
4930
4931@defopt reftex-idle-time
4932Time (secs) Emacs has to be idle before automatic crossref display
4933or toc recentering is done.
4934@end defopt
4935
4936@defopt reftex-cite-view-format
4937Citation format used to display citation info in the message area. See
4938the variable @code{reftex-cite-format} for possible percent
4939escapes.
4940@end defopt
4941
4942@defopt reftex-revisit-to-echo
4943Non-@code{nil} means, automatic citation display will revisit files if
4944necessary. When nil, citation display in echo area will only be active
4945for cached echo strings (see @code{reftex-cache-cite-echo}), or for
4f595e15 4946@BibTeX{} database files which are already visited by a live associated
4009494e
GM
4947buffers.
4948@end defopt
4949
4950@defopt reftex-cache-cite-echo
4951Non-@code{nil} means, the information displayed in the echo area for
4952cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
4953saved along with the parsing information. The cache survives document
4954scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
4955@end defopt
4956
6d1962b3 4957@node Options (Finding Files)
4009494e
GM
4958@section Finding Files
4959@cindex Options, Finding Files
4960@cindex Finding files, options
4961
4962@defopt reftex-texpath-environment-variables
4f595e15 4963List of specifications how to retrieve the search path for @TeX{} files.
4009494e
GM
4964Several entries are possible.
4965@itemize @minus
4966@item
4967If an element is the name of an environment variable, its content is
4968used.
4969@item
4970If an element starts with an exclamation mark, it is used as a command
4971to retrieve the path. A typical command with the kpathsearch library
4972would be @w{@code{"!kpsewhich -show-path=.tex"}}.
4973@item
4974Otherwise the element itself is interpreted as a path.
4975@end itemize
4976Multiple directories can be separated by the system dependent
4977@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4978be expanded recursively. See also @code{reftex-use-external-file-finders}.
4979@end defopt
4980
4981@defopt reftex-bibpath-environment-variables
4f595e15 4982List of specifications how to retrieve the search path for @BibTeX{}
4009494e
GM
4983files. Several entries are possible.
4984@itemize @minus
4985@item
4986If an element is the name of an environment variable, its content is
4987used.
4988@item
4989If an element starts with an exclamation mark, it is used as a command
4990to retrieve the path. A typical command with the kpathsearch library
4991would be @w{@code{"!kpsewhich -show-path=.bib"}}.
4992@item
4993Otherwise the element itself is interpreted as a path.
4994@end itemize
4995Multiple directories can be separated by the system dependent
4996@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
4997be expanded recursively. See also @code{reftex-use-external-file-finders}.
4998@end defopt
4999
5000@defopt reftex-file-extensions
5001Association list with file extensions for different file types.
5002This is a list of items, each item is like:
5003@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
5004@example
5005@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
5006@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
5007@var{other-ext}: @r{Any number of other valid extensions for this file type.}
5008@end example
5009When a files is searched and it does not have any of the valid extensions,
5010we try the default extension first, and then the naked file name.
5011@end defopt
5012
5013@defopt reftex-search-unrecursed-path-first
5014Non-@code{nil} means, search all specified directories before trying
5015recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
5016then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
5017option is @code{nil}, the subdirectories of @samp{./} are searched
f99f1641 5018before @samp{/tex/}. This is mainly for speed; most of the time the
4009494e 5019recursive path is for the system files and not for the user files. Set
4f595e15 5020this to @code{nil} if the default makes @RefTeX{} finding files with
4009494e
GM
5021equal names in wrong sequence.
5022@end defopt
5023
5024@defopt reftex-use-external-file-finders
5025Non-@code{nil} means, use external programs to find files. Normally,
4f595e15
RA
5026@RefTeX{} searches the paths given in the environment variables
5027@code{TEXINPUTS} and @code{BIBINPUTS} to find @TeX{} files and @BibTeX{}
4009494e
GM
5028database files. With this option turned on, it calls an external
5029program specified in the option @code{reftex-external-file-finders}
5030instead. As a side effect, the variables
5031@code{reftex-texpath-environment-variables} and
5032@code{reftex-bibpath-environment-variables} will be ignored.
5033@end defopt
5034
5035@defopt reftex-external-file-finders
5036Association list with external programs to call for finding files. Each
5037entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
5038@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
5039string containing the external program to use with any arguments.
5040@code{%f} will be replaced by the name of the file to be found. Note
5041that these commands will be executed directly, not via a shell. Only
5042relevant when @code{reftex-use-external-file-finders} is
5043non-@code{nil}.
5044@end defopt
5045
5046@page
6d1962b3 5047@node Options (Optimizations)
4009494e
GM
5048@section Optimizations
5049@cindex Options, optimizations
5050@cindex Optimizations, options
5051
5052@defopt reftex-keep-temporary-buffers
5053Non-@code{nil} means, keep buffers created for parsing and lookup.
4f595e15 5054@RefTeX{} sometimes needs to visit files related to the current
4009494e
GM
5055document. We distinguish files visited for
5056@table @asis
5057@item PARSING
5058Parts of a multifile document loaded when (re)-parsing the
5059document.
5060@item LOOKUP
4f595e15 5061@BibTeX{} database files and @TeX{} files loaded to find a reference, to
4009494e
GM
5062display label context, etc.
5063@end table
5064The created buffers can be kept for later use, or be thrown away
5065immediately after use, depending on the value of this variable:
5066
5067@table @code
5068@item nil
5069Throw away as much as possible.
5070@item t
5071Keep everything.
5072@item 1
5073Throw away buffers created for parsing, but keep the ones created for
5074lookup.
5075@end table
5076
5077If a buffer is to be kept, the file is visited normally (which is
5078potentially slow but will happen only once). If a buffer is to be thrown
5079away, the initialization of the buffer depends upon the variable
5080@code{reftex-initialize-temporary-buffers}.
5081@end defopt
5082
5083@defopt reftex-initialize-temporary-buffers
5084Non-@code{nil} means do initializations even when visiting file
4f595e15 5085temporarily. When @code{nil}, @RefTeX{} may turn off find-file hooks and
4009494e
GM
5086other stuff to briefly visit a file. When @code{t}, the full default
5087initializations are done (@code{find-file-hook} etc.). Instead of
5088@code{t} or @code{nil}, this variable may also be a list of hook
5089functions to do a minimal initialization.
5090@end defopt
5091
5092@defopt reftex-no-include-regexps
5093List of regular expressions to exclude certain input files from parsing.
5094If the name of a file included via @code{\include} or @code{\input} is
5095matched by any of the regular expressions in this list, that file is not
4f595e15 5096parsed by @RefTeX{}.
4009494e
GM
5097@end defopt
5098
5099@defopt reftex-enable-partial-scans
5100Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
4f595e15 5101Re-parsing is normally requested with a @kbd{C-u} prefix to many @RefTeX{}
4009494e
GM
5102commands, or with the @kbd{r} key in menus. When this option is
5103@code{t} in a multifile document, we will only parse the current buffer,
5104or the file associated with the label or section heading near point in a
5105menu. Requesting re-parsing of an entire multifile document then
5106requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
5107menus.
5108@end defopt
5109
5110@defopt reftex-save-parse-info
5111Non-@code{nil} means, save information gathered with parsing in files.
5112The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
5113used to save the information. When this variable is @code{t},
5114@itemize @minus
5115@item
5116accessing the parsing information for the first time in an editing
5117session will read that file (if available) instead of parsing the
5118document.
5119@item
5120exiting Emacs or killing a buffer in reftex-mode will cause a new
5121version of the file to be written.
5122@end itemize
5123@end defopt
5124
5125@defopt reftex-parse-file-extension
5126File extension for the file in which parser information is stored.
5127This extension is added to the base name of the master file.
5128@end defopt
5129
5130@defopt reftex-allow-automatic-rescan
4f595e15 5131Non-@code{nil} means, @RefTeX{} may rescan the document when this seems
4009494e
GM
5132necessary. Applies (currently) only in rare cases, when a new label
5133cannot be placed with certainty into the internal label list.
5134@end defopt
5135
5136@defopt reftex-use-multiple-selection-buffers
5137Non-@code{nil} means use a separate selection buffer for each label
5138type. These buffers are kept from one selection to the next and need
f99f1641 5139not be created for each use, so the menu generally comes up faster.
4009494e
GM
5140The selection buffers will be erased (and therefore updated)
5141automatically when new labels in its category are added. See the
5142variable @code{reftex-auto-update-selection-buffers}.
5143@end defopt
5144
5145@defopt reftex-auto-update-selection-buffers
5146Non-@code{nil} means, selection buffers will be updated automatically.
5147When a new label is defined with @code{reftex-label}, all selection
5148buffers associated with that label category are emptied, in order to
5149force an update upon next use. When @code{nil}, the buffers are left
5150alone and have to be updated by hand, with the @kbd{g} key from the
5151label selection process. The value of this variable will only have any
5152effect when @code{reftex-use-multiple-selection-buffers} is
5153non-@code{nil}.
5154@end defopt
5155
6d1962b3 5156@node Options (Fontification)
4009494e
GM
5157@section Fontification
5158@cindex Options, fontification
5159@cindex Fontification, options
5160
5161@defopt reftex-use-fonts
5162Non-@code{nil} means, use fonts in label menu and on-the-fly help.
5163Font-lock must be loaded as well to actually get fontified
5164display. After changing this option, a rescan may be necessary to
5165activate it.
5166@end defopt
5167
5168@defopt reftex-refontify-context
5169Non-@code{nil} means, re-fontify the context in the label menu with
5170font-lock. This slightly slows down the creation of the label menu. It
5171is only necessary when you definitely want the context fontified.
5172
5173This option may have 3 different values:
5174@table @code
5175@item nil
5176Never refontify.
5177@item t
5178Always refontify.
5179@item 1
1df7defd 5180Refontify when necessary, e.g., with old versions of the x-symbol
4009494e
GM
5181package.
5182@end table
5183The option is ignored when @code{reftex-use-fonts} is @code{nil}.
5184@end defopt
5185
5186@defopt reftex-highlight-selection
5187Non-@code{nil} means, highlight selected text in selection and
5188@file{*toc*} buffers. Normally, the text near the cursor is the
5189@emph{selected} text, and it is highlighted. This is the entry most
5190keys in the selection and @file{*toc*} buffers act on. However, if you
5191mainly use the mouse to select an item, you may find it nice to have
5192mouse-triggered highlighting @emph{instead} or @emph{as well}. The
5193variable may have one of these values:
5194
5195@example
5196nil @r{No highlighting.}
5197cursor @r{Highlighting is cursor driven.}
5198mouse @r{Highlighting is mouse driven.}
5199both @r{Both cursor and mouse trigger highlighting.}
5200@end example
5201
5202Changing this variable requires to rebuild the selection and *toc*
5203buffers to become effective (keys @kbd{g} or @kbd{r}).
5204@end defopt
5205
5206@defopt reftex-cursor-selected-face
5207Face name to highlight cursor selected item in toc and selection buffers.
5208See also the variable @code{reftex-highlight-selection}.
5209@end defopt
5210@defopt reftex-mouse-selected-face
5211Face name to highlight mouse selected item in toc and selection buffers.
5212See also the variable @code{reftex-highlight-selection}.
5213@end defopt
5214@defopt reftex-file-boundary-face
5215Face name for file boundaries in selection buffer.
5216@end defopt
5217@defopt reftex-label-face
5218Face name for labels in selection buffer.
5219@end defopt
5220@defopt reftex-section-heading-face
5221Face name for section headings in toc and selection buffers.
5222@end defopt
5223@defopt reftex-toc-header-face
5224Face name for the header of a toc buffer.
5225@end defopt
5226@defopt reftex-bib-author-face
5227Face name for author names in bib selection buffer.
5228@end defopt
5229@defopt reftex-bib-year-face
5230Face name for year in bib selection buffer.
5231@end defopt
5232@defopt reftex-bib-title-face
5233Face name for article title in bib selection buffer.
5234@end defopt
5235@defopt reftex-bib-extra-face
5236Face name for bibliographic information in bib selection buffer.
5237@end defopt
5238@defopt reftex-select-mark-face
5239Face name for marked entries in the selection buffers.
5240@end defopt
5241@defopt reftex-index-header-face
5242Face name for the header of an index buffer.
5243@end defopt
5244@defopt reftex-index-section-face
5245Face name for the start of a new letter section in the index.
5246@end defopt
5247@defopt reftex-index-tag-face
5248Face name for index names (for multiple indices).
5249@end defopt
5250@defopt reftex-index-face
5251Face name for index entries.
5252@end defopt
5253
6d1962b3 5254@node Options (Misc)
4009494e
GM
5255@section Miscellaneous
5256@cindex Options, misc
5257
5258@defopt reftex-extra-bindings
5259Non-@code{nil} means, make additional key bindings on startup. These
5260extra bindings are located in the users @samp{C-c letter}
5261map. @xref{Key Bindings}.
5262@end defopt
5263
5264@defopt reftex-plug-into-AUCTeX
4f595e15
RA
5265Plug-in flags for @AUCTeX{} interface. This variable is a list of
52665 boolean flags. When a flag is non-@code{nil}, @RefTeX{}
4009494e
GM
5267will
5268
5269@example
5270- supply labels in new sections and environments (flag 1)
5271- supply arguments for macros like @code{\label} (flag 2)
5272- supply arguments for macros like @code{\ref} (flag 3)
5273- supply arguments for macros like @code{\cite} (flag 4)
5274- supply arguments for macros like @code{\index} (flag 5)
5275@end example
5276
5277You may also set the variable itself to t or nil in order to turn all
5278options on or off, respectively.@*
5279Supplying labels in new sections and environments applies when creating
5280sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
5281Supplying macro arguments applies when you insert such a macro
5282interactively with @kbd{C-c @key{RET}}.@*
4f595e15 5283See the @AUCTeX{} documentation for more information.
4009494e
GM
5284@end defopt
5285
5286@defopt reftex-revisit-to-follow
5287Non-@code{nil} means, follow-mode will revisit files if necessary.
5288When nil, follow-mode will be suspended for stuff in unvisited files.
5289@end defopt
5290
5291@defopt reftex-allow-detached-macro-args
5292Non-@code{nil} means, allow arguments of macros to be detached by
5293whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
5294[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
5295this will be the case even if @code{\bb} is defined with zero or one
5296argument.
5297@end defopt
5298
6d1962b3 5299@node Keymaps and Hooks
4009494e
GM
5300@section Keymaps and Hooks
5301@cindex Keymaps
5302
4f595e15 5303@RefTeX{} has the usual general keymap, load hook and mode hook.
4009494e
GM
5304
5305@deffn Keymap reftex-mode-map
4f595e15 5306The keymap for @RefTeX{} mode.
4009494e
GM
5307@end deffn
5308
5309@deffn {Normal Hook} reftex-load-hook
5310Normal hook which is being run when loading @file{reftex.el}.
5311@end deffn
5312
5313@deffn {Normal Hook} reftex-mode-hook
4f595e15 5314Normal hook which is being run when turning on @RefTeX{} mode.
4009494e
GM
5315@end deffn
5316
4f595e15 5317Furthermore, the four modes used for referencing labels, creating
4009494e
GM
5318citations, the table of contents buffer and the phrases buffer have
5319their own keymaps and mode hooks. See the respective sections. There
5320are many more hooks which are described in the relevant sections about
4f595e15 5321options for a specific part of @RefTeX{}.
4009494e 5322
6d1962b3 5323@node Changes
4009494e
GM
5324@chapter Changes
5325@cindex Changes
5326
4f595e15
RA
5327Here is a list of recent changes to @RefTeX{}.
5328
5329@noindent @b{Version 4.33}
5330
5331@itemize @bullet
5332@item
5333Update to GPLv3.
5334@item
5335Parse files are created in a way that does not interfere with recentf
5336mode.
5337@end itemize
5338
5339@noindent @b{Version 4.32}
5340
5341@itemize @bullet
5342@item
5343First release by @AUCTeX{} project.
5344@item
5345Installation routine rewritten after structure of source package
5346changed.
5347@item
5348Activation of @RefTeX{} changed, so make sure you read the installation
5349instructions and remove obsolete cruft related to @RefTeX{} from your
5350init file.
5351@item
5352Fixed bug where point would end up in the wrong buffer when jumping
5353between several @LaTeX{} and phrases buffers.
5354@item
5355Fixed bug where @BibTeX{} keys with hyphens were parsed incorrectly.
5356@item
5357Some performance improvements.
5358@item
5359The separator used between multiple citations in a \cite macro can now
5360be changed by customizing the variable @code{reftex-cite-key-separator}.
5361@end itemize
4009494e
GM
5362
5363@noindent @b{Version 4.28}
5364@itemize @bullet
5365@item Support for the Jurabib package.
5366@item Improvements when selecting several items in a selection buffer.
5367@end itemize
5368
5369@noindent @b{Version 4.26}
5370@itemize @bullet
5371@item
5372Support for global incremental search.
5373@item
5374Some improvements for XEmacs compatibility.
5375@end itemize
5376
5377@noindent @b{Version 4.25}
5378@itemize @bullet
5379@item
5380Fixed bug with @samp{%F} in a label prefix. Added new escapes
5381@samp{%m} and @samp{%M} for mater file name and master directory.
5382@end itemize
5383
5384@noindent @b{Version 4.24}
5385@itemize @bullet
9858f6c3 5386@item
4009494e
GM
5387Inserting citation commands now prompts for optional arguments
5388when called with a prefix argument. Related new options are
5389@code{reftex-cite-prompt-optional-args} and
9858f6c3 5390@code{reftex-cite-cleanup-optional-args}.
4009494e
GM
5391@item
5392New option @code{reftex-trust-label-prefix}. Configure this variable
5393if you'd like RefTeX to base its classification of labels on prefixes.
5394This can speed-up document parsing, but may in some cases reduce the
5395quality of the context used by RefTeX to describe a label.
5396@item
5397Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
5398is non-nil.
5399@item
5400Fixed bugs in indexing: Case-sensitive search, quotes before and/or
5401after words. Disabled indexing in comment lines.
5402@end itemize
5403
5404@noindent @b{Version 4.22}
5405@itemize @bullet
9858f6c3 5406@item
4009494e
GM
5407New command @code{reftex-create-bibtex-file} to create a new database
5408with all entries referenced in the current document.
5409@item
5410New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
5411from entries marked in a citation selection buffer.
5412@end itemize
5413
5414@noindent @b{Version 4.21}
5415@itemize @bullet
9858f6c3 5416@item
4009494e
GM
5417Renaming labels from the toc buffer with key @kbd{M-%}.
5418@end itemize
5419
5420@noindent @b{Version 4.20}
5421@itemize @bullet
5422@item
5423Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in
5424the TOC buffer promote/demote the section at point or all sections in
5425the current region.
5426@item
5427New option @code{reftex-toc-split-windows-fraction} to set the size of
1df7defd 5428the window used by the TOC@. This makes the old variable
4009494e
GM
5429@code{reftex-toc-split-windows-horizontally-fraction} obsolete.
5430@item
5431A dedicated frame can show the TOC with the current section
5432always automatically highlighted. The frame is created and
5433deleted from the toc buffer with the @kbd{d} key.
5434@end itemize
5435
5436@noindent @b{Version 4.19}
5437@itemize @bullet
5438@item
5439New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
5440section in the TOC buffer without selecting the TOC window.
5441@item
5442Recentering happens automatically in idle time when the option
5443@code{reftex-auto-recenter-toc} is turned on.
5444@item
5445Fixed several bugs related to automatic cursor positioning in the TOC
5446buffer.
5447@item
5448The highlight in the TOC buffer stays when the focus moves to a
5449different window.
5450@item
5451New command `reftex-goto-label'.
5452@item
5453Part numbers are no longer included in chapter numbers, and a new
5454part does not reset the chapter counter. See new option
5455@code{reftex-part-resets-chapter}.
5456@end itemize
5457
5458@noindent @b{Version 4.18}
5459@itemize @bullet
5460@item
5461@code{reftex-citation} uses the word before the cursor as a default
5462search string.
5463@item
5464Simplified several regular expressions for speed.
5465@item
5466Better support for chapterbib.
5467@end itemize
5468
5469@noindent @b{Version 4.17}
5470@itemize @bullet
5471@item
5472The toc window can be split off horizontally. See new options
5473@code{reftex-toc-split-windows-horizontally},
5474@code{reftex-toc-split-windows-horizontally-fraction}.
5475@item
5476It is possible to specify a function which verifies an index match
5477during global indexing. See new option @code{reftex-index-verify-function}.
5478@item
5479The macros which input a file in LaTeX (like \input, \include) can
5480be configured. See new option @code{reftex-include-file-commands}.
5481@item
5482The macros which specify the bibliography file (like \bibliography) can
5483be configured. See new option @code{reftex-bibliography-commands}.
5484@item
5485The regular expression used to search for the \bibliography macro has
5486been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
5487chapterbib.
5488@item
5489Small bug fixes.
5490@end itemize
5491
5492@noindent @b{Version 4.15}
5493@itemize @bullet
5494@item
5495Fixed bug with parsing of BibTeX files, when fields contain quotes or
5496unmatched parenthesis.
5497@item
5498Small bug fixes.
5499@item
5500Improved interaction with Emacs LaTeX mode.
5501@end itemize
5502
5503@noindent @b{Version 4.12}
5504@itemize @bullet
5505@item
5506Support for @file{bibentry} citation style.
5507@end itemize
5508
5509@noindent @b{Version 4.11}
5510@itemize @bullet
5511@item
5512Fixed bug which would parse @samp{\Section} just like @samp{\section}.
5513@end itemize
5514
5515@noindent @b{Version 4.10}
5516@itemize @bullet
5517@item
5518Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
5519with @file{reftex-vars.el} on DOS machines.
5520@item
5521New options @code{reftex-parse-file-extension} and
5522@code{reftex-index-phrase-file-extension}.
5523@end itemize
5524
5525@noindent [.....]
5526@ignore
5527@noindent @b{Version 4.09}
5528@itemize @bullet
5529@item
5530New option @code{reftex-toc-max-level} to limit the depth of the toc.
5531New key binding @kbd{t} in the @file{*toc*} buffer to change this
5532setting.
5533@item
5534RefTeX maintains an @file{Index Phrases} file in which phrases can be
5535collected. When the document is ready, RefTeX can search all
5536these phrases and assist indexing all matches.
5537@item
5538The variables @code{reftex-index-macros} and
5539@code{reftex-index-default-macro} have changed their syntax slightly.
5540The @var{repeat} parameter has move from the latter to the former.
5541Also calls to @code{reftex-add-index-macros} from AUCTeX style files
5542need to be adapted.
5543@item
5544The variable @code{reftex-section-levels} no longer contains the
5545default stuff which has been moved to a constant.
5546@item
5547Environments like theorems can be placed into the TOC by putting
5548entries for @samp{"begin@{theorem@}"} in
9858f6c3 5549@code{reftex-section-levels}.
4009494e
GM
5550@end itemize
5551
5552@noindent @b{Version 4.06}
5553@itemize @bullet
5554@item
5555@code{reftex-section-levels} can contain a function to compute the level
5556of a sectioning command.
5557@item
5558Multiple @code{thebibliography} environments recognized.
5559@end itemize
5560
5561@noindent @b{Version 4.04}
5562@itemize @bullet
5563@item
5564New option @code{reftex-index-default-tag} implements a default for queries.
5565@end itemize
5566
5567@noindent @b{Version 4.02}
5568@itemize @bullet
5569@item
5570macros ending in @samp{refrange} are considered to contain references.
5571@item
5572Index entries made with @code{reftex-index-selection-or-word} in TeX
5573math mode automatically get enclosing @samp{$} to preserve math mode. See
5574new option @code{reftex-index-math-format}. Requires AUCTeX.
5575@end itemize
5576
5577@noindent @b{Version 4.01}
5578@itemize @bullet
5579@item
5580New command @code{reftex-index-globally} to index a word in many
5581places in the document. Also available from the index buffer with
5582@kbd{&}.
5583@item
5584The first item in a @code{reftex-label-alist} entry may now also be a parser
5585function to do non-standard parsing.
5586@item
5587@code{reftex-auto-view-crossref} no longer interferes with
5588@code{pop-up-frames} (patch from Stefan Monnier).
5589@end itemize
5590
5591@noindent @b{Version 4.00}
5592@itemize @bullet
5593@item
5594RefTeX has been split into several smaller files which are autoloaded on
5595demand.
5596@item
5597Index support, along with many new options.
5598@item
5599The selection of keys for @code{\ref} and @code{\cite} now allows to
5600select multiple items by marking entries with the @kbd{m} key.
5601@item
5602Fancyref support.
5603@end itemize
5604
5605@noindent @b{Version 3.43}
5606@itemize @bullet
5607@item
5608Viewing cross-references generalized. Now works on @code{\label},
5609@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
5610these, and from BibTeX buffers.
5611@item
5612New option @code{reftex-view-crossref-extra}.
5613@item
5614Support for the additional sectioning commands @code{\addchap} and
5615@code{\addsec} which are defined in the LaTeX KOMA-Script classes.
5616@item
5617Files in @code{reftex-default-bibliography} will be searched along
5618@code{BIBINPUTS} path.
5619@item
5620Reading a parse file now checks consistency.
5621@end itemize
5622
5623@noindent @b{Version 3.42}
5624@itemize @bullet
5625@item
5626File search further refined. New option @code{reftex-file-extensions}.
5627@item
5628@file{*toc*} buffer can show the file boundaries of a multifile
5629document, all labels and associated context. New keys @kbd{i}, @kbd{l},
5630and @kbd{c}. New options @code{reftex-toc-include-labels},
5631@code{reftex-toc-include-context},
9858f6c3 5632@code{reftex-toc-include-file-boundaries}.
4009494e
GM
5633@end itemize
5634
5635@noindent @b{Version 3.41}
5636@itemize @bullet
5637@item
5638New options @code{reftex-texpath-environment-variables},
5639@code{reftex-use-external-file-finders},
5640@code{reftex-external-file-finders},
5641@code{reftex-search-unrecursed-path-first}.
5642@item
5643@emph{kpathsearch} support. See new options and
5644@code{reftex-bibpath-environment-variables}.
5645@end itemize
5646
5647@noindent @b{Version 3.38}
5648@itemize @bullet
5649@item
5650@code{reftex-view-crossref} no longer moves to find a macro. Point has
5651to be on the macro argument.
5652@end itemize
5653
5654@noindent @b{Version 3.36}
5655@itemize @bullet
5656@item
5657New value @code{window} for option @code{reftex-auto-view-crossref}.
5658@end itemize
5659
5660@noindent @b{Version 3.35}
5661@itemize @bullet
5662@item
5663ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
5664This takes back the related changes in 3.34 for safety reasons.
5665@end itemize
5666
5667@noindent @b{Version 3.34}
5668@itemize @bullet
5669@item
5670Additional flag in @code{reftex-derive-label-parameters} do make only
5671lowercase labels (default @code{t}).
5672@item
5673All @file{.rel} files have a final newline to avoid queries.
5674@item
5675Single byte representations of accented European letters (ISO-8859-1)
5676are now valid in labels.
5677@end itemize
5678
5679@noindent @b{Version 3.33}
5680@itemize @bullet
5681@item
5682Multiple selection buffers are now hidden buffers (they start with a
5683SPACE).
5684@item
5685Fixed bug with file search when TEXINPUTS environment variable is empty.
5686@end itemize
5687
5688@noindent @b{Version 3.30}
5689@itemize @bullet
5690@item
5691In @code{reftex-citation}, the regular expression used to scan BibTeX
5692files can be specified using completion on known citation keys.
5693@item
5694New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
5695entries.
5696@item
5697New command @code{reftex-renumber-simple-labels} to renumber simple
5698labels like @samp{eq:13} sequentially through a document.
5699@end itemize
5700
5701@noindent @b{Version 3.28}
5702@itemize @bullet
5703@item
5704Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
5705timer, since itimer restart is not reliable.
5706@item
5707Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
5708@item
5709Expansion of recursive tex and bib path rewritten.
5710@item
4f595e15 5711Fixed problem where @RefTeX{} did not scan unsaved buffers.
4009494e
GM
5712@item
5713Fixed bug with section numbering after *-red sections.
5714@end itemize
5715
5716@noindent @b{Version 3.27}
5717@itemize @bullet
5718@item
5719Macros can define @emph{neutral} labels, just like @code{\label}
5720itself.
5721@item
5722New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
5723@end itemize
5724
5725@noindent @b{Version 3.26}
5726@itemize @bullet
5727@item
5728[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
5729@item
5730New hooks @code{reftex-translate-to-ascii-function},
5731@code{reftex-string-to-label-function}.
5732@item
5733Made sure automatic crossref display will not visit/scan files.
5734@end itemize
5735
5736@noindent @b{Version 3.25}
5737@itemize @bullet
5738@item
5739Echoing of citation info caches the info for displayed entries.
5740New option @code{reftex-cache-cite-echo}.
5741@item
5742@kbd{M-x reftex-reset-mode} now also removes the file with parsing
5743info.
5744@item
5745Default of @code{reftex-revisit-to-follow} changed to nil.
5746@end itemize
5747
5748@noindent @b{Version 3.24}
5749@itemize @bullet
5750@item
5751New option @code{reftex-revisit-to-echo}.
5752@item
5753Interface with X-Symbol (>=2.6) is now complete and stable.
5754@item
5755Adapted to new outline, which uses overlays.
5756@item
5757File names in @code{\bibliography} may now have the @code{.bib}
5758extension.
5759@item
5760Fixed Bug with parsing "single file" from master file buffer.
5761@end itemize
5762
5763@noindent @b{Version 3.23}
5764@itemize @bullet
5765@item
5766Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
5767@item
5768@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
5769file.
5770@item
5771The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
5772automatic display of crossref information in the echo area. See
5773variable @code{reftex-auto-view-crossref}.
5774@item
5775AUCTeX interface updates:
5776@itemize @minus
5777@item
4f595e15 5778AUCTeX 9.9c and later notifies @RefTeX{} about new sections.
4009494e 5779@item
4f595e15 5780@RefTeX{} notifies AUCTeX about new labels.
4009494e
GM
5781@item
5782@code{TeX-arg-ref} no longer used (introduction was unnecessary).
5783@item
5784@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
5785@item
4f595e15 5786Settings added to @RefTeX{} via style files remain local.
4009494e
GM
5787@end itemize
5788@item
5789Fixed bug with @code{reftex-citation} in non-latex buffers.
5790@item
5791Fixed bug with syntax table and context refontification.
5792@item
5793Safety-net for name change of @code{font-lock-reference-face}.
5794@end itemize
5795
5796@noindent @b{Version 3.22}
5797@itemize @bullet
5798@item
5799Fixed bug with empty context strings.
5800@item
5801@code{reftex-mouse-view-crossref} is now bound by default at
5802@kbd{S-mouse-2}.
5803@end itemize
5804
5805@noindent @b{Version 3.21}
5806@itemize @bullet
5807@item
4f595e15 5808New options for all faces used by @RefTeX{}. They're in the
4009494e
GM
5809customization group @code{reftex-fontification-configurations}.
5810@end itemize
5811
5812@noindent @b{Version 3.19}
5813@itemize @bullet
5814@item
5815Fixed bug with AUCTeX @code{TeX-master}.
5816@end itemize
5817
5818@noindent @b{Version 3.18}
5819@itemize @bullet
5820@item
5821The selection now uses a recursive edit, much like minibuffer input.
1df7defd 5822This removes all restrictions during selection. E.g., you can now
4009494e
GM
5823switch buffers at will, use the mouse etc.
5824@item
5825New option @code{reftex-highlight-selection}.
5826@item
5827@kbd{mouse-2} can be used to select in selection and @file{*toc*}
5828buffers.
5829@item
5830Fixed some problems regarding the interaction with VIPER mode.
5831@item
5832Follow-mode is now only used after point motion.
5833@item
4f595e15 5834@RefTeX{} now finally does not fontify temporary files anymore.
4009494e
GM
5835@end itemize
5836
5837@noindent @b{Version 3.17}
5838@itemize @bullet
5839@item
5840Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
5841redefined.
5842@item
5843New command @code{reftex-save-all-document-buffers}.
5844@item
5845Magic word matching made more intelligent.
5846@item
5847Selection process can switch to completion (with @key{TAB}).
5848@item
5849@code{\appendix} is now recognized and influences section numbering.
5850@item
5851File commentary shortened considerably (use Info documentation).
5852@item
5853New option @code{reftex-no-include-regexps} to skip some include files.
5854@item
5855New option @code{reftex-revisit-to-follow}.
5856@end itemize
5857
5858@noindent @b{Version 3.16}
5859@itemize @bullet
5860@item
5861New hooks @code{reftex-format-label-function},
5862@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
5863@item
5864TeXInfo documentation completed.
5865@item
5866Some restrictions in Label inserting and referencing removed.
5867@item
5868New variable @code{reftex-default-bibliography}.
5869@end itemize
5870
5871@noindent @b{Version 3.14}
5872@itemize @bullet
5873@item
5874Selection buffers can be kept between selections: this is faster.
5875See new variable @code{reftex-use-multiple-selection-buffers}.
5876@item
5877Prefix interpretation of reftex-view-crossref changed.
5878@item
5879Support for the @code{varioref} package (@kbd{v} key in selection
5880buffer).
5881@end itemize
5882
5883@noindent @b{Version 3.12}
5884@itemize @bullet
5885@item
5886There are 3 new keymaps for customization: @code{reftex-toc-map},
5887@code{reftex-select-label-map}, @code{reftex-select-bib-map}.
5888@item
5889Refontification uses more standard font-lock stuff.
5890@item
5891When no BibTeX database files are specified, citations can also use
5892@code{\bibitem} entries from a @code{thebibliography} environment.
5893@end itemize
5894
5895@noindent @b{Version 3.11}
5896@itemize @bullet
5897@item
1df7defd 5898Fixed bug which led to naked label in (e.g.@:) footnotes.
4009494e
GM
5899@item
5900Added scroll-other-window functions to RefTeX-Select.
5901@end itemize
5902
5903@noindent @b{Version 3.10}
5904@itemize @bullet
5905@item
5906Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
5907@item
5908Removed unimportant code which caused OS/2 Emacs to crash.
5909@item
5910All customization variables now accessible from menu.
5911@end itemize
5912
5913@noindent @b{Version 3.07}
5914@itemize @bullet
5915@item
5916@code{Ref} menu improved.
5917@end itemize
5918
5919@noindent @b{Version 3.05}
5920@itemize @bullet
5921@item
5922Compatibility code now first checks for XEmacs feature.
5923@end itemize
5924
5925@noindent @b{Version 3.04}
5926@itemize @bullet
5927@item
5928Fixed BUG in the @emph{xr} support.
5929@end itemize
5930
5931@noindent @b{Version 3.03}
5932@itemize @bullet
5933@item
5934Support for the LaTeX package @code{xr}, for inter-document
5935references.
5936@item
5937A few (minor) Mule-related changes.
5938@item
5939Fixed bug which could cause @emph{huge} @file{.rel} files.
5940@item
5941Search for input and @file{.bib} files with recursive path definitions.
5942@end itemize
5943
5944@noindent @b{Version 3.00}
5945@itemize @bullet
5946@item
4f595e15 5947@RefTeX{} should work better for very large projects:
4009494e
GM
5948@item
5949The new parser works without creating a master buffer.
5950@item
5951Rescanning can be limited to a part of a multifile document.
5952@item
5953Information from the parser can be stored in a file.
5954@item
4f595e15 5955@RefTeX{} can deal with macros having a naked label as an argument.
4009494e
GM
5956@item
5957Macros may have white space and newlines between arguments.
5958@item
5959Multiple identical section headings no longer confuse
5960@code{reftex-toc}.
5961@item
4f595e15 5962@RefTeX{} should work correctly in combination with buffer-altering
4009494e
GM
5963packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
5964@item
5965All labeled environments discussed in @emph{The LaTeX Companion} by
5966Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
4f595e15 5967@RefTeX{}'s defaults.
4009494e
GM
5968@end itemize
5969
5970@noindent @b{Version 2.17}
5971@itemize @bullet
5972@item
5973Label prefix expands % escapes with current file name and other stuff.
5974@item
5975Citation format now with % escapes. This is not backward
5976compatible!
5977@item
5978TEXINPUTS variable recognized when looking for input files.
5979@item
5980Context can be the nth argument of a macro.
5981@item
5982Searching in the select buffer is now possible (@kbd{C-s} and
5983@kbd{C-r}).
5984@item
5985Display and derive-label can use two different context methods.
5986@item
5987AMSmath @code{xalignat} and @code{xxalignat} added.
5988@end itemize
5989
5990@noindent @b{Version 2.14}
5991@itemize @bullet
5992@item
5993Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
5994AUCTeX.
5995@end itemize
5996
5997@noindent @b{Version 2.11}
5998@itemize @bullet
5999@item
6000Submitted for inclusion to Emacs and XEmacs.
6001@end itemize
6002
6003@noindent @b{Version 2.07}
6004@itemize @bullet
6005@item
6006New functions @code{reftex-search-document},
6007@code{reftex-query-replace-document}.
6008@end itemize
6009
6010@noindent @b{Version 2.05}
6011@itemize @bullet
6012@item
6013Support for @file{custom.el}.
6014@item
6015New function @code{reftex-grep-document} (thanks to Stephen Eglen).
6016@end itemize
6017
6018@noindent @b{Version 2.03}
6019@itemize @bullet
6020@item
6021@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
6022default environments.
6023@item
6024@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
6025@item
6026New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
6027@code{reftex-arg-cite}.
6028@item
6029Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
6030required.
6031@item
6032@code{reftex-add-to-label-alist} (to be called from AUCTeX style
6033files).
6034@item
6035Finding context with a hook function.
6036@item
6037Sorting BibTeX entries (new variable:
6038@code{reftex-sort-bibtex-matches}).
6039@end itemize
6040
6041@noindent @b{Version 2.00}
6042@itemize @bullet
6043@item
6044Labels can be derived from context (default for sections).
6045@item
6046Configuration of label insertion and label referencing revised.
6047@item
6048Crossref fields in BibTeX database entries.
6049@item
6050@code{reftex-toc} introduced (thanks to Stephen Eglen).
6051@end itemize
6052
6053@noindent @b{Version 1.09}
6054@itemize @bullet
6055@item
6056Support for @code{tex-main-file}, an analogue for
6057@code{TeX-master}.
6058@item
6059MS-DOS support.
6060@end itemize
6061
6062@noindent @b{Version 1.07}
6063@itemize @bullet
6064@item
4f595e15 6065@RefTeX{} gets its own menu.
4009494e
GM
6066@end itemize
6067
6068@noindent @b{Version 1.05}
6069@itemize @bullet
6070@item
6071XEmacs port.
6072@end itemize
6073
6074@noindent @b{Version 1.04}
6075@itemize @bullet
6076@item
6077Macros as wrappers, AMSTeX support, delayed context parsing for
6078new labels.
6079@end itemize
6080@end ignore
6081
6082@noindent @b{Version 1.00}
6083@itemize @bullet
6084@item
6085released on 7 Jan 1997.
6086@end itemize
6087
6d1962b3 6088@node GNU Free Documentation License
4009494e
GM
6089@appendix GNU Free Documentation License
6090@include doclicense.texi
6091
6d1962b3 6092@node Index
4009494e
GM
6093@unnumbered Index
6094@printindex cp
6095
4009494e 6096@bye