Commit | Line | Data |
---|---|---|
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 {} | |
11 | Ref@TeX{} | |
12 | @end macro | |
13 | @macro AUCTeX {} | |
14 | AUC@TeX{} | |
15 | @end macro | |
16 | @macro BibTeX {} | |
17 | Bib@TeX{} | |
18 | @end macro | |
19 | @macro ConTeXt {} | |
20 | Con@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 |
44 | This manual documents @RefTeX{} (version @value{VERSION}), a package |
45 | to do labels, references, citations and indices for LaTeX documents | |
46 | with Emacs. | |
4009494e | 47 | |
f99f1641 | 48 | Copyright @copyright{} 1997--2012 Free Software Foundation, Inc. |
4009494e GM |
49 | |
50 | @quotation | |
51 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 52 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e | 53 | any later version published by the Free Software Foundation; with no |
debf4439 GM |
54 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', |
55 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
56 | is 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 | 59 | modify 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 |
102 | index entries with GNU Emacs. | |
4009494e | 103 | |
4f595e15 | 104 | This manual documents @RefTeX{} version @value{VERSION}. |
4009494e | 105 | |
4f595e15 RA |
106 | Don't be discouraged by the size of this manual, which covers @RefTeX{} |
107 | in great depth. All you need to know to use @RefTeX{} can be summarized | |
108 | on two pages (@pxref{RefTeX in a Nutshell}). You can go back later to | |
109 | other 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 | ||
136 | The Index | |
137 | ||
138 | * Index:: The full index. | |
139 | ||
140 | @detailmenu | |
4f595e15 | 141 | --- The Detailed Node Listing --- |
4009494e GM |
142 | |
143 | Introduction | |
144 | ||
145 | * Installation:: How to install and activate RefTeX. | |
146 | * RefTeX in a Nutshell:: A brief summary and quick guide. | |
147 | ||
148 | Labels 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 | |
158 | Defining 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 | ||
168 | Citations | |
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 | |
177 | Index 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 | ||
185 | The 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 | ||
191 | AUCTeX | |
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 | ||
197 | Options, 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, |
221 | citations, 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 | |
224 | parts of the document and searching through @BibTeX{} database files. | |
225 | @RefTeX{} automates these time-consuming tasks almost entirely. It also | |
226 | provides functions to display the structure of a document and to move | |
227 | around in this structure quickly. | |
4009494e GM |
228 | |
229 | @iftex | |
4f595e15 RA |
230 | Don't be discouraged by the size of this manual, which covers @RefTeX{} |
231 | in great depth. All you need to know to use @RefTeX{} can be | |
4009494e GM |
232 | summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go |
233 | back 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 | |
237 | reports 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 |
249 | version 20.2. It has also been bundled and pre-installed with XEmacs | |
250 | 19.16--20.x. XEmacs 21.x users want to install the corresponding | |
251 | plug-in package which is available from the @value{XEMACSFTP}. See the | |
252 | XEmacs 21.x documentation on package installation for details. | |
4009494e | 253 | |
4f595e15 RA |
254 | Users of earlier Emacs distributions (including Emacs 19) or people |
255 | craving for new features and bugs can get a copy of the @RefTeX{} | |
256 | distribution from the maintainer's web page. @xref{Imprint}, for more | |
257 | information. The following instructions will guide you through the | |
258 | process of installing such a distribution. | |
4009494e | 259 | |
4f595e15 | 260 | @subsection Building and Installing |
4009494e | 261 | |
4f595e15 RA |
262 | Note: Currently installation is supported for Emacs only. XEmacs users |
263 | might want to refer to the @RefTeX{} package available through the | |
264 | package system of XEmacs. | |
265 | ||
266 | @subsubheading Installation with make | |
267 | ||
268 | In order to install RefTeX, unpack the distribution and edit the header | |
269 | of the Makefile. Basically, you need to change the path specifications | |
270 | for Emacs Lisp files and info files. Also, enter the name of your Emacs | |
271 | executable (usually either @samp{emacs} or @samp{xemacs}). | |
272 | ||
1df7defd | 273 | Then, type |
4f595e15 RA |
274 | |
275 | @example | |
276 | make | |
277 | make install | |
278 | @end example | |
279 | ||
280 | to compile and install the code and documentation. | |
281 | ||
282 | Per default @RefTeX{} is installed in its own subdirectory which might | |
283 | not be on your load path. In this case, add it to load path with a | |
284 | command like the following, replacing the sample directory with the one | |
285 | where @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 |
291 | Put this command into your init file before other @RefTeX{}-related |
292 | settings. | |
293 | ||
294 | @subsubheading Installation by Hand | |
295 | ||
296 | If you want to get your hands dirty, there is also the possibility to | |
297 | install by manually copying files. | |
298 | ||
299 | @enumerate a | |
300 | @item | |
301 | Copy the reftex*.el lisp files to a directory on your load path. Make | |
302 | sure that no old copy of @RefTeX{} shadows these files. | |
303 | @item | |
304 | Byte compile the files. The sequence of compiling should be: | |
305 | reftex-var.el, reftex.el, and then all the others. | |
306 | @item | |
307 | Copy the info file reftex.info to the info directory. | |
308 | @end enumerate | |
309 | ||
310 | @subsection Loading @RefTeX{} | |
311 | ||
312 | In order to make the most important functions for entering @RefTeX{} | |
313 | mode 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 |
325 | To 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 | |
327 | LaTeX 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 |
334 | That's all! |
335 | ||
336 | To get started, read the documentation, in particular the | |
337 | summary. (@pxref{RefTeX in a Nutshell}) | |
338 | ||
339 | In order to produce a printed version of the documentation, use | |
340 | @code{make pdf} to produce a reftex.pdf file. Analogously you can use | |
341 | the @code{dvi}, @code{ps}, or @code{html} targets to create DVI, | |
342 | PostScript 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 | |
352 | document, and the BibTeX database files requested by the | |
353 | @code{\bibliography} command. To find these files, @RefTeX{} will | |
1df7defd | 354 | require a search path, i.e., a list of directories to check. Normally |
4f595e15 RA |
355 | this list is stored in the environment variables @code{TEXINPUTS} and |
356 | @code{BIBINPUTS} which are also used by @RefTeX{}. However, on some | |
357 | systems 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 | |
372 | a table of contents of the document. This buffer can display sections, | |
373 | labels and index entries defined in the document. From the buffer, you | |
374 | can jump quickly to every part of your document. Press @kbd{?} to get | |
375 | help. | |
376 | ||
377 | @item | |
4f595e15 | 378 | @b{Labels and References}@* @RefTeX{} helps to create unique labels |
4009494e GM |
379 | and to find the correct key for references quickly. It distinguishes |
380 | labels for different environments, knows about all standard | |
381 | environments (and many others), and can be configured to recognize any | |
382 | additional labeled environments you have defined yourself (variable | |
383 | @code{reftex-label-alist}). | |
384 | ||
385 | @itemize @bullet | |
386 | @item | |
387 | @b{Creating Labels}@* | |
388 | Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. | |
4f595e15 | 389 | @RefTeX{} will either |
4009494e GM |
390 | @itemize @minus |
391 | @item | |
392 | derive a label from context (default for section labels) | |
393 | @item | |
394 | prompt for a label string (default for figures and tables) or | |
395 | @item | |
396 | insert a simple label made of a prefix and a number (all other | |
397 | environments) | |
398 | @end itemize | |
399 | @noindent | |
400 | Which 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 | |
406 | all labels of a certain type (figure, equation,...) and some label | |
407 | context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro | |
408 | into the original buffer. | |
409 | @end itemize | |
410 | ||
411 | @item | |
412 | @b{Citations}@* | |
413 | Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a | |
4f595e15 | 414 | regular expression to search in current @BibTeX{} database files (as |
4009494e GM |
415 | specified in the @code{\bibliography} command) and pull out a list of |
416 | matches for you to choose from. The list is @emph{formatted} and | |
417 | sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} | |
418 | (see the variable @code{reftex-cite-format} if you want to insert | |
419 | different macros). | |
420 | ||
421 | @item | |
422 | @b{Index Support}@* | |
4f595e15 | 423 | @RefTeX{} helps to enter index entries. It also compiles all |
4009494e | 424 | entries into an alphabetically sorted @file{*Index*} buffer which you |
4f595e15 | 425 | can use to check and edit the entries. @RefTeX{} knows about the |
4009494e GM |
426 | standard index macros and can be configured to recognize any additional |
427 | macros you have defined (@code{reftex-index-macros}). Multiple indices | |
428 | are supported. | |
429 | ||
430 | @itemize @bullet | |
431 | @item | |
432 | @b{Creating Index Entries}@* | |
433 | To 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 | |
436 | type @kbd{C-c <} (@code{reftex-index}), select any of the index macros | |
437 | and enter the arguments with completion. | |
438 | ||
439 | @item | |
440 | @b{The Index Phrases File (Delayed Indexing)}@* | |
441 | Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add | |
442 | the 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 |
444 | phrases and let you interactively index the matches. |
445 | ||
446 | @item | |
447 | @b{Displaying and Editing the Index}@* | |
448 | To 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 | |
450 | all entries. | |
451 | @end itemize | |
452 | ||
453 | @page | |
454 | @item @b{Viewing Cross-References}@* | |
4f595e15 | 455 | When 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 | 458 | can press @kbd{C-c &} (@code{reftex-view-crossref}) to display |
4f595e15 | 459 | corresponding locations in the document and associated @BibTeX{} database |
4009494e GM |
460 | files. @* |
461 | When the enclosing macro is @code{\cite} or @code{\ref} and no other | |
462 | message occupies the echo area, information about the citation or label | |
463 | will automatically be displayed in the echo area. | |
464 | ||
465 | @item | |
466 | @b{Multifile Documents}@* | |
467 | Multifile Documents are fully supported. The included files must have a | |
468 | file variable @code{TeX-master} or @code{tex-main-file} pointing to the | |
4f595e15 | 469 | master file. @RefTeX{} provides cross-referencing information from |
4009494e GM |
470 | all 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 |
475 | order to find labels and other information. It does it automatically |
476 | once and updates its list internally when @code{reftex-label} and | |
477 | @code{reftex-index} are used. To enforce reparsing, call any of the | |
478 | commands 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 | |
480 | buffer, or the index buffer. | |
481 | ||
482 | @item | |
4f595e15 RA |
483 | @b{@AUCTeX{}} @* If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can |
484 | cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). @AUCTeX{} | |
4009494e | 485 | contains style files which trigger appropriate settings in |
4f595e15 | 486 | @RefTeX{}, so that for many of the popular @LaTeX{} packages no |
4009494e GM |
487 | additional customizations will be necessary. |
488 | ||
489 | @item | |
490 | @b{Useful Settings}@* | |
4f595e15 | 491 | To integrate RefTeX with @AUCTeX{}, use |
4009494e GM |
492 | @lisp |
493 | (setq reftex-plug-into-AUCTeX t) | |
494 | @end lisp | |
495 | ||
4f595e15 | 496 | To make your own @LaTeX{} macro definitions known to @RefTeX{}, |
4009494e GM |
497 | customize 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 | |
505 | If you have a large number of macros defined, you may want to write | |
4f595e15 RA |
506 | an @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 |
510 | until you have picked up the key bindings. For an overview of what you |
511 | can do in each of the different special buffers, press @kbd{?}. Read | |
4f595e15 | 512 | the manual if you get stuck, or if you are curious what else might be |
4009494e | 513 | available. The first part of the manual explains in |
4f595e15 | 514 | a tutorial way how to use and customize @RefTeX{}. The second |
4009494e GM |
515 | part 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 | ||
526 | Pressing the keys @kbd{C-c =} pops up a buffer showing the table of | |
527 | contents of the document. By default, this @file{*toc*} buffer shows | |
528 | only the sections of a document. Using the @kbd{l} and @kbd{i} keys you | |
529 | can display all labels and index entries defined in the document as | |
530 | well. | |
531 | ||
532 | With the cursor in any of the lines denoting a location in the | |
533 | document, simple key strokes will display the corresponding part in | |
534 | another window, jump to that location, or perform other actions. | |
535 | ||
536 | @kindex ? | |
537 | Here is a list of special commands in the @file{*toc*} buffer. A | |
538 | summary of this information is always available by pressing | |
539 | @kbd{?}. | |
540 | ||
541 | @table @kbd | |
542 | ||
543 | @tablesubheading{General} | |
544 | @item ? | |
545 | Display a summary of commands. | |
546 | ||
547 | @item 0-9, - | |
548 | Prefix argument. | |
549 | ||
550 | @tablesubheading{Moving around} | |
551 | @item n | |
4f595e15 | 552 | Goto next entry in the table of contents. |
4009494e GM |
553 | |
554 | @item p | |
4f595e15 | 555 | Goto previous entry in the table of contents. |
4009494e GM |
556 | |
557 | @item C-c C-n | |
558 | Goto next section heading. Useful when many labels and index entries | |
559 | separate section headings. | |
560 | ||
561 | @item C-c C-p | |
562 | Goto previous section heading. | |
563 | ||
564 | @item N z | |
565 | Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps | |
566 | to section 3. | |
567 | ||
568 | @tablesubheading{Access to document locations} | |
569 | @item @key{SPC} | |
570 | Show the corresponding location in another window. This command does | |
571 | @emph{not} select that other window. | |
572 | ||
573 | @item @key{TAB} | |
574 | Goto the location in another window. | |
575 | ||
576 | @item @key{RET} | |
577 | Go to the location and hide the @file{*toc*} buffer. This will restore | |
578 | the window configuration before @code{reftex-toc} (@kbd{C-c =}) was | |
579 | called. | |
580 | ||
581 | @item mouse-2 | |
582 | @vindex reftex-highlight-selection | |
583 | Clicking with mouse button 2 on a line has the same effect as @key{RET}. | |
584 | See 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 | |
590 | Toggle follow mode. When follow mode is active, the other window will | |
591 | always show the location corresponding to the line at point in the | |
592 | @file{*toc*} buffer. This is similar to pressing @key{SPC} after each | |
593 | cursor 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 | 595 | visited is shown. @RefTeX{} will not visit a file just for follow |
4009494e GM |
596 | mode. See, however, the variable |
597 | @code{reftex-revisit-to-follow}. | |
598 | ||
599 | @item . | |
600 | Show 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 < | |
607 | Promote the current section. This will convert @code{\section} to | |
608 | @code{\chapter}, @code{\subsection} to @code{\section} etc. If there is | |
609 | an active region, all sections in the region will be promoted, including | |
4f595e15 | 610 | the one at point. To avoid mistakes, @RefTeX{} requires a fresh |
f99f1641 | 611 | document scan before executing this command; if necessary, it will |
4009494e GM |
612 | automatically do this scan and ask the user to repeat the promotion |
613 | command. | |
614 | ||
615 | @item > | |
616 | Demote the current section. This is the opposite of promotion. It will | |
617 | convert @code{\chapter} to @code{\section} etc. If there is an active | |
618 | region, all sections in the region will be demoted, including the one at | |
619 | point. | |
620 | ||
621 | @item M-% | |
622 | Rename the label at point. While generally not recommended, this can be | |
623 | useful when a package like @file{fancyref} is used where the label | |
624 | prefix determines the wording of a reference. After a | |
625 | promotion/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 | 627 | used to do this; it launches a query replace to rename the definition |
4009494e GM |
628 | and all references of a label. |
629 | ||
630 | @tablesubheading{Exiting} | |
631 | @item q | |
632 | Hide the @file{*toc*} buffer, return to the position where | |
633 | @code{reftex-toc} was last called. | |
634 | ||
635 | @item k | |
636 | Kill the @file{*toc*} buffer, return to the position where | |
637 | @code{reftex-toc} was last called. | |
638 | ||
639 | @item C-c > | |
640 | Switch 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*} | |
642 | buffer. | |
643 | ||
644 | @tablesubheading{Controlling what gets displayed} | |
645 | ||
646 | @item t | |
647 | @vindex reftex-toc-max-level | |
648 | Change the maximum level of toc entries displayed in the @file{*toc*} | |
649 | buffer. Without prefix arg, all levels will be included. With prefix | |
650 | arg (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. | |
652 | The mode line @samp{T<>} indicator shows the current value. The default | |
653 | depth can be configured with the variable | |
654 | @code{reftex-toc-max-level}. | |
655 | ||
656 | @item F | |
657 | @vindex reftex-toc-include-file-boundaries | |
658 | Toggle 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 | |
660 | variable @code{reftex-toc-include-file-boundaries}. | |
661 | ||
662 | @item l | |
663 | @vindex reftex-toc-include-labels | |
664 | Toggle the display of labels in the @file{*toc*} buffer. The default | |
665 | for 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 |
668 | the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} |
669 | indicator shows which labels are included. | |
670 | ||
671 | @item i | |
672 | @vindex reftex-toc-include-index-entries | |
673 | Toggle the display of index entries in the @file{*toc*} buffer. The | |
674 | default for this flag can be set with the variable | |
675 | @code{reftex-toc-include-index-entries}. When called with a prefix | |
4f595e15 | 676 | argument, @RefTeX{} will prompt for a specific index and include |
4009494e GM |
677 | only entries in the selected index in the @file{*toc*} buffer. The mode |
678 | line @samp{I<>} indicator shows which index is used. | |
679 | ||
680 | @item c | |
681 | @vindex reftex-toc-include-context | |
682 | Toggle the display of label and index context in the @file{*toc*} | |
683 | buffer. 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 | |
689 | Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the | |
690 | document. | |
691 | ||
692 | @item r | |
693 | @vindex reftex-enable-partial-scans | |
4f595e15 | 694 | Reparse 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 |
696 | location is defined in, not the entire document. | |
697 | ||
698 | @item C-u r | |
4f595e15 | 699 | Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*toc*} |
4009494e GM |
700 | buffer. |
701 | ||
702 | @item x | |
703 | Switch to the @file{*toc*} buffer of an external document. When the | |
704 | current document is using the @code{xr} package (@pxref{xr (LaTeX | |
4f595e15 | 705 | package)}), @RefTeX{} will switch to one of the external |
4009494e GM |
706 | documents. |
707 | ||
708 | ||
709 | @tablesubheading{Automatic recentering} | |
710 | ||
711 | @item d | |
712 | Toggle the display of a dedicated frame displaying just the @file{*toc*} | |
713 | buffer. Follow mode and visiting locations will not work that frame, | |
714 | but automatic recentering will make this frame always show your current | |
715 | editing location in the document (see below). | |
716 | ||
717 | @item a | |
718 | Toggle the automatic recentering of the @file{*toc*} buffer. When this | |
719 | option is on, moving around in the document will cause the @file{*toc*} | |
720 | to always highlight the current section. By default, this option is | |
721 | active while the dedicated @file{*TOC*} frame exists. See also the | |
722 | variable @code{reftex-auto-recenter-toc}. | |
723 | ||
724 | @end table | |
725 | ||
726 | @vindex reftex-toc-map | |
727 | In order to define additional commands for the @file{*toc*} buffer, the | |
728 | keymap @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 - | |
736 | If you call @code{reftex-toc} while the @file{*toc*} buffer already | |
1df7defd | 737 | exists, the cursor will immediately jump to the right place, i.e., the |
4009494e GM |
738 | section from which @code{reftex-toc} was called will be highlighted. |
739 | The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay | |
740 | the @file{*toc*} buffer and highlight the correct line without actually | |
741 | selecting the @file{*toc*} window. This can be useful to quickly find | |
742 | out where in the document you currently are. You can also automate this | |
743 | by asking RefTeX to keep track of your current editing position in the | |
1df7defd | 744 | TOC@. The TOC window will then be updated whenever you stop typing for |
4009494e GM |
745 | more than @code{reftex-idle-time} seconds. By default this works only |
746 | with the dedicated @file{*TOC*} frame. But you can also force automatic | |
747 | recentering 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 | 758 | The section macros recognized by @RefTeX{} are all @LaTeX{} section |
4009494e GM |
759 | macros (from @code{\part} to @code{\subsubparagraph}) and the commands |
760 | @code{\addchap} and @code{\addsec} from the KOMA-Script classes. | |
761 | Additional macros can be configured with the variable | |
4f595e15 | 762 | @code{reftex-section-levels}. It is also possible to add certain @LaTeX{} |
4009494e GM |
763 | environments to the table of contents. This is probably only useful for |
764 | theorem-like environments. @xref{Defining Label Environments}, for an | |
765 | example. | |
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 | 776 | document. When writing a document, any part of it can be marked with a |
4f595e15 | 777 | label, like @samp{\label@{mark@}}. @LaTeX{} records the current value of a |
4009494e GM |
778 | certain counter when a label is defined. Later references to this label |
779 | (like @samp{\ref@{mark@}}) will produce the recorded value of the | |
780 | counter. | |
781 | ||
782 | Labels can be used to mark sections, figures, tables, equations, | |
4f595e15 | 783 | footnotes, items in enumerate lists etc. @LaTeX{} is context sensitive in |
4009494e GM |
784 | doing this: A label defined in a figure environment automatically |
785 | records the figure counter, not the section counter. | |
786 | ||
787 | Several different environments can share a common counter and therefore | |
4f595e15 | 788 | a 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 |
790 | equation 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 |
810 | In 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 |
812 | and will figure out the environment it currently is in and adapt the |
813 | label to that environment. A label usually consists of a short prefix | |
4f595e15 RA |
814 | indicating the type of the label and a unique mark. @RefTeX{} has |
815 | three 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 | 823 | A label can be derived from context. This means, @RefTeX{} takes |
4009494e GM |
824 | the context of the label definition and constructs a label from |
825 | that@footnote{Note that the context may contain constructs which are | |
4f595e15 | 826 | invalid in labels. @RefTeX{} will therefore strip the accent from |
4009494e GM |
827 | accented Latin-1 characters and remove everything else which is not |
828 | valid in labels. This mechanism is safe, but may not be satisfactory | |
829 | for non-western languages. Check the following variables if you need to | |
830 | change 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, | |
833 | where 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 |
835 | labels. You will be asked to confirm the derived label, or edit |
836 | it. | |
837 | ||
838 | @item | |
839 | We may also use a simple unique number to identify a label. This is | |
840 | mostly useful for labels where it is difficult to come up with a very | |
4f595e15 RA |
841 | good descriptive name. @RefTeX{}'s default settings use this method |
842 | for equations, enumerate items and footnotes. The author of @RefTeX{} | |
4009494e GM |
843 | tends to write documents with many equations and finds it impossible |
844 | to come up with good names for each of them. These simple labels are | |
845 | inserted without query, and are therefore very fast. Good descriptive | |
4f595e15 | 846 | names are not really necessary as @RefTeX{} will provide context to |
4009494e GM |
847 | reference a label (@pxref{Referencing Labels}). |
848 | ||
849 | @item | |
850 | The third method is to ask the user for a label. This is most | |
851 | useful for things which are easy to describe briefly and do not turn up | |
4f595e15 | 852 | too frequently in a document. @RefTeX{} uses this for figures and |
4009494e GM |
853 | tables. Of course, one can enter the label directly by typing the full |
854 | @samp{\label@{mark@}}. The advantage of using @code{reftex-label} | |
4f595e15 | 855 | anyway is that @RefTeX{} will know that a new label has been defined. |
4009494e GM |
856 | It will then not be necessary to rescan the document in order to access |
857 | this label later. | |
858 | @end enumerate | |
859 | ||
860 | @vindex reftex-insert-label-flags | |
861 | If you want to change the way certain labels are created, check out the | |
862 | variable @code{reftex-insert-label-flags} (@pxref{Options (Creating | |
863 | Labels)}). | |
864 | ||
4f595e15 | 865 | If you are using @AUCTeX{} to write your @LaTeX{} documents, you can |
4009494e | 866 | set 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 |
881 | referencing labels easier, it assigns to each label a category, the |
882 | @emph{label type} (for example section, table, figure, equation, etc.). | |
4f595e15 | 883 | In order to determine the label type, @RefTeX{} parses around each label |
4009494e GM |
884 | to see in what kind of environments it is located. You can speed up |
885 | the parsing by using type-specific prefixes for labels and configuring | |
886 | the variable @code{reftex-trust-label-prefix}. | |
887 | ||
4f595e15 RA |
888 | Referencing Labels is really at the heart of @RefTeX{}. Press @kbd{C-c |
889 | )} in order to reference a label (@code{reftex-reference}). This will | |
890 | start a selection process and finally insert the complete | |
891 | @samp{\ref@{label@}} into the buffer. | |
892 | ||
893 | @vindex reftex-ref-macro-prompt | |
894 | First, you can select which reference macro you want to use, | |
1df7defd | 895 | e.g., @samp{\ref} or @samp{\pageref}. Later in the process you have |
4f595e15 RA |
896 | another chance to make this selection and you can therefore disable this |
897 | step by customizing @code{reftex-ref-macro-prompt} if you find it too | |
898 | intrusive. @xref{Reference Styles}. | |
4009494e | 899 | |
4f595e15 RA |
900 | Then, @RefTeX{} will determine the label category which is required. |
901 | Often 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 | |
903 | an equation label is going to be referenced. If it cannot figure out | |
904 | what label category is needed, it will query for one. | |
4009494e GM |
905 | |
906 | You will then be presented with a label selection menu. This is a | |
907 | special buffer which contains an outline of the document along with all | |
908 | labels of the given label category. In addition, next to the label | |
909 | there will be one line of context of the label definition, which is some | |
910 | text in the buffer near the label definition. Usually this is | |
911 | sufficient to identify the label. If you are unsure about a certain | |
912 | label, pressing @key{SPC} will show the label definition point in | |
913 | another window. | |
914 | ||
4f595e15 | 915 | In order to reference a label, move the cursor to the correct label and |
4009494e GM |
916 | press @key{RET}. You can also reference several labels with a single |
917 | call to @code{reftex-reference} by marking entries with the @kbd{m} | |
918 | key (see below). | |
919 | ||
920 | @kindex ? | |
921 | Here is a list of special commands in the selection buffer. A summary | |
922 | of this information is always available from the selection process by | |
923 | pressing @kbd{?}. | |
924 | ||
925 | ||
926 | ||
927 | @table @kbd | |
928 | @tablesubheading{General} | |
929 | @item ? | |
930 | Show a summary of available commands. | |
931 | ||
932 | @item 0-9,- | |
933 | Prefix argument. | |
934 | ||
935 | @tablesubheading{Moving around} | |
936 | @item n | |
937 | Go to next label. | |
938 | ||
939 | @item p | |
940 | Go to previous label. | |
941 | ||
942 | @item b | |
943 | Jump back to the position where you last left the selection buffer. | |
944 | Normally this should get you back to the last referenced label. | |
945 | ||
946 | @item C-c C-n | |
947 | Goto next section heading. | |
948 | ||
949 | @item C-c C-p | |
950 | Goto previous section heading. | |
951 | ||
952 | @item N z | |
953 | Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to | |
954 | section 3. | |
955 | ||
956 | @tablesubheading{Displaying Context} | |
957 | @item @key{SPC} | |
958 | Show the surroundings of the definition of the current label in another | |
959 | window. See also the @kbd{f} key. | |
960 | ||
961 | @item f | |
962 | @vindex reftex-revisit-to-follow | |
963 | Toggle follow mode. When follow mode is active, the other window will | |
964 | always display the full context of the current label. This is similar | |
965 | to pressing @key{SPC} after each cursor motion. Note that only context | |
4f595e15 | 966 | in files already visited is shown. @RefTeX{} will not visit a file |
4009494e GM |
967 | just for follow mode. See, however, the variable |
968 | @code{reftex-revisit-to-follow}. | |
969 | ||
970 | @item . | |
971 | Show insertion point in another window. This is the point from where you | |
972 | called @code{reftex-reference}. | |
973 | ||
974 | @tablesubheading{Selecting a label and creating the reference} | |
975 | @item @key{RET} | |
976 | Insert a reference to the label at point into the buffer from which the | |
977 | selection process was started. When entries have been marked, @key{RET} | |
978 | references all marked labels. | |
979 | ||
980 | @item mouse-2 | |
981 | @vindex reftex-highlight-selection | |
982 | Clicking with mouse button 2 on a label will accept it like @key{RET} | |
4f595e15 RA |
983 | would. See also variable @code{reftex-highlight-selection}, |
984 | @ref{Options (Misc)}. | |
4009494e GM |
985 | |
986 | @vindex reftex-multiref-punctuation | |
987 | @item m - + , | |
988 | Mark 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 | |
991 | separator to be inserted before the corresponding reference. So marking | |
992 | six entries with the keys @samp{m , , - , +} will give a reference list | |
993 | like this (see the variable @code{reftex-multiref-punctuation}) | |
994 | @example | |
995 | In eqs. (1), (2), (3)--(4), (5) and (6) | |
996 | @end example | |
997 | ||
998 | @item u | |
999 | Unmark 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 | |
1005 | Accept the marked entries and put all labels as a comma-separated list | |
1006 | into one @emph{single} @code{\ref} macro. Some packages like | |
1007 | @file{saferef.sty} support multiple references in this way. | |
1008 | ||
1009 | @item l | |
1010 | Use the last referenced label(s) again. This is equivalent to moving to | |
1011 | that label and pressing @key{RET}. | |
1012 | ||
1013 | @item @key{TAB} | |
1014 | Enter a label with completion. This may also be a label which does not | |
1015 | yet exist in the document. | |
1016 | ||
1017 | @item v | |
4f595e15 RA |
1018 | Cycle forward through active reference macros. The selected macro is |
1019 | displayed by the @samp{S<...>} indicator in the mode line of the | |
1020 | selection buffer. This mechanism comes in handy if you are using | |
1021 | @LaTeX{} packages like @code{varioref} or @code{fancyref} and want to | |
1df7defd | 1022 | use 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 | 1026 | Cycle backward through active reference macros. |
4009494e GM |
1027 | |
1028 | @tablesubheading{Exiting} | |
1029 | ||
1030 | @item q | |
1031 | Exit the selection process without inserting any reference into the | |
1032 | buffer. | |
1033 | ||
1034 | @tablesubheading{Controlling what gets displayed} | |
1035 | @vindex reftex-label-menu-flags | |
1036 | The 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 | |
1040 | Toggle the display of the one-line label definition context in the | |
1041 | selection buffer. | |
1042 | ||
1043 | @item F | |
1044 | Toggle the display of the file borders of a multifile document in the | |
1045 | selection buffer. | |
1046 | ||
1047 | @item t | |
1048 | Toggle the display of the table of contents in the selection buffer. | |
1049 | With prefix @var{arg}, change the maximum level of toc entries displayed | |
4f595e15 | 1050 | to @var{arg}. Chapters are level 1, sections are level 2. |
4009494e GM |
1051 | |
1052 | @item # | |
1053 | Toggle the display of a label counter in the selection buffer. | |
1054 | ||
1055 | @item % | |
1056 | Toggle the display of labels hidden in comments in the selection | |
1057 | buffers. Sometimes, you may have commented out parts of your document. | |
4f595e15 | 1058 | If these parts contain label definitions, @RefTeX{} can still display |
4009494e GM |
1059 | and reference these labels. |
1060 | ||
1061 | @tablesubheading{Updating the buffer} | |
1062 | @item g | |
1063 | Update the menu. This will rebuilt the menu from the internal label | |
1064 | list, but not reparse the document (see @kbd{r}). | |
1065 | ||
1066 | @item r | |
1067 | @vindex reftex-enable-partial-scans | |
1068 | Reparse the document to update the information on all labels and rebuild | |
1069 | the menu. If the variable @code{reftex-enable-partial-scans} is | |
1070 | non-@code{nil} and your document is a multifile document, this will | |
1071 | reparse only a part of the document (the file in which the label at | |
1072 | point was defined). | |
1073 | ||
1074 | @item C-u r | |
1075 | Reparse the @emph{entire} document. | |
1076 | ||
1077 | @item s | |
1078 | Switch the label category. After prompting for another label category, | |
1079 | a menu for that category will be shown. | |
1080 | ||
1081 | @item x | |
4f595e15 | 1082 | Reference a label from an external document. With the @LaTeX{} package |
4009494e GM |
1083 | @code{xr} it is possible to reference labels defined in another |
1084 | document. This key will switch to the label menu of an external | |
1085 | document and let you select a label from there (@pxref{xr (LaTeX | |
1086 | package),,xr}). | |
1087 | ||
1088 | @end table | |
1089 | ||
1090 | @vindex reftex-select-label-map | |
1091 | In order to define additional commands for the selection process, the | |
1092 | keymap @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 | 1103 | with a label (i.e., which carry their own counters). By default, @RefTeX{} |
4009494e | 1104 | recognizes all labeled environments and macros discussed in @cite{The |
4f595e15 | 1105 | @LaTeX{} Companion by Goossens, Mittelbach & Samarin, Addison-Wesley |
4009494e GM |
1106 | 1994.}. 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 | 1122 | the @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 | |
1142 | the @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 | ||
1195 | If you want to use other labeled environments, defined with | |
4f595e15 | 1196 | @code{\newtheorem}, @RefTeX{} needs to be configured to recognize |
4009494e GM |
1197 | them (@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 |
1205 | environments and macros. This is done with the variable |
1206 | @code{reftex-label-alist} (@pxref{Options (Defining Label | |
1207 | Environments)}). If you are not familiar with Lisp, you can use the | |
1208 | @code{custom} library to configure this rather complex variable. To do | |
1209 | this, 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 | |
1216 | Here we will discuss a few examples, in order to make things clearer. | |
1217 | It can also be instructive to look at the constant | |
1218 | @code{reftex-label-alist-builtin} which contains the entries for | |
1219 | all the builtin environments and macros (@pxref{Builtin Label | |
1220 | Environments}). | |
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 | 1238 | Suppose you are using @code{\newtheorem} in @LaTeX{} in order to define two |
4009494e GM |
1239 | new environments, @code{theorem} and @code{axiom} |
1240 | ||
1241 | @example | |
1242 | \newtheorem@{axiom@}@{Axiom@} | |
1243 | \newtheorem@{theorem@}@{Theorem@} | |
1244 | @end example | |
1245 | ||
1246 | @noindent | |
1247 | to be used like this: | |
1248 | ||
1249 | @example | |
1250 | \begin@{axiom@} | |
1251 | \label@{ax:first@} | |
1252 | .... | |
1253 | \end@{axiom@} | |
1254 | @end example | |
1255 | ||
4f595e15 | 1256 | So we need to tell @RefTeX{} that @code{theorem} and @code{axiom} are new |
4009494e | 1257 | labeled environments which define their own label categories. We can |
1df7defd | 1258 | either use Lisp to do this (e.g., in @file{.emacs}) or use the custom |
4009494e GM |
1259 | library. 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 | ||
1267 | The type indicator characters @code{?a} and @code{?h} are used for | |
4f595e15 | 1268 | prompts when @RefTeX{} queries for a label type. @code{?h} |
4009494e GM |
1269 | was 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 | |
1274 | The 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 |
1277 | environment is inserted into a buffer. Additionally, the following | |
1278 | needs to be added to one's .emacs file before @AUCTeX{} will | |
1279 | automatically 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 | |
1291 | The @samp{~\ref@{%s@}} is a format string indicating how to insert | |
1292 | references to these labels. | |
1293 | ||
1294 | @noindent | |
1295 | The 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 | |
1299 | a @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 | |
1304 | For more complex ways of getting context, see the variable | |
1305 | @code{reftex-label-alist} (@ref{Options (Defining Label | |
1306 | Environments)}). | |
1307 | @end itemize | |
1308 | ||
1309 | The following list of strings is used to guess the correct label type | |
4f595e15 | 1310 | from the word before point when creating a reference. For example if you |
4009494e | 1311 | write: @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 |
1313 | restrict the menu to only these labels without even asking. |
1314 | ||
1315 | The final item in each entry is the level at which the environment | |
1316 | should produce entries in the table of context buffer. If the number is | |
1317 | positive, 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 | |
1320 | document similar to sectioning commands. For everything else, omit the | |
1321 | item. | |
1322 | ||
1323 | To do the same configuration with @code{customize}, you need to click on | |
1324 | the @code{[INS]} button twice to create two templates and fill them in | |
1325 | like this: | |
1326 | ||
1327 | @example | |
1328 | Reftex 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 | |
1356 | Depending on how you would like the label insertion and selection for | |
1357 | the new environments to work, you might want to add the letters @samp{a} | |
1358 | and @samp{h} to some of the flags in the variables | |
1359 | @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) | |
1360 | and @code{reftex-label-menu-flags} (@pxref{Options (Referencing | |
1361 | Labels)}). | |
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 | ||
1369 | Suppose you would like to have a macro for quick equations. It | |
1370 | could be defined like this: | |
1371 | ||
1372 | @example | |
1373 | \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} | |
1374 | @end example | |
1375 | ||
1376 | @noindent | |
1377 | and used like this: | |
1378 | ||
1379 | @example | |
1380 | Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. | |
1381 | @end example | |
1382 | ||
4f595e15 | 1383 | We 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 | ||
1390 | The 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 | |
1392 | an equation label, the different @code{nil} elements indicate to use the | |
1393 | default values for equations. The @samp{1} as the fifth element | |
4f595e15 | 1394 | indicates that the context of the label definition should be the first |
4009494e GM |
1395 | argument of the macro. |
1396 | ||
1397 | Here is again how this would look in the customization buffer: | |
1398 | ||
1399 | @example | |
1400 | Reftex 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 | ||
1417 | Suppose you want to make figures not directly with the figure | |
1418 | environment, 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 | |
1430 | which would be called like | |
1431 | ||
1432 | @example | |
1433 | \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} | |
1434 | @end example | |
1435 | ||
4f595e15 | 1436 | Now 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 |
1438 | the context. | |
1439 | ||
1440 | @lisp | |
1441 | (setq reftex-label-alist | |
1442 | '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) | |
1443 | @end lisp | |
1444 | ||
1445 | The empty pairs of brackets indicate the different arguments of the | |
1446 | @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} | |
1447 | indicates that this is a figure label which will be listed together with | |
1448 | labels from normal figure environments. The @code{nil} entries for | |
1449 | prefix and reference format mean to use the defaults for figure labels. | |
f99f1641 PE |
1450 | The @samp{3} for the context method means to grab the third macro argument: |
1451 | the caption. | |
4009494e GM |
1452 | |
1453 | As a side effect of this configuration, @code{reftex-label} will now | |
1454 | insert the required naked label (without the @code{\label} macro) when | |
1455 | point is directly after the opening parenthesis of a @code{\myfig} macro | |
1456 | argument. | |
1457 | ||
1458 | Again, 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 | ||
1478 | Sometimes you don't want to define a new label environment or macro, but | |
1479 | just change the information associated with a label category. Maybe you | |
1480 | want to add some magic words, for another language. Changing only the | |
1481 | information associated with a label category is done by giving | |
1482 | @code{nil} for the environment name and then specify the items you want | |
1483 | to define. Here is an example which adds German magic words to all | |
1484 | predefined 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 | ||
1502 | Another case where one only wants to change the information associated | |
1503 | with the label category is to change the macro which is used for | |
4f595e15 | 1504 | referencing the label. When working with the AMS-@LaTeX{}, you might |
4009494e GM |
1505 | prefer @code{\eqref} for doing equation references. Here is how to |
1506 | do 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 |
1513 | following is equivalent to the line above. |
1514 | ||
1515 | @lisp | |
1516 | (setq reftex-label-alist '(AMSTeX)) | |
1517 | @end lisp | |
1518 | ||
1519 | Note that this is automatically done by the @file{amsmath.el} style file | |
f99f1641 | 1520 | of @AUCTeX{} (@pxref{Style Files}); so if you use @AUCTeX{}, |
4009494e GM |
1521 | this 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 |
1530 | Some @LaTeX{} packages define environment-like structures without using the |
1531 | standard @samp{\begin..\end} structure. @RefTeX{} cannot parse | |
4009494e GM |
1532 | these directly, but you can write your own special-purpose parser and |
1533 | use it instead of the name of an environment in an entry for | |
1534 | @code{reftex-label-alist}. The function should check if point is | |
1535 | currently in the special environment it was written to detect. If so, | |
1536 | it must return a buffer position indicating the start of this | |
1537 | environment. The return value must be @code{nil} on failure to detect | |
1538 | the environment. The function is called with one argument @var{bound}. | |
1539 | If non-@code{nil}, @var{bound} is a boundary for backwards searches | |
1540 | which should be observed. We will discuss two examples. | |
1541 | ||
1542 | @cindex LaTeX commands, abbreviated | |
1543 | ||
1544 | Some people define abbreviations for | |
1545 | environments, like @code{\be} for @code{\begin@{equation@}}, and | |
1546 | @code{\ee} for @code{\end@{equation@}}. The parser function would have | |
1547 | to 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 | |
1550 | the beginning of the match. To avoid scanning too far, we can also look | |
1551 | for empty lines which cannot occur inside an equation environment. | |
1552 | Here 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} | |
1570 | A more complex example is the @file{linguex.sty} package which defines | |
1571 | list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are | |
1572 | terminated 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 | ||
1587 | The difficulty is that the @samp{\a.} lists can nest and that an empty | |
1588 | line terminates all list levels in one go. So we have to count nesting | |
1589 | levels between @samp{\a.} and @samp{\z.}. Here is the implementation | |
4f595e15 | 1590 | for @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 | ||
1627 | When you have to put several entries into @code{reftex-label-alist}, just | |
1628 | put them after each other in a list, or create that many templates in | |
1629 | the customization buffer. Here is a lisp example which uses several of | |
1630 | the 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 | ||
1653 | When point is idle for more than @code{reftex-idle-time} seconds on the | |
1654 | argument of a @code{\ref} macro, the echo area will display some | |
1655 | information about the label referenced there. Note that the information | |
1656 | is only displayed if the echo area is not occupied by a different | |
1657 | message. | |
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 | |
1662 | information. | |
1663 | ||
6d1962b3 | 1664 | @node Reference Styles |
4f595e15 RA |
1665 | @section Reference Styles |
1666 | ||
1667 | In 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 | |
1670 | convenient way. | |
1671 | ||
1672 | @RefTeX{} comes equipped with a set of so-called reference styles where | |
1673 | each relates to one or more reference macros. The standard macros | |
1674 | @samp{\ref} and @samp{\pageref} or provided by the ``Default'' style. | |
1675 | The ``Varioref'' style offers macros for the @samp{varioref} @LaTeX{} | |
1676 | package (@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 | |
1682 | A style can be toggled by selecting the respective entry in the | |
1683 | @samp{Reference Style} menu. Changes made through the menu will only | |
1684 | last for the Emacs session. In order to configure a preference | |
1685 | permanently, the variable @code{reftex-ref-style-default-list} should be | |
1686 | customized. This variable specifies the list of styles to be activated. | |
1687 | It can also be set as a file variable if the preference should be set | |
1688 | for a specific file. | |
1689 | ||
1690 | @vindex reftex-ref-style-alist | |
1691 | In case the built-in styles do not suffice, you can add additional | |
1692 | macros and styles to the variable @code{reftex-ref-style-alist}. Those | |
1693 | do not necessarily have to be related to a certain @LaTeX{} package but | |
1694 | can follow an arbitrary grouping rule. For example you could define a | |
1695 | style called ``Personal'' for your personal referencing macros. (When | |
1696 | changing the variable you should be aware that other Emacs packages, | |
1697 | like @AUCTeX{}, might rely on the entries from the default value to be | |
1698 | present.) | |
1699 | ||
1700 | Once a style is active the macros it relates to are available for | |
1701 | selection when you are about to insert a reference. In general this | |
1702 | process involves three steps: the selection of a reference macro, a | |
1703 | label type and a label. Reference macros can be chosen in the first and | |
1704 | last step. | |
1705 | ||
1706 | @vindex reftex-ref-macro-prompt | |
1707 | In the first step you will be presented with a list of macros from which | |
1708 | you can select one by typing a single key. If you dislike having an | |
1709 | extra step for reference macro selection, you can disable it by | |
1710 | customizing @code{reftex-ref-macro-prompt} and relying only on the | |
1711 | selection facilities provided in the last step. | |
1712 | ||
1df7defd | 1713 | In the last step, i.e., the label selection, two key bindings are |
4f595e15 RA |
1714 | provided to set the reference macro. Type @key{v} in order to cycle |
1715 | forward through the list of available macros or @key{V} to cycle | |
1716 | backward. The mode line of the selection buffer shows the macro | |
1717 | currently selected. | |
1718 | ||
1719 | In case you are not satisfied with the order of macros when cycling | |
1720 | through them you should adapt the order of entries in the variable | |
1721 | @code{reftex-ref-style-alist} to fit your liking. | |
1722 | ||
1723 | For 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 |
1725 | be created automatically by @RefTeX{}. These functions can be used |
1726 | instead of @kbd{C-c )} and provide an alternative way of having your | |
1727 | favorite referencing macro preselected and if cycling through the macros | |
1df7defd | 1728 | seems 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) | |
1738 | In former versions of @RefTeX{} only support for @code{varioref} and | |
1739 | @code{fancyref} was included. @code{varioref} is a @LaTeX{} package to | |
1740 | create cross-references with page information. @code{fancyref} is a | |
1741 | package where a macro call like @code{\fref@{@var{fig:map-of-germany}@}} | |
1742 | creates not only the number of the referenced counter but also the | |
1743 | complete text around it, like @samp{Figure 3 on the preceding page}. In | |
1744 | order to make it work you need to use label prefixes like @samp{fig:} | |
f99f1641 | 1745 | consistently---something @RefTeX{} does automatically. For each of |
4f595e15 RA |
1746 | these packages a variable could be configured to make its macros to take |
1747 | precedence over @code{\ref}. Those were @code{reftex-vref-is-default} | |
1748 | and @code{reftex-fref-is-default} respectively. While still working, | |
1749 | these variables are deprecated now. Instead of setting them, the | |
1750 | variable @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 | 1761 | The @LaTeX{} package @code{xr} makes it possible to create references to |
4009494e GM |
1762 | labels 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 | |
1772 | and we can make references to any labels defined in these | |
1773 | external documents by using the prefixes @samp{V1-} and @samp{V3-}, | |
1774 | respectively. | |
1775 | ||
4f595e15 | 1776 | @RefTeX{} can be used to create such references as well. Start the |
4009494e GM |
1777 | referencing process normally, by pressing @kbd{C-c )}. Select a label |
1778 | type 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 | 1780 | documents. You may then select a label as before and @RefTeX{} will |
4009494e GM |
1781 | insert it along with the required prefix. |
1782 | ||
1783 | For this kind of inter-document cross-references, saving of parsing | |
1784 | information and the use of multiple selection buffers can mean a large | |
1785 | speed-up (@pxref{Optimizations}). | |
1786 | ||
6d1962b3 | 1787 | @node Citations |
4009494e GM |
1788 | @chapter Citations |
1789 | @cindex Citations | |
1790 | @cindex @code{\cite} | |
1791 | ||
4f595e15 | 1792 | Citations in @LaTeX{} are done with the @code{\cite} macro or variations of |
4009494e | 1793 | it. The argument of the macro is a citation key which identifies an |
4f595e15 RA |
1794 | article or book in either a @BibTeX{} database file or in an explicit |
1795 | @code{thebibliography} environment in the document. @RefTeX{}'s | |
4009494e GM |
1796 | support 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 | 1816 | In order to create a citation, press @kbd{C-c [}. @RefTeX{} then |
4009494e GM |
1817 | prompts for a regular expression which will be used to search through |
1818 | the database and present the list of matches to choose from in a | |
1819 | selection process similar to that for selecting labels | |
1820 | (@pxref{Referencing Labels}). | |
1821 | ||
1822 | The regular expression uses an extended syntax: @samp{&&} defines a | |
1823 | logic @code{and} for regular expressions. For example | |
1824 | @samp{Einstein&&Bose} will match all articles which mention | |
1825 | Bose-Einstein condensation, or which are co-authored by Bose and | |
1826 | Einstein. When entering the regular expression, you can complete on | |
4f595e15 RA |
1827 | known citation keys. @RefTeX{} also offers a default when prompting for |
1828 | a regular expression. This default is the word before the cursor or the | |
4009494e GM |
1829 | word before the current @samp{\cite} command. Sometimes this may be a |
1830 | good 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 | 1839 | and along the path given in the environment variable @code{BIBINPUTS}. |
4f595e15 RA |
1840 | If you do not use @BibTeX{}, but the document contains an explicit |
1841 | @code{thebibliography} environment, @RefTeX{} will collect its | |
4009494e GM |
1842 | information from there. Note that in this case the information |
1843 | presented 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 ? | |
1848 | In the selection buffer, the following keys provide special commands. A | |
1849 | summary of this information is always available from the selection | |
1850 | process by pressing @kbd{?}. | |
1851 | ||
1852 | @table @kbd | |
1853 | @tablesubheading{General} | |
1854 | @item ? | |
1855 | Show a summary of available commands. | |
1856 | ||
1857 | @item 0-9,- | |
1858 | Prefix argument. | |
1859 | ||
1860 | @tablesubheading{Moving around} | |
1861 | @item n | |
1862 | Go to next article. | |
1863 | ||
1864 | @item p | |
1865 | Go to previous article. | |
1866 | ||
1867 | @tablesubheading{Access to full database entries} | |
1868 | @item @key{SPC} | |
1869 | Show the database entry corresponding to the article at point, in | |
1870 | another window. See also the @kbd{f} key. | |
1871 | ||
1872 | @item f | |
1873 | Toggle follow mode. When follow mode is active, the other window will | |
1874 | always display the full database entry of the current article. This is | |
4f595e15 | 1875 | equivalent to pressing @key{SPC} after each cursor motion. With @BibTeX{} |
4009494e GM |
1876 | entries, follow mode can be rather slow. |
1877 | ||
1878 | @tablesubheading{Selecting entries and creating the citation} | |
1879 | @item @key{RET} | |
1880 | Insert a citation referencing the article at point into the buffer from | |
1881 | which the selection process was started. | |
1882 | ||
1883 | @item mouse-2 | |
1884 | @vindex reftex-highlight-selection | |
1885 | Clicking with mouse button 2 on a citation will accept it like @key{RET} | |
1886 | would. See also variable @code{reftex-highlight-selection}, @ref{Options | |
1887 | (Misc)}. | |
1888 | ||
1889 | @item m | |
1890 | Mark the current entry. When one or several entries are marked, | |
1891 | pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, | |
1892 | @key{RET} behaves like the @kbd{a} key. | |
1893 | ||
1894 | @item u | |
1895 | Unmark a marked entry. | |
1896 | ||
1897 | @item a | |
1898 | Accept all (marked) entries in the selection buffer and create a single | |
1899 | @code{\cite} macro referring to them. | |
1900 | ||
1901 | @item A | |
1902 | Accept all (marked) entries in the selection buffer and create a | |
1903 | separate @code{\cite} macro for each of it. | |
1904 | ||
1905 | @item e | |
4f595e15 | 1906 | Create a new @BibTeX{} database file which contains all @i{marked} entries |
4009494e | 1907 | in the selection buffer. If no entries are marked, all entries are |
9858f6c3 | 1908 | selected. |
4009494e GM |
1909 | |
1910 | @item E | |
4f595e15 | 1911 | Create a new @BibTeX{} database file which contains all @i{unmarked} |
4009494e | 1912 | entries in the selection buffer. If no entries are marked, all entries |
9858f6c3 | 1913 | are selected. |
4009494e GM |
1914 | |
1915 | @item @key{TAB} | |
1916 | Enter a citation key with completion. This may also be a key which does | |
1917 | not yet exist. | |
1918 | ||
1919 | @item . | |
1920 | Show insertion point in another window. This is the point from where you | |
1921 | called @code{reftex-citation}. | |
1922 | ||
1923 | @tablesubheading{Exiting} | |
1924 | @item q | |
1925 | Exit the selection process without inserting a citation into the | |
1926 | buffer. | |
1927 | ||
1928 | @tablesubheading{Updating the buffer} | |
1929 | ||
1930 | @item g | |
1931 | Start over with a new regular expression. The full database will be | |
1932 | rescanned 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 | |
1936 | Refine the current selection with another regular expression. This will | |
1937 | @emph{not} rescan the entire database, but just the already selected | |
1938 | entries. | |
1939 | ||
1940 | @end table | |
1941 | ||
1942 | @vindex reftex-select-bib-map | |
1943 | In order to define additional commands for this selection process, the | |
1944 | keymap @code{reftex-select-bib-map} may be used. | |
1945 | ||
4f595e15 RA |
1946 | Note 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 | |
1948 | detects that the files were changed externally. If you do not want to | |
1949 | be bothered by such queries, you can activate Auto Revert mode for these | |
1950 | buffers 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 |
1972 | The standard @LaTeX{} macro @code{\cite} works well with numeric or |
1973 | simple key citations. To deal with the more complex task of author-year | |
4009494e GM |
1974 | citations as used in many natural sciences, a variety of packages has |
1975 | been 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 |
1977 | setting the variable @code{reftex-cite-format}. For the most commonly | |
1978 | used @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 |
1981 | create the citations, executing @code{reftex-citation} (@kbd{C-c [}) | |
1982 | starts by prompting for the correct macro. For the Natbib style, this | |
1983 | looks like this: | |
1984 | ||
1985 | @example | |
1986 | SELECT 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 | 2001 | If citation formats contain empty pairs of square brackets, @RefTeX{} |
4009494e GM |
2002 | will prompt for values of these optional arguments if you call the |
2003 | @code{reftex-citation} command with a @kbd{C-u} prefix. | |
2004 | Following the most generic of these packages, @code{natbib}, the builtin | |
2005 | citation packages always accept the @kbd{t} key for a @emph{textual} | |
2006 | citation (like: @code{Jones et al. (1997) have shown...}) as well as | |
2007 | the @kbd{p} key for a parenthetical citation (like: @code{As shown | |
2008 | earlier (Jones et al, 1997)}). | |
2009 | ||
2010 | To 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 | 2017 | You can also use @AUCTeX{} style files to automatically set the |
4009494e GM |
2018 | citation style based on the @code{usepackage} commands in a given |
2019 | document. @xref{Style Files}, for information on how to set up the style | |
2020 | files 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 | ||
2033 | When point is idle for more than @code{reftex-idle-time} seconds on the | |
2034 | argument of a @code{\cite} macro, the echo area will display some | |
2035 | information about the article cited there. Note that the information is | |
2036 | only 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 | 2039 | entry corresponding to a @code{\cite} macro, or all citation locations |
4f595e15 | 2040 | corresponding 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 | 2050 | produce 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 |
2052 | files. If they do not, it is best to have each document part in a |
2053 | separate file (as it is required for @code{chapterbib} anyway). Then | |
4f595e15 | 2054 | @RefTeX{} will still scan the locally relevant databases correctly. If |
4009494e GM |
2055 | you have multiple bibliographies within a @emph{single file}, this may |
2056 | or 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 | 2063 | The command @code{reftex-citation} can also be executed outside a @LaTeX{} |
4009494e GM |
2064 | buffer. This can be useful to reference articles in the mail buffer and |
2065 | other documents. You should @emph{not} enter @code{reftex-mode} for | |
4f595e15 | 2066 | this, just execute the command. The list of @BibTeX{} files will in this |
4009494e GM |
2067 | case be taken from the variable @code{reftex-default-bibliography}. |
2068 | Setting the variable @code{reftex-cite-format} to the symbol | |
2069 | @code{locally} does a decent job of putting all relevant information | |
2070 | about a citation directly into the buffer. Here is the lisp code to add | |
2071 | the @kbd{C-c [} binding to the mail buffer. It also provides a local | |
2072 | binding 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 | |
2090 | The first option produces a file which contains only the entries | |
2091 | actually referenced in the current document. This can be useful if | |
4f595e15 | 2092 | the database is only meant for a single document and you want to clean |
4009494e GM |
2093 | it of old and unused ballast. It can also be useful while writing a |
2094 | document together with collaborators, in order to avoid sending around | |
2095 | the entire (possibly very large) database. To create the file, use | |
2096 | @kbd{M-x reftex-create-bibtex-file}, also available from the menu | |
2097 | under @code{Ref->Global Actions->Create Bibtex File}. The command will | |
4f595e15 | 2098 | prompt for a @BibTeX{} file name and write the extracted entries to that |
4009494e GM |
2099 | file. |
2100 | ||
2101 | The second option makes use of the selection process started by the | |
2102 | command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a | |
2103 | regular expression to select entries, and lists them in a formatted | |
2104 | selection buffer. After pressing the @kbd{e} key (mnemonics: Export), | |
4f595e15 | 2105 | the command will prompt for the name of a new @BibTeX{} file and write |
4009494e GM |
2106 | the selected entries to that file. You can also first mark some |
2107 | entries in the selection buffer with the @kbd{m} key and then export | |
2108 | either 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 | 2117 | supports two different indices, the standard index and a glossary. With |
4f595e15 | 2118 | the help of special @LaTeX{} packages (@file{multind.sty} or |
4009494e GM |
2119 | @file{index.sty}), any number of indices can be supported. |
2120 | ||
2121 | Index entries are created with the @code{\index@{@var{entry}@}} macro. | |
2122 | All entries defined in a document are written out to the @file{.aux} | |
2123 | file. A separate tool must be used to convert this information into a | |
4f595e15 | 2124 | nicely formatted index. Tools used with @LaTeX{} include @code{MakeIndex} |
4009494e GM |
2125 | and @code{xindy}. |
2126 | ||
2127 | Indexing is a very difficult task. It must follow strict conventions to | |
2128 | make the index consistent and complete. There are basically two | |
2129 | approaches one can follow, and both have their merits. | |
2130 | ||
2131 | @enumerate | |
2132 | @item | |
2133 | Part of the indexing should already be done with the markup. The | |
2134 | document structure should be reflected in the index, so when starting | |
2135 | new sections, the basic topics of the section should be indexed. If the | |
2136 | document contains definitions, theorems or the like, these should all | |
2137 | correspond to appropriate index entries. This part of the index can | |
2138 | very well be developed along with the document. Often it is worthwhile | |
2139 | to define special purpose macros which define an item and at the same | |
2140 | time make an index entry, possibly with special formatting to make the | |
4f595e15 | 2141 | reference page in the index bold or underlined. To make @RefTeX{} |
4009494e | 2142 | support for indexing possible, these special macros must be added to |
4f595e15 | 2143 | @RefTeX{}'s configuration (@pxref{Defining Index Macros}). |
4009494e GM |
2144 | |
2145 | @item | |
2146 | The rest of the index is often just a collection of where in the | |
2147 | document certain words or phrases are being used. This part is | |
2148 | difficult to develop along with the document, because consistent entries | |
2149 | for each occurrence are needed and are best selected when the document | |
4f595e15 | 2150 | is ready. @RefTeX{} supports this with an @emph{index phrases file} |
4009494e GM |
2151 | which collects phrases and helps indexing the phrases globally. |
2152 | @end enumerate | |
2153 | ||
4f595e15 RA |
2154 | Before you start, you need to make sure that @RefTeX{} knows about |
2155 | the index style being used in the current document. @RefTeX{} has | |
4009494e | 2156 | builtin support for the default @code{\index} and @code{\glossary} |
4f595e15 | 2157 | macros. Other @LaTeX{} packages, like the @file{multind} or @file{index} |
4009494e | 2158 | package, redefine the @code{\index} macro to have an additional |
4f595e15 RA |
2159 | argument, and @RefTeX{} needs to be configured for those. A |
2160 | sufficiently new version of @AUCTeX{} (9.10c or later) will do this | |
2161 | automatically. If you really don't use @AUCTeX{} (you should!), this | |
4009494e GM |
2162 | configuration needs to be done by hand with the menu (@code{Ref->Index |
2163 | Style}), 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 | ||
2187 | In 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 | |
2189 | selection 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 | |
2193 | prefix argument (@kbd{C-u C-c /}), you get a chance to edit the | |
2194 | generated index entry. Use this to change the case of the word or to | |
2195 | make 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. | |
2198 | When there is nothing selected and no word at point, this command will | |
2199 | just call @code{reftex-index}, described below. | |
2200 | ||
2201 | In 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 |
2203 | available index macros and for its arguments. Completion will be |
2204 | available for the index entry and, if applicable, the index tag. The | |
2205 | index tag is a string identifying one of multiple indices. With the | |
2206 | @file{multind} and @file{index} packages, this tag is the first argument | |
2207 | to 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 |
2218 | later indexing. The file is located in the same directory as the master |
2219 | file 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 | |
2222 | is initialized by inserting a file header which contains the definition | |
2223 | of the available index macros. This list is initialized from | |
2224 | @code{reftex-index-macros} (@pxref{Defining Index Macros}). You can | |
4f595e15 | 2225 | edit the header as needed, but if you define new @LaTeX{} indexing macros, |
4009494e GM |
2226 | don't forget to add them to @code{reftex-index-macros} as well. Here is |
2227 | a 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 | ||
2240 | The macro definition lines consist of a unique letter identifying a | |
2241 | macro, 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 | |
2244 | indicates 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 | |
2247 | above example it is assumed that the macro @code{\index*@{@var{word}@}} | |
2248 | already typesets its argument in the text, so that it is unnecessary to | |
2249 | repeat @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 | ||
2263 | Phrases for indexing can be collected while writing the document. The | |
2264 | command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) | |
2265 | copies the current selection (if active) or the word near point into the | |
2266 | phrases buffer. It then selects this buffer, so that the phrase line | |
4f595e15 | 2267 | can 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 | ||
2270 | You can also prepare the list of index phrases in a different way and | |
2271 | copy it into the phrases file. For example you might want to start from | |
2272 | a word list of the document and remove all words which should not be | |
2273 | indexed. | |
2274 | ||
2275 | The 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 |
2277 | format. 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 | |
2285 | identifying one of the macros defined in the file header. It is | |
f99f1641 | 2286 | optional; when omitted, the first macro definition line in the file |
4009494e GM |
2287 | will be used for this phrase. The @var{phrase} is the phrase to be |
2288 | searched for when indexing. It may contain several words separated by | |
2289 | spaces. By default the search phrase is also the text entered as | |
2290 | argument of the index macro. If you want the index entry to be | |
2291 | different from the search phrase, enter another @key{TAB} and the index | |
2292 | argument @var{arg}. If you want to have each match produce several | |
2293 | index 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 | |
2296 | able to choose at each match between several different index arguments, | |
2297 | separate them with @samp{ || }@footnote{@samp{||} with optional spaces, | |
2298 | see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an | |
2299 | example: | |
2300 | ||
2301 | @example | |
2302 | %-------------------------------------------------------------------- | |
2303 | I Sun | |
2304 | i Planet Planets | |
2305 | i Vega Stars!Vega | |
2306 | Jupiter Planets!Jupiter | |
2307 | i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars | |
2308 | i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto | |
2309 | @end example | |
2310 | ||
2311 | ||
2312 | So @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 | |
2316 | macro definition in the file header (see above example). At each | |
2317 | occurrence of @samp{Mars} you will be able choose between indexing it as | |
2318 | a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. | |
2319 | Finally, every occurrence of @samp{Pluto} will be indexed as | |
2320 | @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} | |
2321 | and 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 | |
2330 | Before indexing the phrases in the phrases buffer, they should be | |
2331 | checked carefully for consistency. A first step is to sort the phrases | |
f99f1641 | 2332 | alphabetically; 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 |
2334 | buffer alphabetically by search phrase. If you want to group certain | |
2335 | phrases and only sort within the groups, insert empty lines between the | |
2336 | groups. Sorting will only change the sequence of phrases within each | |
2337 | group (see the variable @code{reftex-index-phrases-sort-in-blocks}). | |
2338 | ||
2339 | @kindex C-c C-i | |
2340 | A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) | |
2341 | which lists information about the phrase at point, including an example | |
2342 | of how the index entry will look like and the number of expected matches | |
2343 | in the document. | |
2344 | ||
2345 | @kindex C-c C-t | |
2346 | Another important check is to find out if there are double or | |
2347 | overlapping entries in the buffer. For example if you are first | |
2348 | searching and indexing @samp{Mars} and then @samp{Planet Mars}, the | |
2349 | second 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 | |
2352 | the buffer which is either duplicate or a subphrase of another phrase. | |
2353 | In order to check the whole buffer like this, start at the beginning and | |
2354 | execute 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 | ||
2362 | Once the index phrases have been collected and organized, you are set | |
2363 | for global indexing. I recommend to do this only on an otherwise | |
2364 | finished document. Global indexing starts from the phrases buffer. | |
2365 | There are several commands which start indexing: @kbd{C-c C-x} acts on | |
2366 | the current phrase line, @kbd{C-c C-r} on all lines in the current | |
2367 | region and @kbd{C-c C-a} on all phrase lines in the buffer. It is | |
2368 | probably good to do indexing in small chunks since your concentration | |
2369 | may 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 |
2372 | globally in the whole document. At each match it will stop, compute the |
2373 | replacement string and offer you the following choices@footnote{Windows | |
2374 | users: 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 | |
2379 | Replace this match with the proposed string. | |
2380 | @item n | |
2381 | Skip this match. | |
2382 | @item ! | |
2383 | Replace this and all further matches in this file. | |
2384 | @item q | |
2385 | Skip this match, start with next file. | |
2386 | @item Q | |
2387 | Skip this match, start with next phrase. | |
2388 | @item o | |
2389 | Select a different indexing macro for this match. | |
2390 | @item 1-9 | |
2391 | Select one of multiple index keys (those separated with @samp{||}). | |
2392 | @item e | |
2393 | Edit the replacement text. | |
2394 | @item C-r | |
2395 | Recursive edit. Use @kbd{C-M-c} to return to the indexing process. | |
2396 | @item s | |
2397 | Save this buffer and ask again about the current match. | |
2398 | @item S | |
2399 | Save all document buffers and ask again about the current match. | |
2400 | @item C-g | |
2401 | Abort the indexing process. | |
2402 | @end table | |
2403 | ||
2404 | The @samp{Find and Index in Document} menu in the phrases buffer also | |
2405 | lists a few options for the indexing process. The options have | |
2406 | associated 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 | |
2411 | When searching for index phrases, make sure whole words are matched. | |
2412 | This should probably always be on. | |
2413 | @item Case Sensitive Search | |
2414 | Search case sensitively for phrases. I recommend to have this setting | |
2415 | off, in order to match the capitalized words at the beginning of a | |
2416 | sentence, and even typos. You can always say @emph{no} at a match you | |
2417 | do not like. | |
2418 | @item Wrap Long Lines | |
2419 | Inserting index macros increases the line length. Turn this option on | |
4f595e15 | 2420 | to allow @RefTeX{} to wrap long lines. |
4009494e | 2421 | @item Skip Indexed Matches |
4f595e15 | 2422 | When this is on, @RefTeX{} will at each match try to figure out if |
4009494e GM |
2423 | this match is already indexed. A match is considered indexed if it is |
2424 | either the argument of an index macro, or if an index macro is directly | |
2425 | (without whitespace separation) before or after the match. Index macros | |
2426 | are those configured in @code{reftex-index-macros}. Intended for | |
2427 | re-indexing a documents after changes have been made. | |
2428 | @end table | |
2429 | ||
2430 | Even though indexing should be the last thing you do to a document, you | |
2431 | are bound to make changes afterwards. Indexing then has to be applied | |
2432 | to the changed regions. The command | |
2433 | @code{reftex-index-phrases-apply-to-region} is designed for this | |
4f595e15 | 2434 | purpose. When called from a @LaTeX{} document with active region, it will |
4009494e GM |
2435 | apply @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 | ||
2447 | In order to compile and display the index, press @kbd{C-c >}. If the | |
4f595e15 | 2448 | document uses multiple indices, @RefTeX{} will ask you to select |
4009494e GM |
2449 | one. Then, all index entries will be sorted alphabetically and |
2450 | displayed in a special buffer, the @file{*Index*} buffer. From that | |
2451 | buffer you can check and edit each entry. | |
2452 | ||
2453 | The index can be restricted to the current section or the region. Then | |
2454 | only entries in that part of the document will go into the compiled | |
2455 | index. 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 | |
2457 | region, 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 | |
2459 | restriction can be moved from one section to the next by pressing the | |
2460 | @kbd{<} and @kbd{>} keys. | |
2461 | ||
4f595e15 | 2462 | One caveat: @RefTeX{} finds the definition point of an index entry |
4009494e GM |
2463 | by searching near the buffer position where it had found to macro during |
2464 | scanning. If you have several identical index entries in the same | |
2465 | buffer and significant changes have shifted the entries around, you must | |
2466 | rescan the buffer to ensure the correspondence between the | |
2467 | @file{*Index*} buffer and the definition locations. It is therefore | |
2468 | advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) | |
2469 | frequently while editing the index from the @file{*Index*} | |
2470 | buffer. | |
2471 | ||
2472 | @kindex ? | |
2473 | Here is a list of special commands available in the @file{*Index*} buffer. A | |
2474 | summary of this information is always available by pressing | |
2475 | @kbd{?}. | |
2476 | ||
2477 | @table @kbd | |
2478 | @tablesubheading{General} | |
2479 | @item ? | |
2480 | Display a summary of commands. | |
2481 | ||
2482 | @item 0-9, - | |
2483 | Prefix argument. | |
2484 | ||
2485 | @tablesubheading{Moving around} | |
2486 | @item ! A..Z | |
2487 | Pressing any capital letter will jump to the corresponding section in | |
2488 | the @file{*Index*} buffer. The exclamation mark is special and jumps to | |
2489 | the first entries alphabetically sorted below @samp{A}. These are | |
2490 | usually non-alphanumeric characters. | |
2491 | @item n | |
2492 | Go to next entry. | |
2493 | @item p | |
2494 | Go to previous entry. | |
2495 | ||
2496 | @tablesubheading{Access to document locations} | |
2497 | @item @key{SPC} | |
2498 | Show the place in the document where this index entry is defined. | |
2499 | ||
2500 | @item @key{TAB} | |
2501 | Go to the definition of the current index entry in another | |
2502 | window. | |
2503 | ||
2504 | @item @key{RET} | |
2505 | Go 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 | |
2511 | Toggle follow mode. When follow mode is active, the other window will | |
2512 | always show the location corresponding to the line in the @file{*Index*} | |
2513 | buffer at point. This is similar to pressing @key{SPC} after each | |
2514 | cursor 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 | 2516 | already visited is shown. @RefTeX{} will not visit a file just for |
4009494e GM |
2517 | follow mode. See, however, the variable |
2518 | @code{reftex-revisit-to-follow}. | |
2519 | ||
2520 | @tablesubheading{Entry editing} | |
2521 | @item e | |
2522 | Edit the current index entry. In the minibuffer, you can edit the | |
2523 | index macro which defines this entry. | |
2524 | ||
2525 | @item C-k | |
2526 | Kill the index entry. Currently not implemented because I don't know | |
2527 | how to implement an @code{undo} function for this. | |
2528 | ||
2529 | @item * | |
2530 | Edit the @var{key} part of the entry. This is the initial part of the | |
2531 | entry which determines the location of the entry in the index. | |
2532 | ||
2533 | @item | | |
2534 | Edit the @var{attribute} part of the entry. This is the part after the | |
2535 | vertical bar. With @code{MakeIndex}, this part is an encapsulating | |
2536 | macro. With @code{xindy}, it is called @emph{attribute} and is a | |
2537 | property of the index entry that can lead to special formatting. When | |
2538 | called with @kbd{C-u} prefix, kill the entire @var{attribute} | |
2539 | part. | |
2540 | ||
2541 | @item @@ | |
2542 | Edit 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 | |
2544 | appearance of the entry in the index. When called with @kbd{C-u} | |
2545 | prefix, kill the entire @var{visual} part. | |
2546 | ||
2547 | @item ( | |
2548 | Toggle the beginning of page range property @samp{|(} of the | |
2549 | entry. | |
2550 | ||
2551 | @item ) | |
2552 | Toggle the end of page range property @samp{|)} of the entry. | |
2553 | ||
2554 | @item _ | |
2555 | Make the current entry a subentry. This command will prompt for the | |
2556 | superordinate entry and insert it. | |
2557 | ||
2558 | @item ^ | |
2559 | Remove the highest superordinate entry. If the current entry is a | |
2560 | subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy | |
2561 | (@samp{bbb!ccc}). | |
2562 | ||
2563 | @tablesubheading{Exiting} | |
2564 | @item q | |
2565 | Hide the @file{*Index*} buffer. | |
2566 | ||
2567 | @item k | |
2568 | Kill the @file{*Index*} buffer. | |
2569 | ||
2570 | @item C-c = | |
2571 | Switch 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 | |
2576 | Toggle the display of short context in the @file{*Index*} buffer. The | |
2577 | default for this flag can be set with the variable | |
2578 | @code{reftex-index-include-context}. | |
2579 | ||
2580 | @item @} | |
2581 | Restrict the index to a single document section. The corresponding | |
2582 | section number will be displayed in the @code{R<>} indicator in the | |
2583 | mode line and in the header of the @file{*Index*} buffer. | |
2584 | ||
2585 | @item @{ | |
2586 | Widen the index to contain all entries of the document. | |
2587 | ||
2588 | @item < | |
2589 | When the index is currently restricted, move the restriction to the | |
2590 | previous section. | |
2591 | ||
2592 | @item > | |
2593 | When the index is currently restricted, move the restriction to the | |
2594 | next section. | |
2595 | ||
2596 | @tablesubheading{Updating the buffer} | |
2597 | @item g | |
2598 | Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the | |
2599 | document. However, it sorts the entries again, so that edited entries | |
2600 | will move to the correct position. | |
2601 | ||
2602 | @item r | |
2603 | @vindex reftex-enable-partial-scans | |
4f595e15 | 2604 | Reparse 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 |
2606 | location is defined in, not the entire document. | |
2607 | ||
2608 | @item C-u r | |
4f595e15 | 2609 | Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*Index*} |
4009494e GM |
2610 | buffer. |
2611 | ||
2612 | @item s | |
2613 | Switch to a different index (for documents with multiple | |
2614 | indices). | |
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 |
2630 | also builtin support for the re-implementations of @code{\index} |
2631 | in the @file{multind} and @file{index} packages. However, since | |
2632 | the different definitions of the @code{\index} macro are incompatible, | |
2633 | you 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 | ||
2642 | When writing a document with an index you will probably define | |
2643 | additional macros which make entries into the index. | |
2644 | Let'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 | ||
2652 | The first macro @code{\ix} typesets its argument in the text and places | |
2653 | it into the index. The second macro @code{\nindex} typesets its | |
2654 | argument 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 | |
2656 | here.}. The last macro also places its argument into the index, but as | |
2657 | subitems under the main index entry @samp{Astronomical Objects}. Here | |
4f595e15 | 2658 | is how to make @RefTeX{} recognize and correctly interpret these |
4009494e GM |
2659 | macros, 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 | ||
2668 | Note 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 | |
2670 | for the default index and for the glossary. | |
2671 | ||
2672 | The character arguments @code{?x}, @code{?n}, and @code{?o} are for | |
4f595e15 | 2673 | quick identification of these macros when @RefTeX{} inserts new |
4009494e GM |
2674 | index entries with @code{reftex-index}. These codes need to be |
2675 | unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the | |
2676 | @code{\index}, @code{\index*}, and @code{\glossary} macros, | |
2677 | respectively. | |
2678 | ||
2679 | The following string is empty unless your macro adds a superordinate | |
f99f1641 | 2680 | entry to the index key; this is the case for the @code{\astobj} macro. |
4009494e GM |
2681 | |
2682 | The next entry can be a hook function to exclude certain matches, it | |
2683 | almost always can be @code{nil}. | |
2684 | ||
2685 | The final element in the list indicates if the text being indexed needs | |
2686 | to be repeated outside the macro. For the normal index macros, this | |
2687 | should 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 | ||
2691 | To do the same thing with customize, you need to fill in the templates | |
2692 | like this: | |
2693 | ||
2694 | @example | |
2695 | Repeat: | |
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 | ||
2720 | With the macro @code{\ix} defined, you may want to change the default | |
2721 | macro used for indexing a text phrase (@pxref{Creating Index Entries}). | |
2722 | This would be done like this | |
2723 | ||
2724 | @lisp | |
2725 | (setq reftex-index-default-macro '(?x "idx")) | |
2726 | @end lisp | |
2727 | ||
2728 | which specifies that the macro identified with the character @code{?x} (the | |
2729 | @code{\ix} macro) should be used for indexing phrases and words already | |
2730 | in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). | |
2731 | The 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, |
2741 | if two document locations are linked, @RefTeX{} can display the | |
4009494e GM |
2742 | matching location(s) in another window. The @code{\label} and @code{\ref} |
2743 | macros are one way of establishing such a link. Also, a @code{\cite} | |
4f595e15 | 2744 | macro is linked to the corresponding @code{\bibitem} macro or a @BibTeX{} |
4009494e GM |
2745 | database entry. |
2746 | ||
2747 | The feature is invoked by pressing @kbd{C-c &} | |
2748 | (@code{reftex-view-crossref}) while point is on the @var{key} argument | |
4f595e15 | 2749 | of 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 |
2751 | individual classes of macros: | |
2752 | ||
2753 | @table @asis | |
2754 | ||
2755 | @item @code{\ref} | |
2756 | @cindex @code{\ref} | |
2757 | Display the corresponding label definition. All usual | |
2758 | variants@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 | 2760 | cross-reference display. This works also for labels defined in an |
4009494e GM |
2761 | external 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 | |
2767 | Display a document location which references this label. Pressing | |
2768 | @kbd{C-c &} several times moves through the entire document and finds | |
2769 | all locations. Not only the @code{\label} macro but also other macros | |
2770 | with label arguments (as configured with @code{reftex-label-alist}) are | |
4f595e15 | 2771 | active for cross-reference display. |
4009494e GM |
2772 | |
2773 | @item @code{\cite} | |
2774 | @cindex @code{\cite} | |
4f595e15 | 2775 | Display the corresponding @BibTeX{} database entry or @code{\bibitem}. |
4009494e | 2776 | All 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 |
2778 | display. |
2779 | ||
2780 | @item @code{\bibitem} | |
2781 | @cindex @code{\bibitem} | |
2782 | Display a document location which cites this article. Pressing | |
2783 | @kbd{C-c &} several times moves through the entire document and finds | |
2784 | all 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 | 2790 | document where the database entry at point is cited will be displayed. |
4f595e15 | 2791 | On first use, @RefTeX{} will prompt for a buffer which belongs to |
4009494e GM |
2792 | the document you want to search. Subsequent calls will use the same |
2793 | document, until you break this link with a prefix argument to @kbd{C-c | |
2794 | &}. | |
2795 | ||
2796 | @item @code{\index} | |
2797 | @cindex @code{\index} | |
2798 | Display other locations in the document which are marked by an index | |
2799 | macro with the same key argument. Along with the standard @code{\index} | |
2800 | and @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 | |
2805 | While the display of cross referencing information for the above | |
4f595e15 | 2806 | mentioned macros is hard-coded, you can configure additional relations |
4009494e GM |
2807 | in 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 | 2822 | which 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 |
2825 | entire set of options. |
2826 | ||
6d1962b3 | 2827 | @node Key Bindings |
4009494e GM |
2828 | @section Default Key Bindings |
2829 | @cindex Key Bindings, summary | |
2830 | ||
2831 | Here 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 | ||
2860 | Note that the @kbd{S-mouse-2} binding is only provided if this key is | |
4f595e15 | 2861 | not already used by some other package. @RefTeX{} will not override an |
4009494e GM |
2862 | existing binding to @kbd{S-mouse-2}. |
2863 | ||
2864 | Personally, I also bind some functions in the users @kbd{C-c} map for | |
2865 | easier 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 | |
2888 | default. 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 | 2897 | Changing 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 |
2899 | which 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 | 2906 | table of contents buffers. It does not create its own faces, but uses |
4f595e15 | 2907 | the ones defined in @file{font-lock.el}. Therefore, @RefTeX{} will |
4009494e GM |
2908 | use faces only when @code{font-lock} is loaded. This seems to be |
2909 | reasonable because people who like faces will very likely have it | |
2910 | loaded. If you wish to turn off fontification or change the involved | |
2911 | faces, 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 | ||
2918 | The following is relevant when working with documents spread over many | |
2919 | files: | |
2920 | ||
2921 | @itemize @bullet | |
2922 | @item | |
4f595e15 | 2923 | @RefTeX{} has full support for multifile documents. You can edit parts of |
4009494e | 2924 | several (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 |
2927 | document. | |
2928 | ||
2929 | @item | |
2930 | @vindex tex-main-file | |
2931 | @vindex TeX-master | |
2932 | All files belonging to a multifile document should define a File | |
4f595e15 RA |
2933 | Variable (@code{TeX-master} for @AUCTeX{} or @code{tex-main-file} for the |
2934 | standard Emacs @LaTeX{} mode) containing the name of the master file. For | |
4009494e | 2935 | example, to set the file variable @code{TeX-master}, include something |
4f595e15 | 2936 | like 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 | ||
2951 | will actually ask you for each new file about the master file and insert | |
2952 | this comment automatically. For more details see the documentation of | |
4f595e15 | 2953 | the @AUCTeX{} (@pxref{Multifile,,,auctex, The AUCTeX User Manual}), the |
4009494e GM |
2954 | documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, |
2955 | The GNU Emacs Manual}) and the Emacs documentation on File Variables | |
2956 | (@pxref{File Variables,,,emacs, The GNU Emacs Manual}). | |
2957 | ||
2958 | @item | |
2959 | The context of a label definition must be found in the same file as the | |
4f595e15 | 2960 | label itself in order to be processed correctly by @RefTeX{}. The only |
4009494e GM |
2961 | exception is that section labels referring to a section statement |
2962 | outside the current file can still use that section title as | |
2963 | context. | |
2964 | @end itemize | |
2965 | ||
6d1962b3 | 2966 | @node Language Support |
4009494e GM |
2967 | @section Language Support |
2968 | @cindex Language support | |
2969 | ||
4f595e15 | 2970 | Some parts of @RefTeX{} are language dependent. The default |
4009494e GM |
2971 | settings work well for English. If you are writing in a different |
2972 | language, the following hints may be useful: | |
2973 | ||
2974 | @itemize @bullet | |
2975 | @item | |
2976 | @vindex reftex-derive-label-parameters | |
2977 | @vindex reftex-abbrev-parameters | |
2978 | The mechanism to derive a label from context includes the abbreviation | |
2979 | of words and omission of unimportant words. These mechanisms may have | |
2980 | to 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 | 2986 | Also, when a label is derived from context, @RefTeX{} clears the |
4009494e GM |
2987 | context string from non-ASCII characters in order to make a valid label. |
2988 | If there should ever be a version of @TeX{} which allows extended | |
2989 | characters @emph{in labels}, then we will have to look at the | |
2990 | variables @code{reftex-translate-to-ascii-function} and | |
2991 | @code{reftex-label-illegal-re}. | |
2992 | ||
2993 | @item | |
4f595e15 | 2994 | When a label is referenced, @RefTeX{} looks at the word before point |
4009494e GM |
2995 | to guess which label type is required. These @emph{magic words} are |
2996 | different in every language. For an example of how to add magic words, | |
2997 | see @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 |
3003 | for the author list in citations. Some of this may be language |
3004 | dependent. 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 | ||
3012 | In 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 |
3014 | environment variable @code{TEXINPUTS}. Similarly, it will search the |
3015 | path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for | |
4f595e15 | 3016 | @BibTeX{} database files. |
4009494e | 3017 | |
4f595e15 | 3018 | When searching, @RefTeX{} will also expand recursive path |
4009494e GM |
3019 | definitions (directories ending in @samp{//} or @samp{!!}). But it will |
3020 | only search and expand directories @emph{explicitly} given in these | |
3021 | variables. This may cause problems under the following circumstances: | |
3022 | ||
3023 | @itemize @bullet | |
3024 | @item | |
4f595e15 | 3025 | Most @TeX{} system have a default search path for both @TeX{} files and @BibTeX{} |
4009494e | 3026 | files which is defined in some setup file. Usually this default path is |
4f595e15 RA |
3027 | for system files which @RefTeX{} does not need to see. But if your |
3028 | document needs @TeX{} files or @BibTeX{} database files in a directory only | |
3029 | given in the default search path, @RefTeX{} will fail to find them. | |
4009494e | 3030 | @item |
4f595e15 | 3031 | Some @TeX{} systems do not use environment variables at all in order to |
4009494e GM |
3032 | specify the search path. Both default and user search path are then |
3033 | defined in setup files. | |
3034 | @end itemize | |
3035 | ||
3036 | @noindent | |
3037 | There are three ways to solve this problem: | |
3038 | ||
3039 | @itemize @bullet | |
3040 | @item | |
3041 | Specify all relevant directories explicitly in the environment | |
3042 | variables. If for some reason you don't want to mess with the default | |
3043 | variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own | |
4f595e15 | 3044 | variables 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 | 3052 | Specify 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 | 3062 | Some @TeX{} systems provide stand-alone programs to do the file search just |
1df7defd | 3063 | like @TeX{} and @BibTeX{}. E.g., Thomas Esser's @code{teTeX} uses the |
4009494e | 3064 | @code{kpathsearch} library which provides the command @code{kpsewhich} |
4f595e15 | 3065 | to search for files. @RefTeX{} can be configured to use this |
4009494e GM |
3066 | program. Note that the exact syntax of the @code{kpsewhich} |
3067 | command 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 | |
3080 | Some people like to use RefTeX with noweb files, which usually have the | |
3081 | extension @file{.nw}. In order to deal with such files, the new | |
3082 | extension 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, |
3084 | the 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 | |
3099 | optimizations discussed below will not be necessary on new machines. I | |
3100 | am leaving this stuff in the manual for people who want to write thick | |
3101 | books, where some of it still might be useful.} | |
3102 | ||
3103 | Implementing the principle of least surprises, the default settings of | |
4f595e15 RA |
3104 | @RefTeX{} ensure a safe ride for beginners and casual users. However, |
3105 | when using @RefTeX{} for a large project and/or on a small computer, | |
4009494e GM |
3106 | there 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 |
3113 | database files for lookup purposes. These buffers are kept, so that |
3114 | subsequent use of the same files is fast. If you can't afford keeping | |
3115 | these 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 | 3126 | A @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 | |
3130 | re-parsing of the entire document in order to update the parsing | |
3131 | information. For a large document this can be unnecessary, in | |
4f595e15 | 3132 | particular if only one file has changed. @RefTeX{} can be configured |
4009494e GM |
3133 | to do partial scans instead of full ones. @kbd{C-u} re-parsing then |
3134 | does apply only to the current buffer and files included from it. | |
3135 | Likewise, the @kbd{r} key in both the label selection buffer and the | |
3136 | table-of-contents buffer will only prompt scanning of the file in which | |
3137 | the label or section macro near the cursor was defined. Re-parsing of | |
3138 | the entire document is still available by using @kbd{C-u C-u} as a | |
3139 | prefix, or the capital @kbd{R} key in the menus. To use this feature, | |
3140 | try | |
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 | 3152 | Even with partial scans enabled, @RefTeX{} still has to make one full |
4009494e GM |
3153 | scan, when you start working with a document. To avoid this, parsing |
3154 | information can be stored in a file. The file @file{MASTER.rel} is used | |
3155 | for storing information about a document with master file | |
3156 | @file{MASTER.tex}. It is written automatically when you kill a buffer | |
3157 | in @code{reftex-mode} or when you exit Emacs. The information is | |
3158 | restored when you begin working with a document in a new editing | |
3159 | session. 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 |
3171 | environment this label is located, in order to assign a label type to |
3172 | the label. If your document contains thousands of labels, document | |
3173 | parsing will take considerable time. If you have been using label prefixes | |
4f595e15 | 3174 | like tab: and fn: consistently, you can tell @RefTeX{} to get the |
4009494e GM |
3175 | label type directly from the prefix, without additional parsing. This |
3176 | will be faster and also allow labels to end up in the correct category | |
3177 | if for some reason it is not possible to derive the correct type from | |
3178 | context. For example, to enable this feature for footnote and | |
3179 | equation 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 | 3189 | At rare occasions, @RefTeX{} will automatically rescan a part of the |
4009494e GM |
3190 | document. 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 |
3198 | buffer, saying that their position in the label list in uncertain. A |
3199 | manual document scan will fix this. | |
3200 | ||
3201 | @item | |
3202 | @b{Multiple Selection Buffers}@* | |
3203 | @cindex Multiple selection buffers | |
3204 | @cindex Selection buffers, multiple | |
3205 | Normally, the selection buffer @file{*RefTeX Select*} is re-created for | |
3206 | every selection process. In documents with very many labels this can | |
4f595e15 | 3207 | take several seconds. @RefTeX{} provides an option to create a |
4009494e GM |
3208 | separate selection buffer for each label type and to keep this buffer |
3209 | from one selection to the next. These buffers are updated automatically | |
3210 | only 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 | |
3213 | category 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 | |
3222 | You can also inhibit the automatic updating entirely. Then the | |
3223 | selection buffer will always pop up very fast, but may not contain the | |
3224 | most recently defined labels. You can always update the buffer by hand, | |
3225 | with 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 | 3253 | files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). |
4f595e15 | 3254 | If @AUCTeX{} is not part of your Emacs distribution, you can get |
4009494e | 3255 | it@footnote{XEmacs 21.x users may want to install the corresponding |
4f595e15 | 3256 | XEmacs 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 | 3268 | interface is turned on, both packages will interact closely. Instead of |
4f595e15 RA |
3269 | using @RefTeX{}'s commands directly, you can then also use them |
3270 | indirectly as part of the @AUCTeX{} | |
3271 | environment@footnote{@RefTeX{} 4.0 and @AUCTeX{} 9.10c will be | |
4009494e GM |
3272 | needed for all of this to work. Parts of it work also with earlier |
3273 | versions.}. The interface is turned on with | |
3274 | ||
3275 | @lisp | |
3276 | (setq reftex-plug-into-AUCTeX t) | |
3277 | @end lisp | |
3278 | ||
3279 | If you need finer control about which parts of the interface are used | |
3280 | and which not, read the docstring of the variable | |
3281 | @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x | |
3282 | customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. | |
3283 | ||
3284 | The 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 | 3295 | When a new section is created with @kbd{C-c C-s}, or a new environment |
4f595e15 | 3296 | is inserted with @kbd{C-c C-e}, @AUCTeX{} normally prompts for a label to |
4009494e | 3297 | go with it. With the interface, @code{reftex-label} is called instead. |
4f595e15 RA |
3298 | For 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 | |
3309 | without further prompts. | |
3310 | ||
4f595e15 | 3311 | Similarly, when you type @kbd{C-c C-s section @key{RET}}, @RefTeX{} |
4009494e GM |
3312 | will offer its default label which is derived from the section title. |
3313 | ||
3314 | @item | |
4f595e15 RA |
3315 | @b{@AUCTeX{} tells @RefTeX{} about new sections}@* |
3316 | When creating a new section with @kbd{C-c C-s}, @RefTeX{} will not | |
4009494e GM |
3317 | have 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 |
3331 | interactively with @kbd{C-c @key{RET}}, @AUCTeX{} normally prompts for | |
4009494e GM |
3332 | macro arguments. Internally, it uses the functions |
3333 | @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to | |
3334 | prompt for arguments which are labels, citation keys and index entries. | |
3335 | The interface takes over these functions@footnote{@code{fset} is used to | |
4f595e15 | 3336 | do this, which is not reversible. However, @RefTeX{} implements the |
4009494e | 3337 | old functionality when you later decide to turn off the interface.} and |
4f595e15 RA |
3338 | supplies the macro arguments with @b{@RefTeX{}'s} mechanisms. For |
3339 | example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @RefTeX{} | |
4009494e GM |
3340 | will supply its label selection process (@pxref{Referencing |
3341 | Labels}). | |
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 | 3352 | Style files are Emacs Lisp files which are evaluated by @AUCTeX{} in |
4009494e GM |
3353 | association with the @code{\documentclass} and @code{\usepackage} |
3354 | commands of a document (@pxref{Style Files,,,auctex}). Support for | |
4f595e15 | 3355 | @RefTeX{} in such a style file is useful when the @LaTeX{} style |
4009494e | 3356 | defines macros or environments connected with labels, citations, or the |
1df7defd | 3357 | index. Many style files (e.g., @file{amsmath.el} or @file{natbib.el}) |
4f595e15 | 3358 | distributed with @AUCTeX{} already support @RefTeX{} in this |
4009494e GM |
3359 | way. |
3360 | ||
4f595e15 | 3361 | Before calling a @RefTeX{} function, the style hook should always |
4009494e | 3362 | test for the availability of the function, so that the style file will |
4f595e15 | 3363 | also work for people who do not use @RefTeX{}. |
4009494e GM |
3364 | |
3365 | Additions made with style files in the way described below remain local | |
3366 | to the current document. For example, if one package uses AMSTeX, the | |
4f595e15 | 3367 | style file will make @RefTeX{} switch over to @code{\eqref}, but |
4009494e GM |
3368 | this will not affect other documents. |
3369 | ||
3370 | @findex reftex-add-label-environments | |
3371 | @findex reftex-add-to-label-alist | |
3372 | A style hook may contain calls to | |
3373 | @code{reftex-add-label-environments}@footnote{This used to be the | |
3374 | function @code{reftex-add-to-label-alist} which is still available as an | |
3375 | alias for compatibility.} which defines additions to | |
3376 | @code{reftex-label-alist}. The argument taken by this function must have | |
3377 | the same format as @code{reftex-label-alist}. The @file{amsmath.el} | |
4f595e15 | 3378 | style 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} | |
3391 | while a package @code{myprop} defining a @code{proposition} environment | |
3392 | with @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 | |
3407 | Similarly, a style hook may contain a call to | |
3408 | @code{reftex-set-cite-format} to set the citation format. The style | |
3409 | file @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 | |
3420 | The hook may contain a call to @code{reftex-add-index-macros} to | |
3421 | define additional @code{\index}-like macros. The argument must have | |
3422 | the same format as @code{reftex-index-macros}. It may be a symbol, to | |
3423 | trigger support for one of the builtin index packages. For example, | |
3424 | the 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 | ||
3433 | If you have your own package @file{myindex} which defines the | |
4f595e15 | 3434 | following 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 | ||
3440 | you 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 | |
3455 | Finally the hook may contain a call to @code{reftex-add-section-levels} | |
3456 | to define additional section statements. For example, the FoilTeX class | |
3457 | has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here | |
4f595e15 | 3458 | is 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 | ||
3473 | Once you have written a document with labels, references and citations, | |
4f595e15 | 3474 | it can be nice to read it like a hypertext document. @RefTeX{} has |
4009494e GM |
3475 | support 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 | |
3478 | highlighting 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 |
3480 | Bib-cite and @RefTeX{}. Bib-cite.el comes bundled with |
3481 | @AUCTeX{}. | |
4009494e GM |
3482 | |
3483 | Bib-cite version 3.06 and later can be configured so that bib-cite's | |
4f595e15 RA |
3484 | mouse functions use @RefTeX{} for displaying references and citations. |
3485 | This can be useful in particular when working with the @LaTeX{} @code{xr} | |
4009494e | 3486 | package or with an explicit @code{thebibliography} environment (rather |
4f595e15 | 3487 | than @BibTeX{}). Bib-cite cannot handle those, but @RefTeX{} does. To |
4009494e GM |
3488 | make 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 | |
3505 | have 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 |
3511 | make 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 | |
3517 | When using partial scans (@code{reftex-enable-partial-scans}), the section | |
3518 | numbers in the table of contents may eventually become wrong. A full | |
3519 | scan 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 | |
3527 | The label environment definitions in @code{reftex-label-alist} are | |
3528 | global and apply to all documents. If you need to make definitions | |
3529 | local to a document, because they would interfere with settings in other | |
4f595e15 | 3530 | documents, 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}. | |
3533 | Settings made with these functions remain local to the current | |
3534 | document. @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} | |
3544 | When using packages which make the buffer representation of a file | |
1df7defd | 3545 | different from its disk representation (e.g., x-symbol, isotex, |
4f595e15 | 3546 | iso-cvt) you may find that @RefTeX{}'s parsing information sometimes |
4009494e | 3547 | reflects the disk state of a file. This happens only in @emph{unvisited} |
4f595e15 | 3548 | parts of a multifile document, because @RefTeX{} visits these files |
4009494e GM |
3549 | literally for speed reasons. Then both short context and section |
3550 | headings may look different from what you usually see on your screen. | |
3551 | In rare cases @code{reftex-toc} may have problems to jump to an affected | |
3552 | section heading. There are three possible ways to deal with | |
3553 | this: | |
3554 | @itemize @minus | |
3555 | @item | |
3556 | @vindex reftex-keep-temporary-buffers | |
3557 | @code{(setq reftex-keep-temporary-buffers t)}@* | |
4f595e15 | 3558 | This implies that @RefTeX{} will load all parts of a multifile |
1df7defd | 3559 | document 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)}@* | |
3563 | This means full initialization of temporary buffers. It involves | |
3564 | a penalty when the same unvisited file is used for lookup often. | |
3565 | @item | |
3566 | Set @code{reftex-initialize-temporary-buffers} to a list of hook | |
3567 | functions doing a minimal initialization. | |
3568 | @end itemize | |
3569 | @vindex reftex-refontify-context | |
3570 | See 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} | |
3576 | Some packages use an additional argument to a @code{\begin} macro | |
1df7defd | 3577 | to 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 | 3585 | We 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 | |
3597 | The 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} |
3600 | argument (which really is a second argument to the macro @code{\begin}) | |
3601 | as a label of type @code{?p}. Argument count for this macro starts only | |
3602 | after the @samp{@{step+@}}, also when specifying how to get | |
3603 | context. | |
3604 | ||
3605 | @item | |
3606 | @b{Idle timers in XEmacs}@* | |
3607 | @cindex Idle timer restart | |
3608 | @vindex reftex-use-itimer-in-xemacs | |
3609 | In XEmacs, idle timer restart does not work reliably after fast | |
4f595e15 | 3610 | keystrokes. Therefore @RefTeX{} currently uses the post command |
4009494e GM |
3611 | hook to start the timer used for automatic crossref information. When |
3612 | this 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 | |
3622 | With @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 | 3644 | Eglen}. @RefTeX{} is currently maintained by @value{MAINTAINER}, see |
4009494e GM |
3645 | the @value{MAINTAINERSITE} for detailed information. |
3646 | ||
4f595e15 | 3647 | If 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 |
3649 | to the @value{DEVELADDRESS}. And in the rare case of finding a bug, | |
3650 | please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a | |
3651 | bug report with useful information about your setup. Remember to add | |
3652 | essential information like a recipe for reproducing the bug, what you | |
3653 | expected to happen, and what actually happened. Send the bug report to | |
3654 | the @value{BUGADDRESS}. | |
3655 | ||
3656 | There are also several Usenet groups which have competent readers who | |
3657 | might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, | |
3658 | @code{comp.emacs.xemacs}, and @code{comp.text.tex}. | |
3659 | ||
4f595e15 | 3660 | Thanks to the people on the Net who have used @RefTeX{} and helped |
4009494e GM |
3661 | developing it with their reports. In particular thanks to @i{Ralf |
3662 | Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, | |
3663 | Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai | |
3664 | Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan | |
3665 | Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, | |
4f595e15 RA |
3666 | Juri Linkov, Wolfgang Mayer, Rory Molinari, Stefan Monnier, Laurent |
3667 | Mugnier, Dan Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, | |
3668 | Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph | |
3669 | Wedler, Alan Williams, Roland Winkler, Hans-Christoph Wirth, Eli | |
3670 | Zaretskii}. | |
4009494e GM |
3671 | |
3672 | The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} | |
3673 | @file{bib-cite.el}. | |
3674 | ||
3675 | Finally thanks to @i{Uwe Bolick} who first got me interested in | |
4f595e15 | 3676 | supporting @LaTeX{} labels and references with an editor (which was |
4009494e GM |
3677 | MicroEmacs 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 |
3688 | Here 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 |
3690 | not described here. All commands are available from the @code{Ref} |
3691 | menu. See @xref{Key Bindings}. | |
3692 | ||
3693 | @deffn Command reftex-toc | |
3694 | Show the table of contents for the current document. When called with | |
3695 | one ore two @kbd{C-u} prefixes, rescan the document first. | |
3696 | @end deffn | |
3697 | ||
3698 | @deffn Command reftex-label | |
3699 | Insert a unique label. With one or two @kbd{C-u} prefixes, enforce | |
3700 | document rescan first. | |
3701 | @end deffn | |
3702 | ||
3703 | @deffn Command reftex-reference | |
3704 | Start a selection process to select a label, and insert a reference to | |
3705 | it. With one or two @kbd{C-u} prefixes, enforce document rescan first. | |
3706 | @end deffn | |
3707 | ||
3708 | @deffn Command reftex-citation | |
4f595e15 RA |
3709 | Make a citation using @BibTeX{} database files. After prompting for a regular |
3710 | expression, scans the buffers with @BibTeX{} entries (taken from the | |
4009494e GM |
3711 | @code{\bibliography} command or a @code{thebibliography} environment) |
3712 | and offers the matching entries for selection. The selected entry is | |
3713 | formatted according to @code{reftex-cite-format} and inserted into the | |
3714 | buffer. @* | |
3715 | When called with a @kbd{C-u} prefix, prompt for optional arguments in | |
3716 | cite macros. When called with a numeric prefix, make that many citations. | |
3717 | When called with point inside the braces of a @code{\cite} command, it | |
3718 | will add another key, ignoring the value of | |
3719 | @code{reftex-cite-format}. @* | |
3720 | The regular expression uses an expanded syntax: @samp{&&} is interpreted | |
3721 | as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain | |
3722 | both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion | |
3723 | on knows citation keys is possible. @samp{=} is a good regular | |
3724 | expression to match all entries in all files. | |
3725 | @end deffn | |
3726 | ||
3727 | @deffn Command reftex-index | |
3728 | Query for an index macro and insert it along with its arguments. The | |
3729 | index macros available are those defined in @code{reftex-index-macro} or | |
4f595e15 RA |
3730 | by a call to @code{reftex-add-index-macros}, typically from an @AUCTeX{} |
3731 | style file. @RefTeX{} provides completion for the index tag and the | |
4009494e GM |
3732 | index key, and will prompt for other arguments. |
3733 | @end deffn | |
3734 | ||
3735 | @deffn Command reftex-index-selection-or-word | |
3736 | Put current selection or the word near point into the default index | |
3737 | macro. This uses the information in @code{reftex-index-default-macro} | |
3738 | to make an index entry. The phrase indexed is the current selection or | |
3739 | the word near point. When called with one @kbd{C-u} prefix, let the | |
3740 | user 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 |
3742 | called inside @TeX{} math mode as determined by the @file{texmathp.el} |
3743 | library 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 | |
3748 | Add current selection or the word at point to the phrases buffer. | |
3749 | When you are in transient-mark-mode and the region is active, the | |
f99f1641 PE |
3750 | selection will be used; otherwise the word at point. |
3751 | You get a chance to edit the entry in the phrases buffer; to save the | |
4f595e15 | 3752 | buffer 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 | |
3756 | Switch to the phrases buffer, initialize if empty. | |
3757 | @end deffn | |
3758 | ||
3759 | @deffn Command reftex-index-phrases-apply-to-region | |
3760 | Index all index phrases in the current region. | |
3761 | This works exactly like global indexing from the index phrases buffer, | |
3762 | but operation is restricted to the current region. | |
3763 | @end deffn | |
3764 | ||
3765 | @deffn Command reftex-display-index | |
3766 | Display a buffer with an index compiled from the current document. | |
3767 | When the document has multiple indices, first prompts for the correct one. | |
3768 | When index support is turned off, offer to turn it on. | |
3769 | With one or two @kbd{C-u} prefixes, rescan document first. | |
3770 | With prefix 2, restrict index to current document section. | |
3771 | With prefix 3, restrict index to active region. | |
3772 | @end deffn | |
3773 | ||
3774 | @deffn Command reftex-view-crossref | |
3775 | View cross reference of macro at point. Point must be on the @var{key} | |
3776 | argument. Works with the macros @code{\label}, @code{\ref}, | |
3777 | @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of | |
3778 | these. Where it makes sense, subsequent calls show additional | |
3779 | locations. See also the variable @code{reftex-view-crossref-extra} and | |
3780 | the command @code{reftex-view-crossref-from-bibtex}. With one or two | |
3781 | @kbd{C-u} prefixes, enforce rescanning of the document. With argument | |
3782 | 2, select the window showing the cross reference. | |
3783 | @end deffn | |
3784 | ||
3785 | @deffn Command reftex-view-crossref-from-bibtex | |
4f595e15 RA |
3786 | View location in a @LaTeX{} document which cites the @BibTeX{} entry at point. |
3787 | Since @BibTeX{} files can be used by many @LaTeX{} documents, this function | |
3788 | prompts upon first use for a buffer in @RefTeX{} mode. To reset this | |
4009494e GM |
3789 | link to a document, call the function with a prefix arg. Calling |
3790 | this function several times find successive citation locations. | |
3791 | @end deffn | |
3792 | ||
3793 | @deffn Command reftex-create-tags-file | |
3794 | Create TAGS file by running @code{etags} on the current document. The | |
3795 | TAGS file is also immediately visited with | |
3796 | @code{visit-tags-table}. | |
3797 | @end deffn | |
3798 | ||
3799 | @deffn Command reftex-grep-document | |
3800 | Run grep query through all files related to this document. | |
3801 | With prefix arg, force to rescan document. | |
3802 | No active TAGS table is required. | |
3803 | @end deffn | |
3804 | ||
3805 | @deffn Command reftex-search-document | |
3806 | Regexp search through all files of the current document. | |
3807 | Starts always in the master file. Stops when a match is found. | |
3808 | No active TAGS table is required. | |
3809 | @end deffn | |
3810 | ||
3811 | @deffn Command reftex-query-replace-document | |
3812 | Run a query-replace-regexp of @var{from} with @var{to} over the entire | |
3813 | document. With prefix arg, replace only word-delimited matches. No | |
3814 | active TAGS table is required. | |
3815 | @end deffn | |
3816 | ||
3817 | @deffn Command reftex-isearch-minor-mode | |
3818 | Toggle a minor mode which enables incremental search to work globally | |
4f595e15 | 3819 | on the entire multifile document. Files will be searched in the |
4009494e GM |
3820 | sequence they appear in the document. |
3821 | @end deffn | |
3822 | ||
3823 | @deffn Command reftex-goto-label | |
3824 | Prompt for a label (with completion) and jump to the location of this | |
3825 | label. Optional prefix argument @var{other-window} goes to the label in | |
3826 | another window. | |
3827 | @end deffn | |
3828 | ||
3829 | ||
3830 | @deffn Command reftex-change-label | |
3831 | Query replace @var{from} with @var{to} in all @code{\label} and | |
3832 | @code{\ref} commands. Works on the entire multifile document. No | |
3833 | active TAGS table is required. | |
3834 | @end deffn | |
3835 | ||
3836 | @deffn Command reftex-renumber-simple-labels | |
3837 | Renumber all simple labels in the document to make them sequentially. | |
3838 | Simple labels are the ones created by RefTeX, consisting only of the | |
3839 | prefix and a number. After the command completes, all these labels will | |
3840 | have sequential numbers throughout the document. Any references to the | |
4f595e15 | 3841 | labels will be changed as well. For this, @RefTeX{} looks at the |
4009494e GM |
3842 | arguments of any macros which either start or end with the string |
3843 | @samp{ref}. This command should be used with care, in particular in | |
3844 | multifile documents. You should not use it if another document refers | |
3845 | to this one with the @code{xr} package. | |
3846 | @end deffn | |
3847 | ||
3848 | @deffn Command reftex-find-duplicate-labels | |
3849 | Produce 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 | |
3855 | Create a new @BibTeX{} database file with all entries referenced in | |
3856 | document. The command prompts for a filename and writes the collected | |
3857 | entries to that file. Only entries referenced in the current document | |
3858 | with any @code{\cite}-like macros are used. The sequence in the new | |
3859 | file is the same as it was in the old database. | |
3860 | ||
3861 | Entries referenced from other entries must appear after all referencing | |
3862 | entries. | |
3863 | ||
3864 | You can define strings to be used as header or footer for the created | |
3865 | files 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 | 3870 | Run the customize browser on the @RefTeX{} group. |
4009494e GM |
3871 | @end deffn |
3872 | @deffn Command reftex-show-commentary | |
3873 | Show the commentary section from @file{reftex.el}. | |
3874 | @end deffn | |
3875 | @deffn Command reftex-info | |
4f595e15 | 3876 | Run info on the top @RefTeX{} node. |
4009494e GM |
3877 | @end deffn |
3878 | @deffn Command reftex-parse-document | |
3879 | Parse the entire document in order to update the parsing information. | |
3880 | @end deffn | |
3881 | @deffn Command reftex-reset-mode | |
3882 | Enforce rebuilding of several internal lists and variables. Also | |
3883 | removes 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 | 3890 | Here is a complete list of @RefTeX{}'s configuration variables. All |
f99f1641 | 3891 | variables have customize support, so if you are not familiar with Emacs |
4009494e GM |
3892 | Lisp (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 | |
3894 | reftex-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 | 3917 | List of @LaTeX{} commands which input another file. |
4009494e GM |
3918 | The file name is expected after the command, either in braces or separated |
3919 | by whitespace. | |
3920 | @end defopt | |
3921 | ||
3922 | @defopt reftex-max-section-depth | |
3923 | Maximum depth of section levels in document structure. | |
4f595e15 | 3924 | Standard @LaTeX{} needs 7, default is 12. |
4009494e GM |
3925 | @end defopt |
3926 | ||
3927 | @defopt reftex-section-levels | |
3928 | Commands 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 | |
3931 | same as the positive value, but the section will never get a number. | |
3932 | The @code{cdr} may also be a function which then has to return the | |
3933 | level. This list is also used for promotion and demotion of sectioning | |
3934 | commands. If you are using a document class which has several sets of | |
3935 | sectioning commands, promotion only works correctly if this list is | |
3936 | sorted first by set, then within each set by level. The promotion | |
3937 | commands always select the nearest entry with the correct new level. | |
3938 | ||
3939 | @end defopt | |
3940 | ||
3941 | @defopt reftex-toc-max-level | |
1df7defd | 3942 | The maximum level of toc entries which will be included in the TOC@. |
4009494e GM |
3943 | Section headings with a bigger level will be ignored. In RefTeX, |
3944 | chapters are level 1, sections level 2 etc. This variable can be | |
3945 | changed from within the @file{*toc*} buffer with the @kbd{t} key. | |
3946 | @end defopt | |
3947 | ||
3948 | @defopt reftex-part-resets-chapter | |
3949 | Non-@code{nil} means, @code{\part} is like any other sectioning command. | |
3950 | This means, part numbers will be included in the numbering of chapters, and | |
3951 | chapter counters will be reset for each part. | |
3952 | When @code{nil} (the default), parts are special, do not reset the | |
3953 | chapter counter and also do not show up in chapter numbers. | |
3954 | @end defopt | |
3955 | ||
3956 | @defopt reftex-auto-recenter-toc | |
3957 | Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. | |
3958 | When active, the @file{*TOC*} window will always show the section you | |
3959 | are currently working in. Recentering happens whenever Emacs is idle for | |
3960 | more than @code{reftex-idle-time} seconds. | |
3961 | ||
3962 | Value @code{t} means, turn on immediately when RefTeX gets started. Then, | |
3963 | recentering will work for any toc window created during the session. | |
3964 | ||
3965 | Value @code{frame} (the default) means, turn automatic recentering on | |
3966 | only while the dedicated TOC frame does exist, and do the recentering | |
3967 | only in that frame. So when creating that frame (with @kbd{d} key in an | |
3968 | ordinary TOC window), the automatic recentering is turned on. When the | |
3969 | frame gets destroyed, automatic recentering is turned off again. | |
3970 | ||
9858f6c3 | 3971 | This 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 | |
3976 | Non-@code{nil} means, create TOC window by splitting window | |
3977 | horizontally. The default is to split vertically. | |
3978 | @end defopt | |
3979 | ||
3980 | @defopt reftex-toc-split-windows-fraction | |
3981 | Fraction 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 | |
3985 | Non-@code{nil} means, split the selected window to display the | |
3986 | @file{*toc*} buffer. This helps to keep the window configuration, but | |
3987 | makes the @file{*toc*} small. When @code{nil}, all other windows except | |
3988 | the selected one will be deleted, so that the @file{*toc*} window fills | |
3989 | half the frame. | |
3990 | @end defopt | |
3991 | ||
3992 | @defopt reftex-toc-include-file-boundaries | |
3993 | Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. | |
3994 | This 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 | |
3999 | Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag | |
4000 | can be toggled from within the @file{*toc*} buffer with the @kbd{l} | |
4001 | key. | |
4002 | @end defopt | |
4003 | ||
4004 | @defopt reftex-toc-include-index-entries | |
4005 | Non-@code{nil} means, include index entries in @file{*toc*} buffer. | |
4006 | This 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 | |
4011 | Non-@code{nil} means, include context with labels in the @file{*toc*} | |
4012 | buffer. Context will only be shown if the labels are visible as well. | |
4013 | This 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 | |
4018 | Non-@code{nil} means, point in @file{*toc*} buffer (the | |
4019 | table-of-contents buffer) will cause other window to follow. The other | |
4020 | window will show the corresponding part of the document. This flag can | |
4021 | be toggled from within the @file{*toc*} buffer with the @kbd{f} | |
4022 | key. | |
4023 | @end defopt | |
4024 | ||
4025 | @deffn {Normal Hook} reftex-toc-mode-hook | |
4026 | Normal hook which is run when a @file{*toc*} buffer is | |
4027 | created. | |
4028 | @end deffn | |
4029 | ||
4030 | @deffn Keymap reftex-toc-map | |
4031 | The 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 | |
4041 | Default label alist specifications. It is a list of symbols with | |
4042 | associations 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 | |
4047 | Set 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 | |
4050 | section labels, and @key{SPC} for the @code{any} label type. These are | |
4051 | hard-coded at other places in the code. | |
4052 | ||
4053 | The value of the variable must be a list of items. Each item is a list | |
4054 | itself 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 | ||
4061 | Each list entry describes either an environment carrying a counter for | |
4f595e15 | 4062 | use with @code{\label} and @code{\ref}, or a @LaTeX{} macro defining a |
4009494e GM |
4063 | label as (or inside) one of its arguments. The elements of each list |
4064 | entry are: | |
4065 | ||
4066 | @table @asis | |
4067 | @item @var{env-or-macro} | |
4068 | Name 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 | |
4071 | arguments, a star to mark the label argument, if any. The macro does | |
f99f1641 | 4072 | not have to have a label argument; you could also use |
4009494e GM |
4073 | @samp{\label@{...@}} inside one of its arguments. |
4074 | ||
4075 | Special names: @code{section} for section labels, @code{any} to define a | |
4076 | group which contains all labels. | |
4077 | ||
4078 | This may also be a function to do local parsing and identify point to be | |
4079 | in a non-standard label environment. The function must take an | |
4080 | argument @var{bound} and limit backward searches to this value. It | |
4081 | should return either nil or a cons cell @code{(@var{function} | |
4082 | . @var{position})} with the function symbol and the position where the | |
4083 | special environment starts. See the Info documentation for an | |
4084 | example. | |
4085 | ||
4086 | Finally this may also be @code{nil} if the entry is only meant to change | |
4087 | some settings associated with the type indicator character (see | |
4088 | below). | |
4089 | ||
4090 | @item @var{type-key} | |
4091 | Type indicator character, like @code{?t}, must be a printable ASCII | |
4092 | character. The type indicator is a single character which defines a | |
4093 | label type. Any label inside the environment or macro is assumed to | |
4094 | belong to this type. The same character may occur several times in this | |
4095 | list, to cover cases in which different environments carry the same | |
4096 | label type (like @code{equation} and @code{eqnarray}). If the type | |
4097 | indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, | |
4098 | the macro defines neutral labels just like @code{\label}. In this case | |
4f595e15 | 4099 | the remainder of this entry is ignored. |
4009494e GM |
4100 | |
4101 | @item @var{label-prefix} | |
4102 | Label prefix string, like @samp{tab:}. The prefix is a short string | |
4103 | used as the start of a label. It may be the empty string. The prefix | |
4104 | may 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 | |
4116 | Example: In a file @file{intro.tex}, @samp{eq:%f:} will become | |
4117 | @samp{eq:intro:}. | |
4118 | ||
4119 | @item @var{reference-format} | |
4f595e15 | 4120 | Format string for reference insertion in buffer. @samp{%s} will be |
4009494e GM |
4121 | replaced 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} | |
4126 | Indication on how to find the short context. | |
4127 | @itemize @minus | |
4128 | @item | |
4129 | If @code{nil}, use the text following the @samp{\label@{...@}} macro. | |
4130 | @item | |
4131 | If @code{t}, use | |
4132 | @itemize @minus | |
4133 | @item | |
4134 | the section heading for section labels. | |
4135 | @item | |
4136 | text following the @samp{\begin@{...@}} statement of environments (not | |
4137 | a good choice for environments like eqnarray or enumerate, where one has | |
4138 | several labels in a single environment). | |
4139 | @item | |
4140 | text after the macro name (starting with the first arg) for | |
4141 | macros. | |
4142 | @end itemize | |
4143 | @item | |
4144 | If an integer, use the nth argument of the macro. As a special case, | |
4145 | 1000 means to get text after the last macro argument. | |
4146 | @item | |
4147 | If a string, use as regexp to search @emph{backward} from the label. | |
1df7defd | 4148 | Context is then the text following the end of the match. E.g., setting |
4009494e GM |
4149 | this to @samp{\\caption[[@{]} will use the caption in a figure or table |
4150 | environment. @samp{\\begin@{eqnarray@}\|\\\\} works for | |
4151 | eqnarrays. | |
4152 | @item | |
4153 | If any of @code{caption}, @code{item}, @code{eqnarray-like}, | |
4154 | @code{alignat-like}, this symbol will internally be translated into an | |
4155 | appropriate regexp (see also the variable | |
4156 | @code{reftex-default-context-regexps}). | |
4157 | @item | |
4158 | If a function, call this function with the name of the environment/macro | |
4159 | as argument. On call, point will be just after the @code{\label} macro. | |
4160 | The function is expected to return a suitable context string. It should | |
4161 | throw an exception (error) when failing to find context. As an example, | |
4162 | here is a function returning the 10 chars following the label macro as | |
4163 | context: | |
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 | 4173 | Label context is used in two ways by @RefTeX{}: For display in the label |
4009494e GM |
4174 | menu, and to derive a label string. If you want to use a different |
4175 | method for each of these, specify them as a dotted pair. | |
1df7defd | 4176 | E.g., @code{(nil . t)} uses the text after the label (@code{nil}) for |
4009494e GM |
4177 | display, and text from the default position (@code{t}) to derive a label |
4178 | string. This is actually used for section labels. | |
4179 | ||
4180 | @item @var{magic-word-list} | |
4181 | List of magic words which identify a reference to be of this type. If | |
4182 | the word before point is equal to one of these words when calling | |
4183 | @code{reftex-reference}, the label list offered will be automatically | |
4184 | restricted to labels of the correct type. If the first element of this | |
4f595e15 | 4185 | word list is the symbol `regexp', the strings are interpreted as regular |
4009494e GM |
4186 | expressions. |
4187 | ||
4188 | @item @var{toc-level} | |
4189 | The integer level at which this environment should be added to the table | |
4190 | of contents. See also @code{reftex-section-levels}. A positive value | |
4191 | will number the entries mixed with the sectioning commands of the same | |
4192 | level. A negative value will make unnumbered entries. Useful only for | |
4193 | theorem-like environments which structure the document. Will be ignored | |
4194 | for macros. When omitted or @code{nil}, no TOC entries will be | |
4195 | made. | |
4196 | @end table | |
4197 | ||
4198 | If the type indicator characters of two or more entries are the same, | |
4f595e15 | 4199 | @RefTeX{} will use |
4009494e GM |
4200 | @itemize @minus |
4201 | @item | |
4202 | the first non-@code{nil} format and prefix | |
4203 | @item | |
4204 | the magic words of all involved entries. | |
4205 | @end itemize | |
4206 | ||
4207 | Any 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 | |
4209 | spliced into the list. However, builtin defaults should normally be set | |
4210 | with the variable @code{reftex-default-label-alist-entries}. | |
4211 | @end defopt | |
4212 | ||
4213 | @defopt reftex-section-prefixes | |
4214 | Prefixes 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 | |
4216 | determine the correct prefix string depending on the current section | |
4217 | level. The list is an alist, with each entry of the form | |
4218 | @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro | |
4219 | names 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 | |
4224 | Alist with default regular expressions for finding context. The emacs | |
4225 | lisp form @w{@code{(format regexp (regexp-quote environment))}} is used | |
f99f1641 | 4226 | to calculate the final regular expression, so @samp{%s} will be |
4009494e GM |
4227 | replaced with the environment or macro. |
4228 | @end defopt | |
4229 | ||
4230 | @defopt reftex-trust-label-prefix | |
4231 | Non-@code{nil} means, trust the label prefix when determining label type. | |
4232 | It is customary to use special label prefixes to distinguish different label | |
4f595e15 | 4233 | types. The label prefixes have no syntactic meaning in @LaTeX{} (unless |
4009494e GM |
4234 | special packages like fancyref) are being used. RefTeX can and by |
4235 | default does parse around each label to detect the correct label type, | |
4236 | but this process can be slow when a document contains thousands of | |
4237 | labels. If you use label prefixes consistently, you may speed up | |
4238 | document parsing by setting this variable to a non-nil value. RefTeX | |
4239 | will then compare the label prefix with the prefixes found in | |
4240 | `reftex-label-alist' and derive the correct label type in this way. | |
4241 | Possible values for this option are: | |
4242 | ||
4243 | @example | |
4244 | t @r{This means to trust any label prefixes found.} | |
4245 | regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} | |
4246 | list @r{List of accepted prefixes, as strings. The colon is part of} | |
1df7defd | 4247 | @r{the prefix, e.g., ("fn:" "eqn:" "item:").} |
4009494e GM |
4248 | nil @r{Never trust a label prefix.} |
4249 | @end example | |
4250 | The only disadvantage of using this feature is that the label context | |
4251 | displayed in the label selection buffer along with each label is | |
4252 | simply some text after the label definition. This is no problem if you | |
1df7defd | 4253 | place labels keeping this in mind (e.g., @i{before} the equation, @i{at |
4009494e GM |
4254 | the beginning} of a fig/tab caption ...). Anyway, it is probably best |
4255 | to use the regexp or the list value types to fine-tune this feature. | |
4256 | For example, if your document contains thousands of footnotes with | |
4257 | labels 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 | |
4259 | non-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 | |
4268 | Flags governing label insertion. The value has the form | |
4269 | ||
4270 | @example | |
4271 | (@var{derive} @var{prompt}) | |
4272 | @end example | |
4273 | ||
4f595e15 | 4274 | If @var{derive} is @code{t}, @RefTeX{} will try to derive a sensible |
4009494e GM |
4275 | label from context. A section label for example will be derived from |
4276 | the section heading. The conversion of the context to a valid label is | |
4277 | governed by the specifications given in | |
4278 | @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, | |
4279 | the default label will consist of the prefix and a unique number, like | |
4280 | @samp{eq:23}. | |
4281 | ||
4282 | If @var{prompt} is @code{t}, the user will be prompted for a label | |
4283 | string. When @var{prompt} is @code{nil}, the default label will be | |
4284 | inserted without query. | |
4285 | ||
4286 | So the combination of @var{derive} and @var{prompt} controls label | |
4287 | insertion. Here is a table describing all four possibilities: | |
4288 | ||
4289 | @example | |
4290 | @group | |
4291 | @var{derive} @var{prompt} @var{action} | |
4292 | ----------------------------------------------------------- | |
4293 | nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} | |
4294 | nil t @r{Prompt for label.} | |
4295 | t nil @r{Derive a label from context and insert. No query.} | |
4296 | t t @r{Derive a label from context, prompt for confirmation.} | |
4297 | @end group | |
4298 | @end example | |
4299 | ||
4300 | Each flag may be set to @code{t}, @code{nil}, or a string of label type | |
4301 | letters indicating the label types for which it should be true. Thus, | |
4302 | the combination may be set differently for each label type. The default | |
4303 | settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from | |
4304 | headings (with confirmation). Prompt for figure and table labels. Use | |
4305 | simple labels without confirmation for everything else. | |
4306 | ||
4307 | The 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 | |
4314 | If non-@code{nil}, should be a function which produces the string to | |
4315 | insert as a label definition. The function will be called with two | |
4316 | arguments, the @var{label} and the @var{default-format} (usually | |
4317 | @samp{\label@{%s@}}). It should return the string to insert into the | |
4318 | buffer. | |
4319 | @end deffn | |
4320 | ||
4321 | @deffn Hook reftex-string-to-label-function | |
4322 | Function 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 | |
4328 | Filter function which will process a context string before it is used to | |
4329 | derive a label from it. The intended application is to convert ISO or | |
4330 | Mule characters into something valid in labels. The default function | |
4331 | @code{reftex-latin1-to-ascii} removes the accents from Latin-1 | |
4332 | characters. X-Symbol (>=2.6) sets this variable to the much more | |
4333 | general @code{x-symbol-translate-to-ascii}. | |
4334 | @end deffn | |
4335 | ||
4336 | @defopt reftex-derive-label-parameters | |
4337 | Parameters for converting a string into a label. This variable is a | |
4338 | list of the following items: | |
4339 | @table @asis | |
4340 | @item @var{nwords} | |
4341 | Number of words to use. | |
4342 | @item @var{maxchar} | |
4343 | Maximum 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} | |
4352 | String separating different words in the label. | |
4353 | @item @var{ignorewords} | |
4354 | List 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 | |
4361 | Regexp matching characters not valid in labels. | |
4362 | @end defopt | |
4363 | ||
4364 | @defopt reftex-abbrev-parameters | |
4365 | Parameters for abbreviation of words. A list of four parameters. | |
4366 | @table @asis | |
4367 | @item @var{min-chars} | |
4368 | Minimum number of characters remaining after abbreviation. | |
4369 | @item @var{min-kill} | |
4370 | Minimum number of characters to remove when abbreviating words. | |
4371 | @item @var{before} | |
4372 | Character class before abbrev point in word. | |
4373 | @item @var{after} | |
4374 | Character 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 | |
4384 | List of flags governing the label menu makeup. The flags are: | |
4385 | @table @asis | |
4386 | @item @var{table-of-contents} | |
4387 | Show the labels embedded in a table of context. | |
4388 | @item @var{section-numbers} | |
4389 | Include section numbers (like 4.1.3) in table of contents. | |
4390 | @item @var{counters} | |
4391 | Show counters. This just numbers the labels in the menu. | |
4392 | @item @var{no-context} | |
4393 | Non-@code{nil} means do @emph{not} show the short context. | |
4394 | @item @var{follow} | |
4395 | Follow full context in other window. | |
4396 | @item @var{show-commented} | |
4397 | Show labels from regions which are commented out. | |
4398 | @item @var{match-everywhere} | |
4399 | Obsolete flag. | |
4400 | @item @var{show-files} | |
4401 | Show begin and end of included files. | |
4402 | @end table | |
4403 | ||
4404 | Each of these flags can be set to @code{t} or @code{nil}, or to a string | |
4405 | of type letters indicating the label types for which it should be true. | |
4406 | These strings work like character classes in regular expressions. Thus, | |
4407 | setting one of the flags to @samp{"sf"} makes the flag true for section | |
4408 | and figure labels, @code{nil} for everything else. Setting it to | |
4409 | @samp{"^sf"} makes it the other way round. | |
4410 | ||
4411 | The 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 | 4415 | Most options can also be switched from the label menu itself, so if you |
4009494e GM |
4416 | decide here to not have a table of contents in the label menu, you can |
4417 | still get one interactively during selection from the label menu. | |
4418 | @end defopt | |
4419 | ||
4420 | @defopt reftex-multiref-punctuation | |
4421 | Punctuation strings for multiple references. When marking is used in | |
4422 | the selection buffer to select several references, this variable | |
4423 | associates the 3 marking characters @samp{,-+} with prefix strings to be | |
4424 | inserted into the buffer before the corresponding @code{\ref} macro. | |
4425 | This 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 |
4431 | Alist of reference styles. Each element is a list of the style name, | |
4432 | the name of the @LaTeX{} package associated with the style or @code{t} | |
4433 | for any package, and an alist of macros where the first entry of each | |
4434 | item is the reference macro and the second a key for selecting the macro | |
4435 | when the macro type is being prompted for. (See also | |
4436 | @code{reftex-ref-macro-prompt}.) The keys, represented as characters, | |
4437 | have to be unique. | |
4009494e GM |
4438 | @end defopt |
4439 | ||
4f595e15 RA |
4440 | @defopt reftex-ref-style-default-list |
4441 | List of reference styles to be activated by default. The order is | |
4442 | significant and controls the order in which macros can be cycled in the | |
4443 | buffer for selecting a label. The entries in the list have to match the | |
4444 | respective reference style names used in the variable | |
4445 | @code{reftex-ref-style-alist}. | |
4446 | @end defopt | |
4447 | ||
4448 | @defopt reftex-ref-macro-prompt | |
4449 | Controls if @code{reftex-reference} prompts for the reference macro. | |
4009494e GM |
4450 | @end defopt |
4451 | ||
4452 | @deffn Hook reftex-format-ref-function | |
4453 | If non-@code{nil}, should be a function which produces the string to | |
4454 | insert as a reference. Note that the insertion format can also be | |
4455 | changed with @code{reftex-label-alist}. This hook also is used by the | |
1df7defd | 4456 | special commands to insert, e.g., @code{\vref} and @code{\fref} |
4f595e15 RA |
4457 | references, so even if you set this, your setting will be ignored by the |
4458 | special 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 | |
4461 | return the string to insert into the buffer. | |
4009494e GM |
4462 | @end deffn |
4463 | ||
4464 | @defopt reftex-level-indent | |
4465 | Number of spaces to be used for indentation per section level. | |
4466 | @end defopt | |
4467 | ||
4468 | @defopt reftex-guess-label-type | |
4469 | Non-@code{nil} means, @code{reftex-reference} will try to guess the | |
4f595e15 | 4470 | label type. To do that, @RefTeX{} will look at the word before the |
4009494e | 4471 | cursor and compare it with the magic words given in |
4f595e15 | 4472 | @code{reftex-label-alist}. When it finds a match, @RefTeX{} will |
f99f1641 | 4473 | immediately offer the correct label menu; otherwise it will prompt you |
4f595e15 | 4474 | for a label type. If you set this variable to @code{nil}, @RefTeX{} |
4009494e GM |
4475 | will always prompt for a label type. |
4476 | @end defopt | |
4477 | ||
4478 | @deffn {Normal Hook} reftex-display-copied-context-hook | |
4479 | Normal Hook which is run before context is displayed anywhere. Designed | |
4480 | for @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. | |
4485 | The functions get two arguments, the buffer from where the command | |
4486 | started and a symbol indicating in what context the hook is | |
4487 | called. | |
4488 | @end deffn | |
4489 | ||
4490 | @deffn {Normal Hook} reftex-select-label-mode-hook | |
4491 | Normal 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 | |
4496 | The 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 | |
4510 | List of regular expressions to exclude files in | |
4511 | @code{\\bibliography@{..@}}. File names matched by any of these regexps | |
4512 | will 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 | 4518 | List of @BibTeX{} database files which should be used if none are specified. |
4009494e GM |
4519 | When @code{reftex-citation} is called from a document with neither |
4520 | a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} | |
4f595e15 RA |
4521 | environment, @RefTeX{} will scan these files instead. Intended for |
4522 | using @code{reftex-citation} in non-@LaTeX{} files. The files will be | |
4009494e GM |
4523 | searched along the BIBINPUTS or TEXBIB path. |
4524 | @end defopt | |
4525 | ||
4526 | @defopt reftex-sort-bibtex-matches | |
4f595e15 | 4527 | Sorting of the entries found in @BibTeX{} databases by reftex-citation. |
4009494e GM |
4528 | Possible values: |
4529 | @example | |
4530 | nil @r{Do not sort entries.} | |
4531 | author @r{Sort entries by author name.} | |
4532 | year @r{Sort entries by increasing year.} | |
4533 | reverse-year @r{Sort entries by decreasing year.} | |
4534 | @end example | |
4535 | @end defopt | |
4536 | ||
4537 | @defopt reftex-cite-format | |
4538 | The format of citations to be inserted into the buffer. It can be a | |
4539 | string, 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 | ||
4543 | If @code{reftex-cite-format} is a string, it will be used as the format. | |
4544 | In the format, the following percent escapes will be expanded. | |
4545 | ||
4546 | @table @code | |
4547 | @item %l | |
4f595e15 | 4548 | The @BibTeX{} label of the citation. |
4009494e GM |
4549 | @item %a |
4550 | List of author names, see also @code{reftex-cite-punctuation}. | |
4551 | @item %2a | |
4552 | Like %a, but abbreviate more than 2 authors like Jones et al. | |
4553 | @item %A | |
4554 | First author name only. | |
4555 | @item %e | |
4556 | Works like @samp{%a}, but on list of editor names. (@samp{%2e} and | |
4557 | @samp{%E} work a well). | |
4558 | @end table | |
4559 | ||
4f595e15 | 4560 | It 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 | |
4572 | Usually, only @samp{%l} is needed. The other stuff is mainly for the | |
4573 | echo area display, and for @code{(setq reftex-comment-citations t)}. | |
4574 | ||
4575 | @samp{%<} as a special operator kills punctuation and space around it | |
4576 | after the string has been formatted. | |
4577 | ||
4578 | A pair of square brackets indicates an optional argument, and RefTeX | |
4579 | will prompt for the values of these arguments. | |
4580 | ||
4f595e15 | 4581 | Beware that all this only works with @BibTeX{} database files. When |
4009494e GM |
4582 | citations are made from the @code{\bibitems} in an explicit |
4583 | @code{thebibliography} environment, only @samp{%l} is available. | |
4584 | ||
4585 | If @code{reftex-cite-format} is an alist of characters and strings, the | |
4586 | user will be prompted for a character to select one of the possible | |
4587 | format strings. | |
4588 | ||
4589 | In 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 | |
4592 | are 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 | |
4598 | If non-@code{nil}, should be a function which produces the string to | |
4599 | insert as a citation. Note that the citation format can also be changed | |
4600 | with the variable @code{reftex-cite-format}. The function will be | |
4601 | called with two arguments, the @var{citation-key} and the | |
4602 | @var{default-format} (taken from @code{reftex-cite-format}). It should | |
4603 | return the string to insert into the buffer. | |
4604 | @end deffn | |
4605 | ||
4606 | @defopt reftex-cite-prompt-optional-args | |
4607 | Non-@code{nil} means, prompt for empty optional arguments in cite macros. | |
4608 | When an entry in @code{reftex-cite-format} ist given with square brackets to | |
4609 | indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can | |
4610 | prompt for values. Possible values are: | |
4611 | @example | |
4612 | nil @r{Never prompt for optional arguments} | |
4613 | t @r{Always prompt} | |
4614 | maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example | |
4615 | Unnecessary empty optional arguments are removed before insertion into | |
4616 | the buffer. See @code{reftex-cite-cleanup-optional-args}. | |
4617 | @end defopt | |
4618 | ||
4619 | @defopt reftex-cite-cleanup-optional-args | |
4620 | Non-@code{nil} means, remove empty optional arguments from cite macros | |
4621 | if possible. | |
4622 | @end defopt | |
4623 | ||
4624 | @defopt reftex-comment-citations | |
4625 | Non-@code{nil} means add a comment for each citation describing the full | |
4626 | entry. The comment is formatted according to | |
4627 | @code{reftex-cite-comment-format}. | |
4628 | @end defopt | |
4629 | ||
4630 | @defopt reftex-cite-comment-format | |
4631 | Citation format used for commented citations. Must @emph{not} contain | |
4632 | @samp{%l}. See the variable @code{reftex-cite-format} for possible | |
4633 | percent escapes. | |
4634 | @end defopt | |
4635 | ||
4636 | @defopt reftex-cite-punctuation | |
4637 | Punctuation for formatting of name lists in citations. This is a list | |
4638 | of 3 strings. | |
4639 | @enumerate | |
4640 | @item | |
4641 | normal names separator, like @samp{, } in Jones, Brown and Miller | |
4642 | @item | |
4643 | final names separator, like @samp{ and } in Jones, Brown and Miller | |
4644 | @item | |
4645 | The @samp{et al.} string, like @samp{ @{\it et al.@}} in | |
4646 | Jones @{\it et al.@} | |
4647 | @end enumerate | |
4648 | @end defopt | |
4649 | ||
4650 | @deffn {Normal Hook} reftex-select-bib-mode-hook | |
4651 | Normal 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 | |
4656 | The 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 |
4661 | String used to separate several keys in a single @samp{\\cite} macro. | |
4662 | Per default this is @samp{","} but if you often have to deal with a lot | |
4663 | of entries and need to break the macro across several lines you might | |
4664 | want to change it to @samp{", "}. | |
4665 | @end defopt | |
4666 | ||
4667 | @defopt reftex-create-bibtex-header | |
4668 | Header to insert in BibTeX files generated by | |
4669 | @code{reftex-create-bibtex-file}. | |
4670 | @end defopt | |
4671 | ||
4672 | @defopt reftex-create-bibtex-footer | |
4673 | Footer 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 | |
4684 | Non-@code{nil} means, index entries are parsed as well. Index support | |
4685 | is resource intensive and the internal structure holding the parsed | |
4686 | information can become quite big. Therefore it can be turned off. When | |
4687 | this is @code{nil} and you execute a command which requires index | |
4688 | support, you will be asked for confirmation to turn it on and rescan the | |
4689 | document. | |
4690 | @end defopt | |
4691 | ||
4692 | @defopt reftex-index-special-chars | |
4693 | List of special characters in index entries, given as strings. These | |
4694 | correspond 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 | |
4699 | List of macros which define index entries. The structure of each entry | |
4700 | is | |
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, | |
4706 | as for example in @samp{\index[]@{*@}}. Use square brackets to denote | |
4707 | optional 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} | |
4710 | are reserved for the default index and the glossary. Other indices can | |
4711 | be defined as well. If this is an integer, the Nth argument of the | |
4712 | macro holds the index tag. | |
4713 | ||
4714 | @var{key} is a character which is used to identify the macro for input | |
4715 | with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are | |
4716 | reserved for default index and glossary. | |
4717 | ||
4718 | @var{prefix} can be a prefix which is added to the @var{key} part of the | |
4719 | index entry. If you have a macro | |
4720 | @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix | |
4721 | should be @samp{Molecules!}. | |
4722 | ||
4723 | @var{exclude} can be a function. If this function exists and returns a | |
4724 | non-@code{nil} value, the index entry at point is ignored. This was | |
4725 | implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts | |
4f595e15 | 4726 | in the @LaTeX{}2e @code{index} package. |
4009494e GM |
4727 | |
4728 | @var{repeat}, if non-@code{nil}, means the index macro does not typeset | |
4729 | the entry in the text, so that the text has to be repeated outside the | |
4730 | index macro. Needed for @code{reftex-index-selection-or-word} and for | |
4731 | indexing from the phrase buffer. | |
4732 | ||
4733 | The final entry may also be a symbol. It must have an association in | |
4734 | the variable @code{reftex-index-macros-builtin} to specify the main | |
4735 | indexing package you are using. Valid values are currently | |
4736 | @example | |
f99f1641 | 4737 | default @r{The @LaTeX{} default; unnecessary to specify this one} |
4009494e GM |
4738 | multind @r{The multind.sty package} |
4739 | index @r{The index.sty package} | |
4740 | index-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 |
4743 | Note that @AUCTeX{} sets these things internally for @RefTeX{} as well, |
4744 | so with a sufficiently new version of @AUCTeX{}, you should not set the | |
4009494e GM |
4745 | package here. |
4746 | @end defopt | |
4747 | ||
4748 | @defopt reftex-index-default-macro | |
4749 | The default index macro for @code{reftex-index-selection-or-word}. | |
4750 | This 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 |
4758 | TAG argument of the index macro is optional, the TAG argument will be |
4759 | omitted. | |
4760 | @end defopt | |
4761 | ||
4762 | @defopt reftex-index-default-tag | |
4763 | Default index tag. When working with multiple indexes, RefTeX queries | |
4764 | for an index tag when creating index entries or displaying a specific | |
4765 | index. This variable controls the default offered for these queries. | |
4766 | The default can be selected with @key{RET} during selection or | |
4767 | completion. Valid values of this variable are: | |
4768 | @example | |
4769 | nil @r{Do not provide a default index} | |
1df7defd | 4770 | "tag" @r{The default index tag given as a string, e.g., "idx"} |
4009494e GM |
4771 | last @r{The last used index tag will be offered as default} |
4772 | @end example | |
4773 | @end defopt | |
4774 | ||
4775 | @defopt reftex-index-math-format | |
4776 | Format 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 |
4778 | the index key copied from the buffer is processed with this format |
4779 | string through the @code{format} function. This can be used to add the | |
1df7defd | 4780 | math 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 | |
4785 | File extension for the index phrase file. This extension will be added | |
4786 | to the base name of the master file. | |
4787 | @end defopt | |
4788 | ||
4789 | @defopt reftex-index-phrases-logical-and-regexp | |
4790 | Regexp matching the @samp{and} operator for index arguments in phrases | |
4791 | file. When several index arguments in a phrase line are separated by | |
4792 | this operator, each part will generate an index macro. So each match of | |
4793 | the search phrase will produce @emph{several} different index entries. | |
4794 | Make sure this does no match things which are not separators. This | |
4795 | logical @samp{and} has higher priority than the logical @samp{or} | |
4796 | specified in @code{reftex-index-phrases-logical-or-regexp}. | |
4797 | @end defopt | |
4798 | ||
4799 | @defopt reftex-index-phrases-logical-or-regexp | |
4800 | Regexp matching the @samp{or} operator for index arguments in phrases | |
4801 | file. When several index arguments in a phrase line are separated by | |
4802 | this operator, the user will be asked to select one of them at each | |
4803 | match of the search phrase. The first index arg will be the default. A | |
4804 | number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make | |
4805 | sure this does no match things which are not separators. The logical | |
4806 | @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} | |
4807 | has higher priority than this logical @samp{or}. | |
4808 | @end defopt | |
4809 | ||
4810 | @defopt reftex-index-phrases-search-whole-words | |
4811 | Non-@code{nil} means phrases search will look for whole words, not subwords. | |
4812 | This works by requiring word boundaries at the beginning and end of | |
4813 | the search string. When the search phrase already has a non-word-char | |
4814 | at one of these points, no word boundary is required there. | |
4815 | @end defopt | |
4816 | ||
4817 | @defopt reftex-index-phrases-case-fold-search | |
4818 | Non-@code{nil} means, searching for index phrases will ignore | |
4819 | case. | |
4820 | @end defopt | |
4821 | ||
4822 | @defopt reftex-index-verify-function | |
4823 | A function which is called at each match during global indexing. | |
4824 | If the function returns nil, the current match is skipped. | |
4825 | @end defopt | |
4826 | ||
4827 | @defopt reftex-index-phrases-skip-indexed-matches | |
4828 | Non-@code{nil} means, skip matches which appear to be indexed already. | |
4829 | When doing global indexing from the phrases buffer, searches for some | |
4830 | phrases may match at places where that phrase was already indexed. In | |
4831 | particular when indexing an already processed document again, this | |
4832 | will 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 |
4834 | index macro is directly before or after the phrase. If that is the |
4835 | case, that match will be ignored. | |
4836 | @end defopt | |
4837 | ||
4838 | @defopt reftex-index-phrases-wrap-long-lines | |
4839 | Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. | |
f99f1641 | 4840 | Inserting indexing commands in a line makes the line longer, often |
4009494e GM |
4841 | so long that it does not fit onto the screen. When this variable is |
4842 | non-@code{nil}, newlines will be added as necessary before and/or after the | |
4843 | indexing command to keep lines short. However, the matched text | |
4844 | phrase and its index command will always end up on a single line. | |
4845 | @end defopt | |
4846 | ||
4847 | @defopt reftex-index-phrases-sort-prefers-entry | |
4848 | Non-@code{nil} means when sorting phrase lines, the explicit index entry | |
4849 | is used. Phrase lines in the phrases buffer contain a search phrase, and | |
4850 | sorting is normally based on these. Some phrase lines also have | |
4851 | an explicit index argument specified. When this variable is | |
4852 | non-@code{nil}, the index argument will be used for sorting. | |
4853 | @end defopt | |
4854 | ||
4855 | @defopt reftex-index-phrases-sort-in-blocks | |
4856 | Non-@code{nil} means, empty and comment lines separate phrase buffer | |
4857 | into blocks. Sorting will then preserve blocks, so that lines are | |
4858 | re-arranged only within blocks. | |
4859 | @end defopt | |
4860 | ||
4861 | @defopt reftex-index-phrases-map | |
4862 | Keymap for the Index Phrases buffer. | |
4863 | @end defopt | |
4864 | ||
4865 | @defopt reftex-index-phrases-mode-hook | |
4866 | Normal 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 | |
4871 | The letters which denote sections in the index. Usually these are all | |
4872 | capital letters. Don't use any downcase letters. Order is not | |
4873 | significant, the index will be sorted by whatever the sort function | |
4f595e15 | 4874 | thinks is correct. In addition to these letters, @RefTeX{} will |
4009494e GM |
4875 | create a group @samp{!} which contains all entries sorted below the |
4876 | lowest specified letter. In the @file{*Index*} buffer, pressing any of | |
4877 | these capital letters or @kbd{!} will jump to that section. | |
4878 | @end defopt | |
4879 | ||
4880 | @defopt reftex-index-include-context | |
4881 | Non-@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 | |
4887 | Non-@code{nil} means, point in @file{*Index*} buffer will cause other | |
4888 | window to follow. The other window will show the corresponding part of | |
4889 | the document. This flag can be toggled from within the @file{*Index*} | |
4890 | buffer with the @kbd{f} key. | |
4891 | @end defopt | |
4892 | ||
4893 | @deffn Keymap reftex-index-map | |
4894 | The 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 | |
4904 | Macros which can be used for the display of cross references. | |
4905 | This is used when `reftex-view-crossref' is called with point in an | |
4906 | argument of a macro. Note that crossref viewing for citations, | |
4907 | references (both ways) and index entries is hard-coded. This variable | |
4908 | is only to configure additional structures for which crossreference | |
4909 | viewing 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 | |
4914 | regexp used to search for cross references. @samp{%s} in this regexp is | |
4915 | replaced with the macro argument at point. @var{highlight} is an | |
4916 | integer indicating which subgroup of the match should be highlighted. | |
4917 | @end defopt | |
4918 | ||
4919 | @defopt reftex-auto-view-crossref | |
4920 | Non-@code{nil} means, initially turn automatic viewing of crossref info | |
4921 | on. Automatic viewing of crossref info normally uses the echo area. | |
4922 | Whenever point is idle for more than @code{reftex-idle-time} seconds on | |
4923 | the argument of a @code{\ref} or @code{\cite} macro, and no other | |
4924 | message is being displayed, the echo area will display information about | |
4925 | that 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 | |
4927 | display. This feature can be turned on and off from the menu | |
4928 | (Ref->Options). | |
4929 | @end defopt | |
4930 | ||
4931 | @defopt reftex-idle-time | |
4932 | Time (secs) Emacs has to be idle before automatic crossref display | |
4933 | or toc recentering is done. | |
4934 | @end defopt | |
4935 | ||
4936 | @defopt reftex-cite-view-format | |
4937 | Citation format used to display citation info in the message area. See | |
4938 | the variable @code{reftex-cite-format} for possible percent | |
4939 | escapes. | |
4940 | @end defopt | |
4941 | ||
4942 | @defopt reftex-revisit-to-echo | |
4943 | Non-@code{nil} means, automatic citation display will revisit files if | |
4944 | necessary. When nil, citation display in echo area will only be active | |
4945 | for 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 |
4947 | buffers. |
4948 | @end defopt | |
4949 | ||
4950 | @defopt reftex-cache-cite-echo | |
4951 | Non-@code{nil} means, the information displayed in the echo area for | |
4952 | cite macros (see variable @code{reftex-auto-view-crossref}) is cached and | |
4953 | saved along with the parsing information. The cache survives document | |
4954 | scans. 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 | 4963 | List of specifications how to retrieve the search path for @TeX{} files. |
4009494e GM |
4964 | Several entries are possible. |
4965 | @itemize @minus | |
4966 | @item | |
4967 | If an element is the name of an environment variable, its content is | |
4968 | used. | |
4969 | @item | |
4970 | If an element starts with an exclamation mark, it is used as a command | |
4971 | to retrieve the path. A typical command with the kpathsearch library | |
4972 | would be @w{@code{"!kpsewhich -show-path=.tex"}}. | |
4973 | @item | |
4974 | Otherwise the element itself is interpreted as a path. | |
4975 | @end itemize | |
4976 | Multiple directories can be separated by the system dependent | |
4977 | @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will | |
4978 | be expanded recursively. See also @code{reftex-use-external-file-finders}. | |
4979 | @end defopt | |
4980 | ||
4981 | @defopt reftex-bibpath-environment-variables | |
4f595e15 | 4982 | List of specifications how to retrieve the search path for @BibTeX{} |
4009494e GM |
4983 | files. Several entries are possible. |
4984 | @itemize @minus | |
4985 | @item | |
4986 | If an element is the name of an environment variable, its content is | |
4987 | used. | |
4988 | @item | |
4989 | If an element starts with an exclamation mark, it is used as a command | |
4990 | to retrieve the path. A typical command with the kpathsearch library | |
4991 | would be @w{@code{"!kpsewhich -show-path=.bib"}}. | |
4992 | @item | |
4993 | Otherwise the element itself is interpreted as a path. | |
4994 | @end itemize | |
4995 | Multiple directories can be separated by the system dependent | |
4996 | @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will | |
4997 | be expanded recursively. See also @code{reftex-use-external-file-finders}. | |
4998 | @end defopt | |
4999 | ||
5000 | @defopt reftex-file-extensions | |
5001 | Association list with file extensions for different file types. | |
5002 | This 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 | |
5009 | When a files is searched and it does not have any of the valid extensions, | |
5010 | we try the default extension first, and then the naked file name. | |
5011 | @end defopt | |
5012 | ||
5013 | @defopt reftex-search-unrecursed-path-first | |
5014 | Non-@code{nil} means, search all specified directories before trying | |
5015 | recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, | |
5016 | then @samp{/tex/}, and then all subdirectories of @samp{./}. If this | |
5017 | option is @code{nil}, the subdirectories of @samp{./} are searched | |
f99f1641 | 5018 | before @samp{/tex/}. This is mainly for speed; most of the time the |
4009494e | 5019 | recursive path is for the system files and not for the user files. Set |
4f595e15 | 5020 | this to @code{nil} if the default makes @RefTeX{} finding files with |
4009494e GM |
5021 | equal names in wrong sequence. |
5022 | @end defopt | |
5023 | ||
5024 | @defopt reftex-use-external-file-finders | |
5025 | Non-@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 |
5028 | database files. With this option turned on, it calls an external |
5029 | program specified in the option @code{reftex-external-file-finders} | |
5030 | instead. 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 | |
5036 | Association list with external programs to call for finding files. Each | |
5037 | entry is a cons cell @w{@code{(@var{type} . @var{program})}}. | |
5038 | @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a | |
5039 | string 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 | |
5041 | that these commands will be executed directly, not via a shell. Only | |
5042 | relevant when @code{reftex-use-external-file-finders} is | |
5043 | non-@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 | |
5053 | Non-@code{nil} means, keep buffers created for parsing and lookup. | |
4f595e15 | 5054 | @RefTeX{} sometimes needs to visit files related to the current |
4009494e GM |
5055 | document. We distinguish files visited for |
5056 | @table @asis | |
5057 | @item PARSING | |
5058 | Parts of a multifile document loaded when (re)-parsing the | |
5059 | document. | |
5060 | @item LOOKUP | |
4f595e15 | 5061 | @BibTeX{} database files and @TeX{} files loaded to find a reference, to |
4009494e GM |
5062 | display label context, etc. |
5063 | @end table | |
5064 | The created buffers can be kept for later use, or be thrown away | |
5065 | immediately after use, depending on the value of this variable: | |
5066 | ||
5067 | @table @code | |
5068 | @item nil | |
5069 | Throw away as much as possible. | |
5070 | @item t | |
5071 | Keep everything. | |
5072 | @item 1 | |
5073 | Throw away buffers created for parsing, but keep the ones created for | |
5074 | lookup. | |
5075 | @end table | |
5076 | ||
5077 | If a buffer is to be kept, the file is visited normally (which is | |
5078 | potentially slow but will happen only once). If a buffer is to be thrown | |
5079 | away, 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 | |
5084 | Non-@code{nil} means do initializations even when visiting file | |
4f595e15 | 5085 | temporarily. When @code{nil}, @RefTeX{} may turn off find-file hooks and |
4009494e GM |
5086 | other stuff to briefly visit a file. When @code{t}, the full default |
5087 | initializations are done (@code{find-file-hook} etc.). Instead of | |
5088 | @code{t} or @code{nil}, this variable may also be a list of hook | |
5089 | functions to do a minimal initialization. | |
5090 | @end defopt | |
5091 | ||
5092 | @defopt reftex-no-include-regexps | |
5093 | List of regular expressions to exclude certain input files from parsing. | |
5094 | If the name of a file included via @code{\include} or @code{\input} is | |
5095 | matched by any of the regular expressions in this list, that file is not | |
4f595e15 | 5096 | parsed by @RefTeX{}. |
4009494e GM |
5097 | @end defopt |
5098 | ||
5099 | @defopt reftex-enable-partial-scans | |
5100 | Non-@code{nil} means, re-parse only 1 file when asked to re-parse. | |
4f595e15 | 5101 | Re-parsing is normally requested with a @kbd{C-u} prefix to many @RefTeX{} |
4009494e GM |
5102 | commands, 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, | |
5104 | or the file associated with the label or section heading near point in a | |
5105 | menu. Requesting re-parsing of an entire multifile document then | |
5106 | requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in | |
5107 | menus. | |
5108 | @end defopt | |
5109 | ||
5110 | @defopt reftex-save-parse-info | |
5111 | Non-@code{nil} means, save information gathered with parsing in files. | |
5112 | The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is | |
5113 | used to save the information. When this variable is @code{t}, | |
5114 | @itemize @minus | |
5115 | @item | |
5116 | accessing the parsing information for the first time in an editing | |
5117 | session will read that file (if available) instead of parsing the | |
5118 | document. | |
5119 | @item | |
5120 | exiting Emacs or killing a buffer in reftex-mode will cause a new | |
5121 | version of the file to be written. | |
5122 | @end itemize | |
5123 | @end defopt | |
5124 | ||
5125 | @defopt reftex-parse-file-extension | |
5126 | File extension for the file in which parser information is stored. | |
5127 | This extension is added to the base name of the master file. | |
5128 | @end defopt | |
5129 | ||
5130 | @defopt reftex-allow-automatic-rescan | |
4f595e15 | 5131 | Non-@code{nil} means, @RefTeX{} may rescan the document when this seems |
4009494e GM |
5132 | necessary. Applies (currently) only in rare cases, when a new label |
5133 | cannot be placed with certainty into the internal label list. | |
5134 | @end defopt | |
5135 | ||
5136 | @defopt reftex-use-multiple-selection-buffers | |
5137 | Non-@code{nil} means use a separate selection buffer for each label | |
5138 | type. These buffers are kept from one selection to the next and need | |
f99f1641 | 5139 | not be created for each use, so the menu generally comes up faster. |
4009494e GM |
5140 | The selection buffers will be erased (and therefore updated) |
5141 | automatically when new labels in its category are added. See the | |
5142 | variable @code{reftex-auto-update-selection-buffers}. | |
5143 | @end defopt | |
5144 | ||
5145 | @defopt reftex-auto-update-selection-buffers | |
5146 | Non-@code{nil} means, selection buffers will be updated automatically. | |
5147 | When a new label is defined with @code{reftex-label}, all selection | |
5148 | buffers associated with that label category are emptied, in order to | |
5149 | force an update upon next use. When @code{nil}, the buffers are left | |
5150 | alone and have to be updated by hand, with the @kbd{g} key from the | |
5151 | label selection process. The value of this variable will only have any | |
5152 | effect when @code{reftex-use-multiple-selection-buffers} is | |
5153 | non-@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 | |
5162 | Non-@code{nil} means, use fonts in label menu and on-the-fly help. | |
5163 | Font-lock must be loaded as well to actually get fontified | |
5164 | display. After changing this option, a rescan may be necessary to | |
5165 | activate it. | |
5166 | @end defopt | |
5167 | ||
5168 | @defopt reftex-refontify-context | |
5169 | Non-@code{nil} means, re-fontify the context in the label menu with | |
5170 | font-lock. This slightly slows down the creation of the label menu. It | |
5171 | is only necessary when you definitely want the context fontified. | |
5172 | ||
5173 | This option may have 3 different values: | |
5174 | @table @code | |
5175 | @item nil | |
5176 | Never refontify. | |
5177 | @item t | |
5178 | Always refontify. | |
5179 | @item 1 | |
1df7defd | 5180 | Refontify when necessary, e.g., with old versions of the x-symbol |
4009494e GM |
5181 | package. |
5182 | @end table | |
5183 | The option is ignored when @code{reftex-use-fonts} is @code{nil}. | |
5184 | @end defopt | |
5185 | ||
5186 | @defopt reftex-highlight-selection | |
5187 | Non-@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 | |
5190 | keys in the selection and @file{*toc*} buffers act on. However, if you | |
5191 | mainly use the mouse to select an item, you may find it nice to have | |
5192 | mouse-triggered highlighting @emph{instead} or @emph{as well}. The | |
5193 | variable may have one of these values: | |
5194 | ||
5195 | @example | |
5196 | nil @r{No highlighting.} | |
5197 | cursor @r{Highlighting is cursor driven.} | |
5198 | mouse @r{Highlighting is mouse driven.} | |
5199 | both @r{Both cursor and mouse trigger highlighting.} | |
5200 | @end example | |
5201 | ||
5202 | Changing this variable requires to rebuild the selection and *toc* | |
5203 | buffers to become effective (keys @kbd{g} or @kbd{r}). | |
5204 | @end defopt | |
5205 | ||
5206 | @defopt reftex-cursor-selected-face | |
5207 | Face name to highlight cursor selected item in toc and selection buffers. | |
5208 | See also the variable @code{reftex-highlight-selection}. | |
5209 | @end defopt | |
5210 | @defopt reftex-mouse-selected-face | |
5211 | Face name to highlight mouse selected item in toc and selection buffers. | |
5212 | See also the variable @code{reftex-highlight-selection}. | |
5213 | @end defopt | |
5214 | @defopt reftex-file-boundary-face | |
5215 | Face name for file boundaries in selection buffer. | |
5216 | @end defopt | |
5217 | @defopt reftex-label-face | |
5218 | Face name for labels in selection buffer. | |
5219 | @end defopt | |
5220 | @defopt reftex-section-heading-face | |
5221 | Face name for section headings in toc and selection buffers. | |
5222 | @end defopt | |
5223 | @defopt reftex-toc-header-face | |
5224 | Face name for the header of a toc buffer. | |
5225 | @end defopt | |
5226 | @defopt reftex-bib-author-face | |
5227 | Face name for author names in bib selection buffer. | |
5228 | @end defopt | |
5229 | @defopt reftex-bib-year-face | |
5230 | Face name for year in bib selection buffer. | |
5231 | @end defopt | |
5232 | @defopt reftex-bib-title-face | |
5233 | Face name for article title in bib selection buffer. | |
5234 | @end defopt | |
5235 | @defopt reftex-bib-extra-face | |
5236 | Face name for bibliographic information in bib selection buffer. | |
5237 | @end defopt | |
5238 | @defopt reftex-select-mark-face | |
5239 | Face name for marked entries in the selection buffers. | |
5240 | @end defopt | |
5241 | @defopt reftex-index-header-face | |
5242 | Face name for the header of an index buffer. | |
5243 | @end defopt | |
5244 | @defopt reftex-index-section-face | |
5245 | Face name for the start of a new letter section in the index. | |
5246 | @end defopt | |
5247 | @defopt reftex-index-tag-face | |
5248 | Face name for index names (for multiple indices). | |
5249 | @end defopt | |
5250 | @defopt reftex-index-face | |
5251 | Face 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 | |
5259 | Non-@code{nil} means, make additional key bindings on startup. These | |
5260 | extra bindings are located in the users @samp{C-c letter} | |
5261 | map. @xref{Key Bindings}. | |
5262 | @end defopt | |
5263 | ||
5264 | @defopt reftex-plug-into-AUCTeX | |
4f595e15 RA |
5265 | Plug-in flags for @AUCTeX{} interface. This variable is a list of |
5266 | 5 boolean flags. When a flag is non-@code{nil}, @RefTeX{} | |
4009494e GM |
5267 | will |
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 | ||
5277 | You may also set the variable itself to t or nil in order to turn all | |
5278 | options on or off, respectively.@* | |
5279 | Supplying labels in new sections and environments applies when creating | |
5280 | sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* | |
5281 | Supplying macro arguments applies when you insert such a macro | |
5282 | interactively with @kbd{C-c @key{RET}}.@* | |
4f595e15 | 5283 | See the @AUCTeX{} documentation for more information. |
4009494e GM |
5284 | @end defopt |
5285 | ||
5286 | @defopt reftex-revisit-to-follow | |
5287 | Non-@code{nil} means, follow-mode will revisit files if necessary. | |
5288 | When nil, follow-mode will be suspended for stuff in unvisited files. | |
5289 | @end defopt | |
5290 | ||
5291 | @defopt reftex-allow-detached-macro-args | |
5292 | Non-@code{nil} means, allow arguments of macros to be detached by | |
5293 | whitespace. 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 | |
5295 | this will be the case even if @code{\bb} is defined with zero or one | |
5296 | argument. | |
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 | 5306 | The keymap for @RefTeX{} mode. |
4009494e GM |
5307 | @end deffn |
5308 | ||
5309 | @deffn {Normal Hook} reftex-load-hook | |
5310 | Normal hook which is being run when loading @file{reftex.el}. | |
5311 | @end deffn | |
5312 | ||
5313 | @deffn {Normal Hook} reftex-mode-hook | |
4f595e15 | 5314 | Normal hook which is being run when turning on @RefTeX{} mode. |
4009494e GM |
5315 | @end deffn |
5316 | ||
4f595e15 | 5317 | Furthermore, the four modes used for referencing labels, creating |
4009494e GM |
5318 | citations, the table of contents buffer and the phrases buffer have |
5319 | their own keymaps and mode hooks. See the respective sections. There | |
5320 | are many more hooks which are described in the relevant sections about | |
4f595e15 | 5321 | options for a specific part of @RefTeX{}. |
4009494e | 5322 | |
6d1962b3 | 5323 | @node Changes |
4009494e GM |
5324 | @chapter Changes |
5325 | @cindex Changes | |
5326 | ||
4f595e15 RA |
5327 | Here is a list of recent changes to @RefTeX{}. |
5328 | ||
5329 | @noindent @b{Version 4.33} | |
5330 | ||
5331 | @itemize @bullet | |
5332 | @item | |
5333 | Update to GPLv3. | |
5334 | @item | |
5335 | Parse files are created in a way that does not interfere with recentf | |
5336 | mode. | |
5337 | @end itemize | |
5338 | ||
5339 | @noindent @b{Version 4.32} | |
5340 | ||
5341 | @itemize @bullet | |
5342 | @item | |
5343 | First release by @AUCTeX{} project. | |
5344 | @item | |
5345 | Installation routine rewritten after structure of source package | |
5346 | changed. | |
5347 | @item | |
5348 | Activation of @RefTeX{} changed, so make sure you read the installation | |
5349 | instructions and remove obsolete cruft related to @RefTeX{} from your | |
5350 | init file. | |
5351 | @item | |
5352 | Fixed bug where point would end up in the wrong buffer when jumping | |
5353 | between several @LaTeX{} and phrases buffers. | |
5354 | @item | |
5355 | Fixed bug where @BibTeX{} keys with hyphens were parsed incorrectly. | |
5356 | @item | |
5357 | Some performance improvements. | |
5358 | @item | |
5359 | The separator used between multiple citations in a \cite macro can now | |
5360 | be 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 | |
5372 | Support for global incremental search. | |
5373 | @item | |
5374 | Some improvements for XEmacs compatibility. | |
5375 | @end itemize | |
5376 | ||
5377 | @noindent @b{Version 4.25} | |
5378 | @itemize @bullet | |
5379 | @item | |
5380 | Fixed 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 |
5387 | Inserting citation commands now prompts for optional arguments |
5388 | when 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 |
5392 | New option @code{reftex-trust-label-prefix}. Configure this variable | |
5393 | if you'd like RefTeX to base its classification of labels on prefixes. | |
5394 | This can speed-up document parsing, but may in some cases reduce the | |
5395 | quality of the context used by RefTeX to describe a label. | |
5396 | @item | |
5397 | Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} | |
5398 | is non-nil. | |
5399 | @item | |
5400 | Fixed bugs in indexing: Case-sensitive search, quotes before and/or | |
5401 | after words. Disabled indexing in comment lines. | |
5402 | @end itemize | |
5403 | ||
5404 | @noindent @b{Version 4.22} | |
5405 | @itemize @bullet | |
9858f6c3 | 5406 | @item |
4009494e GM |
5407 | New command @code{reftex-create-bibtex-file} to create a new database |
5408 | with all entries referenced in the current document. | |
5409 | @item | |
5410 | New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file | |
5411 | from 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 |
5417 | Renaming labels from the toc buffer with key @kbd{M-%}. |
5418 | @end itemize | |
5419 | ||
5420 | @noindent @b{Version 4.20} | |
5421 | @itemize @bullet | |
5422 | @item | |
5423 | Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in | |
5424 | the TOC buffer promote/demote the section at point or all sections in | |
5425 | the current region. | |
5426 | @item | |
5427 | New option @code{reftex-toc-split-windows-fraction} to set the size of | |
1df7defd | 5428 | the window used by the TOC@. This makes the old variable |
4009494e GM |
5429 | @code{reftex-toc-split-windows-horizontally-fraction} obsolete. |
5430 | @item | |
5431 | A dedicated frame can show the TOC with the current section | |
5432 | always automatically highlighted. The frame is created and | |
5433 | deleted from the toc buffer with the @kbd{d} key. | |
5434 | @end itemize | |
5435 | ||
5436 | @noindent @b{Version 4.19} | |
5437 | @itemize @bullet | |
5438 | @item | |
5439 | New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current | |
5440 | section in the TOC buffer without selecting the TOC window. | |
5441 | @item | |
5442 | Recentering happens automatically in idle time when the option | |
5443 | @code{reftex-auto-recenter-toc} is turned on. | |
5444 | @item | |
5445 | Fixed several bugs related to automatic cursor positioning in the TOC | |
5446 | buffer. | |
5447 | @item | |
5448 | The highlight in the TOC buffer stays when the focus moves to a | |
5449 | different window. | |
5450 | @item | |
5451 | New command `reftex-goto-label'. | |
5452 | @item | |
5453 | Part numbers are no longer included in chapter numbers, and a new | |
5454 | part 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 | |
5462 | search string. | |
5463 | @item | |
5464 | Simplified several regular expressions for speed. | |
5465 | @item | |
5466 | Better support for chapterbib. | |
5467 | @end itemize | |
5468 | ||
5469 | @noindent @b{Version 4.17} | |
5470 | @itemize @bullet | |
5471 | @item | |
5472 | The 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 | |
5476 | It is possible to specify a function which verifies an index match | |
5477 | during global indexing. See new option @code{reftex-index-verify-function}. | |
5478 | @item | |
5479 | The macros which input a file in LaTeX (like \input, \include) can | |
5480 | be configured. See new option @code{reftex-include-file-commands}. | |
5481 | @item | |
5482 | The macros which specify the bibliography file (like \bibliography) can | |
5483 | be configured. See new option @code{reftex-bibliography-commands}. | |
5484 | @item | |
5485 | The regular expression used to search for the \bibliography macro has | |
5486 | been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by | |
5487 | chapterbib. | |
5488 | @item | |
5489 | Small bug fixes. | |
5490 | @end itemize | |
5491 | ||
5492 | @noindent @b{Version 4.15} | |
5493 | @itemize @bullet | |
5494 | @item | |
5495 | Fixed bug with parsing of BibTeX files, when fields contain quotes or | |
5496 | unmatched parenthesis. | |
5497 | @item | |
5498 | Small bug fixes. | |
5499 | @item | |
5500 | Improved interaction with Emacs LaTeX mode. | |
5501 | @end itemize | |
5502 | ||
5503 | @noindent @b{Version 4.12} | |
5504 | @itemize @bullet | |
5505 | @item | |
5506 | Support for @file{bibentry} citation style. | |
5507 | @end itemize | |
5508 | ||
5509 | @noindent @b{Version 4.11} | |
5510 | @itemize @bullet | |
5511 | @item | |
5512 | Fixed 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 | |
5518 | Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict | |
5519 | with @file{reftex-vars.el} on DOS machines. | |
5520 | @item | |
5521 | New 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 | |
5530 | New option @code{reftex-toc-max-level} to limit the depth of the toc. | |
5531 | New key binding @kbd{t} in the @file{*toc*} buffer to change this | |
5532 | setting. | |
5533 | @item | |
5534 | RefTeX maintains an @file{Index Phrases} file in which phrases can be | |
5535 | collected. When the document is ready, RefTeX can search all | |
5536 | these phrases and assist indexing all matches. | |
5537 | @item | |
5538 | The variables @code{reftex-index-macros} and | |
5539 | @code{reftex-index-default-macro} have changed their syntax slightly. | |
5540 | The @var{repeat} parameter has move from the latter to the former. | |
5541 | Also calls to @code{reftex-add-index-macros} from AUCTeX style files | |
5542 | need to be adapted. | |
5543 | @item | |
5544 | The variable @code{reftex-section-levels} no longer contains the | |
5545 | default stuff which has been moved to a constant. | |
5546 | @item | |
5547 | Environments like theorems can be placed into the TOC by putting | |
5548 | entries 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 | |
5556 | of a sectioning command. | |
5557 | @item | |
5558 | Multiple @code{thebibliography} environments recognized. | |
5559 | @end itemize | |
5560 | ||
5561 | @noindent @b{Version 4.04} | |
5562 | @itemize @bullet | |
5563 | @item | |
5564 | New 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 | |
5570 | macros ending in @samp{refrange} are considered to contain references. | |
5571 | @item | |
5572 | Index entries made with @code{reftex-index-selection-or-word} in TeX | |
5573 | math mode automatically get enclosing @samp{$} to preserve math mode. See | |
5574 | new option @code{reftex-index-math-format}. Requires AUCTeX. | |
5575 | @end itemize | |
5576 | ||
5577 | @noindent @b{Version 4.01} | |
5578 | @itemize @bullet | |
5579 | @item | |
5580 | New command @code{reftex-index-globally} to index a word in many | |
5581 | places in the document. Also available from the index buffer with | |
5582 | @kbd{&}. | |
5583 | @item | |
5584 | The first item in a @code{reftex-label-alist} entry may now also be a parser | |
5585 | function 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 | |
5594 | RefTeX has been split into several smaller files which are autoloaded on | |
5595 | demand. | |
5596 | @item | |
5597 | Index support, along with many new options. | |
5598 | @item | |
5599 | The selection of keys for @code{\ref} and @code{\cite} now allows to | |
5600 | select multiple items by marking entries with the @kbd{m} key. | |
5601 | @item | |
5602 | Fancyref support. | |
5603 | @end itemize | |
5604 | ||
5605 | @noindent @b{Version 3.43} | |
5606 | @itemize @bullet | |
5607 | @item | |
5608 | Viewing cross-references generalized. Now works on @code{\label}, | |
5609 | @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of | |
5610 | these, and from BibTeX buffers. | |
5611 | @item | |
5612 | New option @code{reftex-view-crossref-extra}. | |
5613 | @item | |
5614 | Support for the additional sectioning commands @code{\addchap} and | |
5615 | @code{\addsec} which are defined in the LaTeX KOMA-Script classes. | |
5616 | @item | |
5617 | Files in @code{reftex-default-bibliography} will be searched along | |
5618 | @code{BIBINPUTS} path. | |
5619 | @item | |
5620 | Reading a parse file now checks consistency. | |
5621 | @end itemize | |
5622 | ||
5623 | @noindent @b{Version 3.42} | |
5624 | @itemize @bullet | |
5625 | @item | |
5626 | File search further refined. New option @code{reftex-file-extensions}. | |
5627 | @item | |
5628 | @file{*toc*} buffer can show the file boundaries of a multifile | |
5629 | document, all labels and associated context. New keys @kbd{i}, @kbd{l}, | |
5630 | and @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 | |
5638 | New 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 | |
5651 | to be on the macro argument. | |
5652 | @end itemize | |
5653 | ||
5654 | @noindent @b{Version 3.36} | |
5655 | @itemize @bullet | |
5656 | @item | |
5657 | New 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 | |
5663 | ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. | |
5664 | This 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 | |
5670 | Additional flag in @code{reftex-derive-label-parameters} do make only | |
5671 | lowercase labels (default @code{t}). | |
5672 | @item | |
5673 | All @file{.rel} files have a final newline to avoid queries. | |
5674 | @item | |
5675 | Single byte representations of accented European letters (ISO-8859-1) | |
5676 | are now valid in labels. | |
5677 | @end itemize | |
5678 | ||
5679 | @noindent @b{Version 3.33} | |
5680 | @itemize @bullet | |
5681 | @item | |
5682 | Multiple selection buffers are now hidden buffers (they start with a | |
5683 | SPACE). | |
5684 | @item | |
5685 | Fixed 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 | |
5691 | In @code{reftex-citation}, the regular expression used to scan BibTeX | |
5692 | files can be specified using completion on known citation keys. | |
5693 | @item | |
5694 | New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} | |
5695 | entries. | |
5696 | @item | |
5697 | New command @code{reftex-renumber-simple-labels} to renumber simple | |
5698 | labels like @samp{eq:13} sequentially through a document. | |
5699 | @end itemize | |
5700 | ||
5701 | @noindent @b{Version 3.28} | |
5702 | @itemize @bullet | |
5703 | @item | |
5704 | Auto view crossref for XEmacs uses @code{post-command-hook} to restart the | |
5705 | timer, since itimer restart is not reliable. | |
5706 | @item | |
5707 | Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. | |
5708 | @item | |
5709 | Expansion of recursive tex and bib path rewritten. | |
5710 | @item | |
4f595e15 | 5711 | Fixed problem where @RefTeX{} did not scan unsaved buffers. |
4009494e GM |
5712 | @item |
5713 | Fixed bug with section numbering after *-red sections. | |
5714 | @end itemize | |
5715 | ||
5716 | @noindent @b{Version 3.27} | |
5717 | @itemize @bullet | |
5718 | @item | |
5719 | Macros can define @emph{neutral} labels, just like @code{\label} | |
5720 | itself. | |
5721 | @item | |
5722 | New 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 | |
5730 | New hooks @code{reftex-translate-to-ascii-function}, | |
5731 | @code{reftex-string-to-label-function}. | |
5732 | @item | |
5733 | Made sure automatic crossref display will not visit/scan files. | |
5734 | @end itemize | |
5735 | ||
5736 | @noindent @b{Version 3.25} | |
5737 | @itemize @bullet | |
5738 | @item | |
5739 | Echoing of citation info caches the info for displayed entries. | |
5740 | New option @code{reftex-cache-cite-echo}. | |
5741 | @item | |
5742 | @kbd{M-x reftex-reset-mode} now also removes the file with parsing | |
5743 | info. | |
5744 | @item | |
5745 | Default of @code{reftex-revisit-to-follow} changed to nil. | |
5746 | @end itemize | |
5747 | ||
5748 | @noindent @b{Version 3.24} | |
5749 | @itemize @bullet | |
5750 | @item | |
5751 | New option @code{reftex-revisit-to-echo}. | |
5752 | @item | |
5753 | Interface with X-Symbol (>=2.6) is now complete and stable. | |
5754 | @item | |
5755 | Adapted to new outline, which uses overlays. | |
5756 | @item | |
5757 | File names in @code{\bibliography} may now have the @code{.bib} | |
5758 | extension. | |
5759 | @item | |
5760 | Fixed Bug with parsing "single file" from master file buffer. | |
5761 | @end itemize | |
5762 | ||
5763 | @noindent @b{Version 3.23} | |
5764 | @itemize @bullet | |
5765 | @item | |
5766 | Parse 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 | |
5769 | file. | |
5770 | @item | |
5771 | The cursor inside a @code{\ref} or @code{\cite} macro can now trigger | |
5772 | automatic display of crossref information in the echo area. See | |
5773 | variable @code{reftex-auto-view-crossref}. | |
5774 | @item | |
5775 | AUCTeX interface updates: | |
5776 | @itemize @minus | |
5777 | @item | |
4f595e15 | 5778 | AUCTeX 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 | 5786 | Settings added to @RefTeX{} via style files remain local. |
4009494e GM |
5787 | @end itemize |
5788 | @item | |
5789 | Fixed bug with @code{reftex-citation} in non-latex buffers. | |
5790 | @item | |
5791 | Fixed bug with syntax table and context refontification. | |
5792 | @item | |
5793 | Safety-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 | |
5799 | Fixed 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 | 5808 | New options for all faces used by @RefTeX{}. They're in the |
4009494e GM |
5809 | customization group @code{reftex-fontification-configurations}. |
5810 | @end itemize | |
5811 | ||
5812 | @noindent @b{Version 3.19} | |
5813 | @itemize @bullet | |
5814 | @item | |
5815 | Fixed bug with AUCTeX @code{TeX-master}. | |
5816 | @end itemize | |
5817 | ||
5818 | @noindent @b{Version 3.18} | |
5819 | @itemize @bullet | |
5820 | @item | |
5821 | The selection now uses a recursive edit, much like minibuffer input. | |
1df7defd | 5822 | This removes all restrictions during selection. E.g., you can now |
4009494e GM |
5823 | switch buffers at will, use the mouse etc. |
5824 | @item | |
5825 | New option @code{reftex-highlight-selection}. | |
5826 | @item | |
5827 | @kbd{mouse-2} can be used to select in selection and @file{*toc*} | |
5828 | buffers. | |
5829 | @item | |
5830 | Fixed some problems regarding the interaction with VIPER mode. | |
5831 | @item | |
5832 | Follow-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 | |
5840 | Additional bindings in selection and @file{*toc*} buffers. @kbd{g} | |
5841 | redefined. | |
5842 | @item | |
5843 | New command @code{reftex-save-all-document-buffers}. | |
5844 | @item | |
5845 | Magic word matching made more intelligent. | |
5846 | @item | |
5847 | Selection process can switch to completion (with @key{TAB}). | |
5848 | @item | |
5849 | @code{\appendix} is now recognized and influences section numbering. | |
5850 | @item | |
5851 | File commentary shortened considerably (use Info documentation). | |
5852 | @item | |
5853 | New option @code{reftex-no-include-regexps} to skip some include files. | |
5854 | @item | |
5855 | New option @code{reftex-revisit-to-follow}. | |
5856 | @end itemize | |
5857 | ||
5858 | @noindent @b{Version 3.16} | |
5859 | @itemize @bullet | |
5860 | @item | |
5861 | New hooks @code{reftex-format-label-function}, | |
5862 | @code{reftex-format-ref-function}, @code{reftex-format-cite-function}. | |
5863 | @item | |
5864 | TeXInfo documentation completed. | |
5865 | @item | |
5866 | Some restrictions in Label inserting and referencing removed. | |
5867 | @item | |
5868 | New variable @code{reftex-default-bibliography}. | |
5869 | @end itemize | |
5870 | ||
5871 | @noindent @b{Version 3.14} | |
5872 | @itemize @bullet | |
5873 | @item | |
5874 | Selection buffers can be kept between selections: this is faster. | |
5875 | See new variable @code{reftex-use-multiple-selection-buffers}. | |
5876 | @item | |
5877 | Prefix interpretation of reftex-view-crossref changed. | |
5878 | @item | |
5879 | Support for the @code{varioref} package (@kbd{v} key in selection | |
5880 | buffer). | |
5881 | @end itemize | |
5882 | ||
5883 | @noindent @b{Version 3.12} | |
5884 | @itemize @bullet | |
5885 | @item | |
5886 | There are 3 new keymaps for customization: @code{reftex-toc-map}, | |
5887 | @code{reftex-select-label-map}, @code{reftex-select-bib-map}. | |
5888 | @item | |
5889 | Refontification uses more standard font-lock stuff. | |
5890 | @item | |
5891 | When 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 | 5898 | Fixed bug which led to naked label in (e.g.@:) footnotes. |
4009494e GM |
5899 | @item |
5900 | Added scroll-other-window functions to RefTeX-Select. | |
5901 | @end itemize | |
5902 | ||
5903 | @noindent @b{Version 3.10} | |
5904 | @itemize @bullet | |
5905 | @item | |
5906 | Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. | |
5907 | @item | |
5908 | Removed unimportant code which caused OS/2 Emacs to crash. | |
5909 | @item | |
5910 | All 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 | |
5922 | Compatibility code now first checks for XEmacs feature. | |
5923 | @end itemize | |
5924 | ||
5925 | @noindent @b{Version 3.04} | |
5926 | @itemize @bullet | |
5927 | @item | |
5928 | Fixed BUG in the @emph{xr} support. | |
5929 | @end itemize | |
5930 | ||
5931 | @noindent @b{Version 3.03} | |
5932 | @itemize @bullet | |
5933 | @item | |
5934 | Support for the LaTeX package @code{xr}, for inter-document | |
5935 | references. | |
5936 | @item | |
5937 | A few (minor) Mule-related changes. | |
5938 | @item | |
5939 | Fixed bug which could cause @emph{huge} @file{.rel} files. | |
5940 | @item | |
5941 | Search 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 |
5949 | The new parser works without creating a master buffer. | |
5950 | @item | |
5951 | Rescanning can be limited to a part of a multifile document. | |
5952 | @item | |
5953 | Information 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 |
5957 | Macros may have white space and newlines between arguments. | |
5958 | @item | |
5959 | Multiple 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 |
5963 | packages like outline, folding, x-symbol, iso-cvt, isotex, etc. |
5964 | @item | |
5965 | All labeled environments discussed in @emph{The LaTeX Companion} by | |
5966 | Goossens, 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 | |
5973 | Label prefix expands % escapes with current file name and other stuff. | |
5974 | @item | |
5975 | Citation format now with % escapes. This is not backward | |
5976 | compatible! | |
5977 | @item | |
5978 | TEXINPUTS variable recognized when looking for input files. | |
5979 | @item | |
5980 | Context can be the nth argument of a macro. | |
5981 | @item | |
5982 | Searching in the select buffer is now possible (@kbd{C-s} and | |
5983 | @kbd{C-r}). | |
5984 | @item | |
5985 | Display and derive-label can use two different context methods. | |
5986 | @item | |
5987 | AMSmath @code{xalignat} and @code{xxalignat} added. | |
5988 | @end itemize | |
5989 | ||
5990 | @noindent @b{Version 2.14} | |
5991 | @itemize @bullet | |
5992 | @item | |
5993 | Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with | |
5994 | AUCTeX. | |
5995 | @end itemize | |
5996 | ||
5997 | @noindent @b{Version 2.11} | |
5998 | @itemize @bullet | |
5999 | @item | |
6000 | Submitted for inclusion to Emacs and XEmacs. | |
6001 | @end itemize | |
6002 | ||
6003 | @noindent @b{Version 2.07} | |
6004 | @itemize @bullet | |
6005 | @item | |
6006 | New 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 | |
6013 | Support for @file{custom.el}. | |
6014 | @item | |
6015 | New 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 | |
6022 | default environments. | |
6023 | @item | |
6024 | @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). | |
6025 | @item | |
6026 | New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, | |
6027 | @code{reftex-arg-cite}. | |
6028 | @item | |
6029 | Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is | |
6030 | required. | |
6031 | @item | |
6032 | @code{reftex-add-to-label-alist} (to be called from AUCTeX style | |
6033 | files). | |
6034 | @item | |
6035 | Finding context with a hook function. | |
6036 | @item | |
6037 | Sorting 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 | |
6044 | Labels can be derived from context (default for sections). | |
6045 | @item | |
6046 | Configuration of label insertion and label referencing revised. | |
6047 | @item | |
6048 | Crossref 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 | |
6056 | Support for @code{tex-main-file}, an analogue for | |
6057 | @code{TeX-master}. | |
6058 | @item | |
6059 | MS-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 | |
6071 | XEmacs port. | |
6072 | @end itemize | |
6073 | ||
6074 | @noindent @b{Version 1.04} | |
6075 | @itemize @bullet | |
6076 | @item | |
6077 | Macros as wrappers, AMSTeX support, delayed context parsing for | |
6078 | new labels. | |
6079 | @end itemize | |
6080 | @end ignore | |
6081 | ||
6082 | @noindent @b{Version 1.00} | |
6083 | @itemize @bullet | |
6084 | @item | |
6085 | released 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 |