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