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