1 ;;; reftex-vars.el --- configuration variables for RefTeX
3 ;; Copyright (C) 1997-1999, 2001-2013 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <dominik@science.uva.nl>
6 ;; Maintainer: auctex-devel@gnu.org
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 (defvar reftex-tables-dirty
)
27 (eval-when-compile (require 'cl
))
29 (defun reftex-set-dirty (symbol value
)
30 (setq reftex-tables-dirty t
)
33 ;; Define the two constants which are needed during compilation
36 (defconst reftex-label-alist-builtin
38 ;; Some aliases, mostly for backward compatibility
39 (Sideways "Alias for -->rotating" (rotating))
40 (AMSTeX "amsmath with eqref macro"
41 ((nil ?e nil
"~\\eqref{%s}")
44 ;; Individual package defaults
45 (amsmath "AMS-LaTeX math environments"
46 (("align" ?e nil nil eqnarray-like
)
47 ("gather" ?e nil nil eqnarray-like
)
48 ("multline" ?e nil nil t
)
49 ("flalign" ?e nil nil eqnarray-like
)
50 ("alignat" ?e nil nil alignat-like
)
51 ("xalignat" ?e nil nil alignat-like
)
52 ("xxalignat" ?e nil nil alignat-like
)
53 ("subequations" ?e nil nil t
)))
55 (endnotes "The \\endnote macro"
56 (("\\endnote[]{}" ?N
"en:" "~\\ref{%s}" 2
57 (regexp "endnotes?" "notes?" "Anmerkung\\(en\\)?" "Anm\\."))))
59 (fancybox "The Beqnarray environment"
60 (("Beqnarray" ?e nil nil eqnarray-like
)))
62 (floatfig "The floatingfigure environment"
63 (("floatingfigure" ?f nil nil caption
)))
65 (longtable "The longtable environment"
66 (("longtable" ?t nil nil caption
)))
68 (picinpar "The figwindow and tabwindow environments"
69 (("figwindow" ?f nil nil
1)
70 ("tabwindow" ?f nil nil
1)))
72 (rotating "Sidewaysfigure and table"
73 (("sidewaysfigure" ?f nil nil caption
)
74 ("sidewaystable" ?t nil nil caption
)))
76 (sidecap "CSfigure and SCtable"
77 (("SCfigure" ?f nil nil caption
)
78 ("SCtable" ?t nil nil caption
)))
80 (subfigure "Subfigure environments/macro"
81 (("subfigure" ?f nil nil caption
)
82 ("subfigure*" ?f nil nil caption
)
83 ("\\subfigure[]{}" ?f nil nil
1)))
85 (supertab "Supertabular environment"
86 (("supertabular" ?t nil nil
"\\tablecaption{")))
88 (wrapfig "The wrapfigure environment"
89 (("wrapfigure" ?f nil nil caption
)))
91 (ctable "The ctable package"
92 (("\\ctable[]{}{}{}" ?t
"tab:" "\\ref{%s}" 1 ("table" "Tabelle"))))
94 (listings "The listings package"
95 (("lstlisting" ?l
"lst:" "~\\ref{%s}" nil
(regexp "[Ll]isting"))))
97 (minted "The minted package"
98 (("minted" ?l
"lst:" "~\\ref{%s}" nil
(regexp "[Ll]isting"))))
100 ;; The LaTeX core stuff
101 (LaTeX "LaTeX default environments"
102 (("section" ?s
"%S" "~\\ref{%s}" (nil . t
)
103 (regexp "parts?" "chapters?" "chap\\." "sections?" "sect?\\."
104 "paragraphs?" "par\\."
105 "\\\\S" "\247" "Teile?" "Kapitel" "Kap\\." "Abschnitte?"
106 "appendi\\(x\\|ces\\)" "App\\." "Anh\"?ange?" "Anh\\."))
108 ("enumerate" ?i
"item:" "~\\ref{%s}" item
109 (regexp "items?" "Punkte?"))
111 ("equation" ?e
"eq:" "~(\\ref{%s})" t
112 (regexp "equations?" "eqs?\\." "eqn\\." "Gleichung\\(en\\)?" "Gl\\."))
113 ("eqnarray" ?e
"eq:" nil eqnarray-like
)
115 ("figure" ?f
"fig:" "~\\ref{%s}" caption
116 (regexp "figure?[sn]?" "figs?\\." "Abbildung\\(en\\)?" "Abb\\."))
117 ("figure*" ?f nil nil caption
)
119 ("table" ?t
"tab:" "~\\ref{%s}" caption
120 (regexp "tables?" "tab\\." "Tabellen?"))
121 ("table*" ?t nil nil caption
)
123 ("\\footnote[]{}" ?n
"fn:" "~\\ref{%s}" 2
124 (regexp "footnotes?" "Fussnoten?"))
126 ("any" ?\
" " "~\\ref{%s}" nil
)
128 ;; The label macro is hard coded, but it *could* be defined like this:
129 ;;("\\label{*}" nil nil nil nil)
131 "The default label environment descriptions.
132 Lower-case symbols correspond to a style file of the same name in the LaTeX
133 distribution. Mixed-case symbols are convenience aliases.")
135 (defconst reftex-cite-format-builtin
136 '((default "Default macro \\cite{%l}"
138 (natbib "The Natbib package"
139 ((?\C-m .
"\\cite[][]{%l}")
140 (?t .
"\\citet[][]{%l}")
141 (?T .
"\\citet*[][]{%l}")
142 (?p .
"\\citep[][]{%l}")
143 (?P .
"\\citep*[][]{%l}")
144 (?e .
"\\citep[e.g.][]{%l}")
145 (?s .
"\\citep[see][]{%l}")
146 (?a .
"\\citeauthor{%l}")
147 (?A .
"\\citeauthor*{%l}")
148 (?y .
"\\citeyear{%l}")
149 (?n .
"\\nocite{%l}")))
150 (amsrefs "The AMSRefs package"
151 ((?\C-m .
"\\cite{%l}")
155 (?T .
"\\ocites{%l}")
157 (?Y .
"\\ycites{%l}")
158 (?a .
"\\citeauthor{%l}")
159 (?A .
"\\citeauthory{%l}")
160 (?f .
"\\fullcite{%l}")
161 (?F .
"\\fullocite{%l}")
162 (?n .
"\\nocite{%l}")))
163 (jurabib "The Jurabib package"
164 ((?\C-m .
"\\cite{%l}")
165 (?c .
"\\cite[][]{%l}")
168 (?e .
"\\citep[e.g.][]{%l}")
169 (?s .
"\\citep[see][]{%l}")
170 (?u .
"\\fullcite{%l}")
171 (?i .
"\\citetitle{%l}")
172 (?a .
"\\citeauthor{%l}")
173 (?e .
"\\citefield{}{%l}")
174 (?y .
"\\citeyear{%l}")
175 (?f .
"\\footcite{%l}")
176 (?F .
"\\footcite[][]{%l}")
177 (?l .
"\\footfullcite{%l}")))
178 (bibentry "The Bibentry package"
180 (harvard "The Harvard package"
181 ((?\C-m .
"\\cite[]{%l}")
182 (?p .
"\\cite[]{%l}")
183 (?t .
"\\citeasnoun{%l}")
184 (?n .
"\\citeasnoun{%l}")
185 (?s .
"\\possessivecite{%l}")
186 (?e .
"\\citeaffixed{%l}{?}")
187 (?y .
"\\citeyear{%l}")
188 (?a .
"\\citename{%l}")))
189 (chicago "The Chicago package"
190 ((?\C-m .
"\\cite[]{%l}")
191 (?t .
"\\citeN[]{%l}")
192 (?T .
"\\shortciteN{%l}")
193 (?p .
"\\cite[]{%l}")
194 (?P .
"\\shortcite{%l}")
196 (?A .
"\\shortciteA{%l}")
197 (?y .
"\\citeyear{%l}")))
198 (astron "The Astron package"
199 ((?\C-m .
"\\cite[]{%l}")
200 (?p .
"\\cite[]{%l}" )
201 (?t .
"%2a (\\cite{%l})")))
202 (author-year "Do-it-yourself Author-year"
203 ((?\C-m .
"\\cite{%l}")
204 (?t .
"%2a (%y)\\nocite{%l}")
205 (?p .
"(%2a %y\\nocite{%l})")))
206 (locally "Full info in parenthesis"
207 "(%2a %y, %j %v, %P, %e: %b, %u, %s %<)")
210 ((?\C-m .
"\\cite[%l]")
211 (?s .
"\\cite[][%l]")
212 (?n .
"\\nocite[%l]")))
214 "Builtin versions of the citation format.
215 The following conventions are valid for all alist entries:
216 `?\C-m' should always point to a straight \\cite{%l} macro.
217 `?t' should point to a textual citation (citation as a noun).
218 `?p' should point to a parenthetical citation.")
220 (defconst reftex-index-macros-builtin
221 '((default "Default \\index and \\glossary macros"
222 (("\\index{*}" "idx" ?i
"" nil t
)
223 ("\\glossary{*}" "glo" ?g
"" nil t
)))
224 (multind "The multind.sty package"
225 (("\\index{}{*}" 1 ?i
"" nil t
)))
226 (index "The index.sty package"
227 (("\\index[]{*}" 1 ?i
"" nil t
)
228 ("\\index*[]{*}" 1 ?I
"" nil nil
)))
229 (Index-Shortcut "index.sty with \\shortindexingon"
230 (("\\index[]{*}" 1 ?i
"" nil t
)
231 ("\\index*[]{*}" 1 ?I
"" nil nil
)
232 ("^[]{*}" 1 ?^
"" texmathp t
)
233 ("_[]{*}" 1 ?_
"" texmathp nil
))))
234 "Builtin stuff for `reftex-index-macros'.
235 Lower-case symbols correspond to a style file of the same name in the LaTeX
236 distribution. Mixed-case symbols are convenience aliases.")
239 ;; Configuration Variables and User Options for RefTeX ------------------
242 "LaTeX label and citation support."
244 :link
'(url-link :tag
"Home Page"
245 "http://www.gnu.org/software/auctex/reftex.html")
246 :link
'(emacs-commentary-link :tag
"Commentary in reftex.el" "reftex.el")
247 :link
'(custom-manual "(reftex)Top")
252 ;; Table of contents configuration --------------------------------------
254 (defgroup reftex-table-of-contents-browser nil
255 "A multifile table of contents browser."
258 (defcustom reftex-include-file-commands
'("include" "input")
259 "LaTeX commands which input another file.
260 The file name is expected after the command, either in braces or separated
262 :group
'reftex-table-of-contents-browser
263 :type
'(repeat string
))
265 (defcustom reftex-max-section-depth
12
266 "Maximum depth of section levels in document structure.
267 The default in standard LaTeX is 7, but there are packages for
268 which this needs to be larger."
269 :group
'reftex-table-of-contents-browser
272 ;; LaTeX section commands and level numbers
273 (defcustom reftex-section-levels
279 ("subsubsection" .
4)
282 ("addchap" . -
1) ; KOMA-Script
283 ("addsec" . -
2) ; KOMA-Script
284 ;;; ("minisec" . -7) ; KOMA-Script
286 "Commands and levels used for defining sections in the document.
287 This is an alist with each element like (COMMAND-NAME . LEVEL).
288 The car of each cons cell is the name of the section macro (without
289 the backslash). The cdr is a number indicating its level. A negative
290 level means the same level as the positive value, but the section will
291 never get a number. The cdr may also be a function which will be called
292 to after the section-re matched to determine the level.
293 This list is also used for promotion and demotion of sectioning commands.
294 If you are using a document class which has several sets of sectioning
295 commands, promotion only works correctly if this list is sorted first
296 by set, then within each set by level. The promotion commands always
297 select the nearest entry with the correct new level."
298 :group
'reftex-table-of-contents-browser
299 :set
'reftex-set-dirty
301 (cons (string :tag
"sectioning macro" "")
303 (number :tag
"level " 0)
304 (symbol :tag
"function " my-level-func
)))))
306 (defcustom reftex-toc-max-level
100
307 "The maximum level of toc entries which will be included in the TOC.
308 Section headings with a bigger level will be ignored. In RefTeX, chapters
309 are level 1, sections are level 2 etc.
310 This variable can be changed from within the *toc* buffer with the `t' key."
311 :group
'reftex-table-of-contents-browser
314 (defcustom reftex-part-resets-chapter nil
315 "Non-nil means, \\part is like any other sectioning command.
316 This means, part numbers will be included in the numbering of chapters, and
317 chapter counters will be reset for each part.
318 When nil (the default), parts are special, do not reset the chapter counter
319 and also do not show up in chapter numbers."
320 :group
'reftex-table-of-contents-browser
324 (defcustom reftex-auto-recenter-toc
'frame
325 "Non-nil means, turn automatic recentering of *TOC* window on.
326 When active, the *TOC* window will always show the section you
327 are currently working in. Recentering happens whenever Emacs is idle for
328 more than `reftex-idle-time' seconds.
330 Value t means, turn on immediately when RefTeX gets started. Then,
331 recentering will work for any TOC window created during the session.
333 Value 'frame (the default) means, turn automatic recentering on only while the
334 dedicated TOC frame does exist, and do the recentering only in that frame. So
335 when creating that frame (with `d' key in an ordinary TOC window), the
336 automatic recentering is turned on. When the frame gets destroyed, automatic
337 recentering is turned off again.
339 This feature can be turned on and off from the menu
341 :group
'reftex-table-of-contents-browser
343 (const :tag
"never" nil
)
344 (const :tag
"always" t
)
345 (const :tag
"in dedicated frame only" frame
)))
347 (defcustom reftex-toc-split-windows-horizontally nil
348 "Non-nil means, create TOC window by splitting window horizontally."
349 :group
'reftex-table-of-contents-browser
352 (defcustom reftex-toc-split-windows-fraction
.3
353 "Fraction of the width or height of the frame to be used for TOC window.
354 See also `reftex-toc-split-windows-horizontally'."
355 :group
'reftex-table-of-contents-browser
358 (defvar reftex-toc-split-windows-horizontally-fraction
0.5
359 "This variable is obsolete, use `reftex-toc-split-windows-fraction' instead.")
361 (defcustom reftex-toc-keep-other-windows t
362 "Non-nil means, split the selected window to display the *toc* buffer.
363 This helps to keep the window configuration, but makes the *toc* small.
364 When nil, all other windows except the selected one will be deleted, so
365 that the *toc* window fills half the frame."
366 :group
'reftex-table-of-contents-browser
369 (defcustom reftex-toc-include-file-boundaries nil
370 "Non-nil means, include file boundaries in *toc* buffer.
371 This flag can be toggled from within the *toc* buffer with the `F' key."
372 :group
'reftex-table-of-contents-browser
375 (defcustom reftex-toc-include-labels nil
376 "Non-nil means, include labels in *toc* buffer.
377 This flag can be toggled from within the *toc* buffer with the `l' key."
378 :group
'reftex-table-of-contents-browser
381 (defcustom reftex-toc-include-index-entries nil
382 "Non-nil means, include index entries in *toc* buffer.
383 This flag can be toggled from within the *toc* buffer with the `i' key."
384 :group
'reftex-table-of-contents-browser
387 (defcustom reftex-toc-confirm-promotion
2
388 "Non-nil means, promotion/demotion commands first prompt for confirmation.
389 If nil, the command is executed immediately. If this is an integer N,
390 ask for confirmation only if N or more section commands are going to be
392 :group
'reftex-table-of-contents-browser
394 (const :tag
"Never" nil
)
395 (const :tag
"Always" t
)
396 (number :tag
"When more than N sections" :value
2)))
398 (defcustom reftex-toc-include-context nil
399 "Non-nil means, include context with labels in the *toc* buffer.
400 Context will only be shown when labels are visible as well.
401 This flag can be toggled from within the *toc* buffer with the `c' key."
402 :group
'reftex-table-of-contents-browser
405 (defcustom reftex-toc-follow-mode nil
406 "Non-nil means, point in *toc* buffer will cause other window to follow.
407 The other window will show the corresponding part of the document.
408 This flag can be toggled from within the *toc* buffer with the `f' key."
409 :group
'reftex-table-of-contents-browser
412 (defcustom reftex-revisit-to-follow nil
413 "Non-nil means, follow-mode will revisit files if necessary.
414 If nil, follow-mode will be suspended for stuff in unvisited files."
415 :group
'reftex-table-of-contents-browser
416 :group
'reftex-referencing-labels
419 (defcustom reftex-toc-mode-hook nil
420 "Mode hook for `reftex-toc-mode'."
421 :group
'reftex-table-of-contents-browser
424 ;; Label Support Configuration
426 (defgroup reftex-label-support nil
427 "Support for creation, insertion and referencing of labels in LaTeX."
430 (defgroup reftex-defining-label-environments nil
431 "Definition of environments and macros to do with label."
432 :group
'reftex-label-support
)
434 (defcustom reftex-default-label-alist-entries
435 '(amsmath endnotes fancybox floatfig longtable picinpar
436 rotating sidecap subfigure supertab wrapfig
437 listings minted ctable LaTeX
)
438 "Default label alist specifications. LaTeX should always be the last entry.
439 The value of this variable is a list of symbols with associations in the
440 constant `reftex-label-alist-builtin'. Check that constant for a full list
442 :group
'reftex-defining-label-environments
443 :set
'reftex-set-dirty
450 (list 'const
:tag
(concat (symbol-name (nth 0 x
))
453 reftex-label-alist-builtin
)))
455 (defcustom reftex-label-alist nil
456 "Alist with information on environments for \\label-\\ref use.
458 This doc string is easier to understand after reading the configuration
459 examples in the manual. Looking at the builtin defaults in the constant
460 `reftex-label-alist-builtin' may also be instructive.
462 Set this variable to define additions and changes to the default. The only
463 things you MUST NOT change is that `?s' is the type indicator for section
464 labels, and SPC for the `any' label type. These are hard-coded at other
467 The value of the variable must be a list of items. Each item is a list
468 itself and has the following structure:
470 (ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT CONTEXT-METHOD
471 (MAGIC-WORD ... ) TOC-LEVEL)
473 Each list entry describes either an environment carrying a counter for use
474 with \\label and \\ref, or a LaTeX macro defining a label as (or inside)
475 one of its arguments. The elements of each list entry are:
478 Name of the environment (like \"table\") or macro (like \"\\\\myfig\").
479 For macros, indicate the macro arguments for best results, as in
480 \"\\\\myfig[]{}{}{*}{}\". Use square brackets for optional arguments,
481 a star to mark the label argument, if any. The macro does not have to
482 have a label argument - you could also use \\label{..} inside one of
484 Special names: `section' for section labels, `any' to define a group
485 which contains all labels.
487 This may also be a function to do local parsing and identify point to
488 be in a non-standard label environment. The function must take an
489 argument BOUND and limit backward searches to this value. It should
490 return either nil or the position where the special environment starts.
491 See the Info documentation for an example.
493 Finally this may also be nil if the entry is only meant to change
494 some settings associated with the type indicator character (see below).
497 Type indicator character, like `?t', must be a printable ASCII character.
498 The type indicator is a single character which defines a label type.
499 Any label inside the environment or macro is assumed to belong to this
500 type. The same character may occur several times in this list, to cover
501 cases in which different environments carry the same label type (like
502 `equation' and `eqnarray').
503 If the type indicator is nil and the macro has a label argument {*},
504 the macro defines neutral labels just like \\label. In this case
505 the remainder of this entry is ignored.
508 Label prefix string, like \"tab:\".
509 The prefix is a short string used as the start of a label. It may be the
510 empty string. The prefix may contain the following `%' escapes:
511 %f Current file name with directory and extension stripped.
512 %F Current file name relative to directory of master file.
513 %m Master file name, directory and extension stripped.
514 %M Directory name (without path) where master file is located.
515 %u User login name, on systems which support this.
516 %S A section prefix derived with variable `reftex-section-prefixes'.
518 Example: In a file `intro.tex', \"eq:%f:\" will become \"eq:intro:\").
521 Format string for reference insertion in buffer. `%s' will be replaced
523 When the format starts with `~', the `~' will only be inserted if
524 there is not already a whitespace before point.
527 Indication on how to find the short context.
528 - If nil, use the text following the \\label{...} macro.
530 - the section heading for section labels.
531 - text following the \\begin{...} statement of environments.
532 (not a good choice for environments like eqnarray or enumerate,
533 where one has several labels in a single environment).
534 - text after the macro name (starting with the first arg) for macros.
535 - If an integer, use the nth argument of the macro. As a special case,
536 1000 means to get text after the last macro argument.
537 - If a string, use as regexp to search *backward* from the label. Context
538 is then the text following the end of the match. E.g. setting this to
539 \"\\\\\\\\caption[[{]\" will use the caption in a figure or table
541 \"\\\\\\\\begin{eqnarray}\\\\|\\\\\\\\\\\\\\\\\" works for eqnarrays.
542 - If any of `caption', `item', `eqnarray-like', `alignat-like', this
543 symbol will internally be translated into an appropriate regexp
544 (see also the variable `reftex-default-context-regexps').
545 - If a function, call this function with the name of the environment/macro
546 as argument. On call, point will be just after the \\label macro. The
547 function is expected to return a suitable context string. It should
548 throw an exception (error) when failing to find context.
549 As an example, here is a function returning the 10 chars following
550 the label macro as context:
552 (defun my-context-function (env-or-mac)
553 (if (> (point-max) (+ 10 (point)))
554 (buffer-substring (point) (+ 10 (point)))
555 (error \"Buffer too small\")))
557 Label context is used in two ways by RefTeX: For display in the label
558 menu, and to derive a label string. If you want to use a different
559 method for each of these, specify them as a dotted pair.
560 E.g. `(nil . t)' uses the text after the label (nil) for display, and
561 text from the default position (t) to derive a label string. This is
562 actually used for section labels.
565 List of magic words which identify a reference to be of this type.
566 If the word before point is equal to one of these words when calling
567 `reftex-reference', the label list offered will be automatically
568 restricted to labels of the correct type.
569 If the first element of this wordlist is the symbol `regexp', the
570 strings are interpreted as regular expressions. RefTeX will add
571 a \"\\\\W\" to the beginning and other stuff to the end of the regexp.
574 The integer level at which this environment should be added to the
575 table of contents. See also `reftex-section-levels'. A positive
576 value will number the entries mixed with the sectioning commands of
577 the same level. A negative value will make unnumbered entries.
578 Useful only for theorem-like environments, will be ignored for macros.
579 When omitted or nil, no TOC entries will be made.
581 If the type indicator characters of two or more entries are the same, RefTeX
583 - the first non-nil format and prefix
584 - the magic words of all involved entries.
586 Any list entry may also be a symbol. If that has an association in
587 `reftex-label-alist-builtin', the cddr of that association is spliced into the
588 list. However, builtin defaults should normally be set with the variable
589 `reftex-default-label-alist-entries'."
590 :group
'reftex-defining-label-environments
591 :set
'reftex-set-dirty
594 (choice :tag
"Package or Detailed "
595 :value
("" ?a nil nil nil nil
)
596 (list :tag
"Detailed Entry"
597 :value
("" ?a nil nil nil nil
)
598 (choice :tag
"Environment or \\macro "
599 (const :tag
"Ignore, just use typekey" nil
)
601 (symbol :tag
"Special parser" my-parser
))
602 (choice :tag
"Type specification "
603 (const :tag
"unspecified, like in \\label" nil
)
604 (character :tag
"Char " ?a
))
605 (choice :tag
"Label prefix string "
606 (const :tag
"Default" nil
)
607 (string :tag
"String" "lab:"))
608 (choice :tag
"Label reference format"
609 (const :tag
"Default" nil
)
610 (string :tag
"String" "~\\ref{%s}"))
611 (choice :tag
"Context method "
612 (const :tag
"Default position" t
)
613 (const :tag
"After label" nil
)
614 (number :tag
"Macro arg nr" 1)
615 (regexp :tag
"Regexp" "")
616 (const :tag
"Caption in float" caption
)
617 (const :tag
"Item in list" item
)
618 (const :tag
"Eqnarray-like" eqnarray-like
)
619 (const :tag
"Alignat-like" alignat-like
)
620 (symbol :tag
"Function" my-func
))
621 (repeat :tag
"Magic words" :extra-offset
2 (string))
622 (option (choice :tag
"Make TOC entry "
623 (const :tag
"No entry" nil
)
624 (integer :tag
"Level" :value -
3))))
630 (list 'const
:tag
(concat (symbol-name (nth 0 x
)))
632 reftex-label-alist-builtin
)))))
634 (defcustom reftex-section-prefixes
'((0 .
"part:") (1 .
"cha:") (t .
"sec:"))
635 "Prefixes for section labels.
636 When the label prefix given in an entry in `reftex-label-alist' contains `%S',
637 this list is used to determine the correct prefix string depending on the
638 current section level.
639 The list is an alist, with each entry of the form (KEY . PREFIX)
640 Possible keys are sectioning macro names like `chapter', section levels
641 \(as given in `reftex-section-levels'), and t for the default."
642 :group
'reftex-defining-label-environments
644 (cons :value
(0 .
"")
646 (string :tag
"macro name")
647 (integer :tag
"section level")
648 (const :tag
"default" t
))
649 (string :tag
"Prefix"))))
651 (defcustom reftex-default-context-regexps
652 '((caption .
"\\\\\\(rot\\)?caption\\*?[[{]")
653 (item .
"\\\\item\\(\\[[^]]*\\]\\)?")
654 (eqnarray-like .
"\\\\begin{%s}\\|\\\\\\\\")
655 (alignat-like .
"\\\\begin{%s}{[0-9]*}\\|\\\\\\\\"))
656 "Alist with default regular expressions for finding context.
657 The form (format regexp (regexp-quote environment)) is used to calculate
658 the final regular expression - so %s will be replaced with the environment
660 :group
'reftex-defining-label-environments
661 :type
'(repeat (cons (symbol) (regexp))))
663 (defcustom reftex-trust-label-prefix nil
664 "Non-nil means, trust the label prefix when determining label type.
665 It is customary to use special label prefixes to distinguish different label
666 types. The label prefixes have no syntactic meaning in LaTeX (unless
667 special packages like fancyref are being used). RefTeX can and by
668 default does parse around each label to detect the correct label type,
669 but this process can be slow when a document contains thousands of
670 labels. If you use label prefixes consistently, you may speed up
671 document parsing by setting this variable to a non-nil value. RefTeX
672 will then compare the label prefix with the prefixes found in
673 `reftex-label-alist' and derive the correct label type in this way.
674 Possible values for this option are:
676 t This means to trust any label prefixes found.
677 regexp If a regexp, only prefixes matched by the regexp are trusted.
678 list List of accepted prefixes, as strings. The colon is part of
679 the prefix, e.g. (\"fn:\" \"eqn:\" \"item:\").
680 nil Never trust a label prefix.
682 The only disadvantage of using this feature is that the label context
683 displayed in the label selection buffer along with each label is
684 simply some text after the label definition. This is no problem if you
685 place labels keeping this in mind (e.g. *before* the equation, *at
686 the beginning* of a fig/tab caption ...). Anyway, it is probably best
687 to use the regexp or the list value types to fine-tune this feature.
688 For example, if your document contains thousands of footnotes with
689 labels fn:xxx, you may want to set this variable to the value \"^fn:$\" or
690 \(\"fn:\"). Then RefTeX will still do extensive parsing for any
691 non-footnote labels."
692 :group
'reftex-defining-label-environments
694 (const :tag
"Always" t
)
695 (const :tag
"Never" nil
)
698 (string :tag
"prefix (with colon)"))))
700 (defcustom reftex-special-environment-functions nil
701 "List of functions to be called when trying to figure out current environment.
702 These are special functions to detect \"environments\" which do not
703 start with \\begin and end with \\end. Some LaTeX packages seem to
704 use such non-standard ways to set up environment-like constructs. The
705 purpose of each function in this list is to detect if point is
706 currently inside such a special \"environment\". If the environment
707 carries a label, you must also set up an entry for it in
708 `reftex-label-alist'.
710 The function should check if point is currently in the special
711 environment it was written to detect. If so, the function must return
712 a cons cell (NAME . POSITION). NAME is the name of the environment
713 detected and POSITION is the buffer position where the environment
714 starts. The function must return nil on failure to detect the
717 The function must take an argument BOUND. If non-nil, BOUND is a
718 boundary for backwards searches which should be observed.
720 Here is an example. The LaTeX package linguex.sty defines list macros
721 `\\ex.', `\\a.', etc for lists which are terminated by `\\z.' or an empty
724 \\ex. \\label{ex:12} Some text in an exotic language ...
725 \\a. \\label{ex:13} more stuff
726 \\b. \\label{ex:14} still more stuff
728 ... more text after the empty line terminating all lists
730 And here is the setup for RefTeX:
732 1. Define a dummy environment for this in `reftex-label-alist'. Dummy means,
733 make up an environment name even though it is not used with \\begin and
734 \\end. Here we use \"linguex\" as this name.
736 (setq reftex-label-alist
737 '((\"linguex\" ?x \"ex:\" \"~\\\\ref{%s}\" nil (\"Example\" \"Ex.\"))))
739 2. Write a function to detect the list macros and the determinators as well.
741 (defun my-detect-linguex-list (bound)
742 (let ((pos (point)) p1)
744 ;; Search for any of the linguex item macros at the beginning of a line
745 (if (re-search-backward
746 \"^[ \\t]*\\\\(\\\\\\\\\\\\(ex\\\\|a\\\\|b\\\\|c\\\\|d\\\\|e\\\\|f\\\\)g?\\\\.\\\\)\" bound t)
748 (setq p1 (match-beginning 1))
749 ;; Make sure no empty line or \\z. is between us and the item macro
750 (if (re-search-forward \"\\n[ \\t]*\\n\\\\|\\\\\\\\z\\\\.\" pos t)
751 ;; Return nil because list was already closed
754 (cons \"linguex\" p1)))
755 ;; Return nil for not found
758 3. Tell RefTeX to use this function
760 (setq reftex-special-environment-functions '(my-detect-linguex-list))"
761 :group
'reftex-defining-label-environments
766 (defgroup reftex-making-and-inserting-labels nil
767 "Options on how to create new labels."
768 :group
'reftex-label-support
)
770 (defcustom reftex-insert-label-flags
'("s" "sft")
771 "Flags governing label insertion. First flag DERIVE, second flag PROMPT.
773 If DERIVE is t, RefTeX will try to derive a sensible label from context.
774 A section label for example will be derived from the section heading.
775 The conversion of the context to a valid label is governed by the
776 specifications given in `reftex-derive-label-parameters'.
777 If RefTeX fails to derive a label, it will prompt the user.
778 If DERIVE is nil, the label generated will consist of the prefix and a
779 unique number, like `eq:23'.
781 If PROMPT is t, the user will be prompted for a label string. The prompt will
782 already contain the prefix, and (if DERIVE is t) a default label derived from
783 context. When PROMPT is nil, the default label will be inserted without
786 So the combination of DERIVE and PROMPT controls label insertion. Here is a
787 table describing all four possibilities:
790 -------------------------------------------------------------------------
791 nil nil Insert simple label, like eq:22 or sec:13. No query.
792 nil t Prompt for label.
793 t nil Derive a label from context and insert without query.
794 t t Derive a label from context and prompt for confirmation.
796 Each flag may be set to t, nil, or a string of label type letters
797 indicating the label types for which it should be true. The strings work
798 like character classes.
799 Thus, the combination may be set differently for each label type. The
800 default settings \"s\" and \"sft\" mean: Derive section labels from headings
801 \(with confirmation). Prompt for figure and table labels. Use simple labels
802 without confirmation for everything else.
803 The available label types are: s (section), f (figure), t (table), i (item),
804 e (equation), n (footnote), N (endnote), plus any definitions in
805 `reftex-label-alist'."
806 :group
'reftex-making-and-inserting-labels
807 :type
'(list (choice :tag
"Derive label from context"
808 (const :tag
"always" t
)
809 (const :tag
"never" nil
)
810 (string :tag
"selected label types" ""))
811 (choice :tag
"Prompt for label string "
812 :entry-format
" %b %v"
813 (const :tag
"always" t
)
814 (const :tag
"never" nil
)
815 (string :tag
"selected label types" ""))))
817 (defcustom reftex-string-to-label-function
'reftex-string-to-label
818 "Function to turn an arbitrary string into a valid label.
819 RefTeX's default function uses the variable `reftex-derive-label-parameters'."
820 :group
'reftex-making-and-inserting-labels
823 (defcustom reftex-translate-to-ascii-function
'reftex-latin1-to-ascii
824 "Filter function to convert a string to ASCII.
825 The function is used to process a context string before it is
826 used to derive a label from it. The intended application is to
827 convert ISO or Mule characters into something valid in labels.
828 The default function removes the accents from Latin-1 characters.
829 X-Symbol (>=2.6) sets this variable to the much more general
830 `x-symbol-translate-to-ascii'."
831 :group
'reftex-making-and-inserting-labels
834 (defcustom reftex-derive-label-parameters
'(3 20 t
1 "-"
835 ("the" "on" "in" "off" "a" "for" "by" "of" "and" "is" "to") t
)
836 "Parameters for converting a string into a label.
837 This variable is a list of the following items.
839 NWORDS Number of words to use.
840 MAXCHAR Maximum number of characters in a label string.
841 INVALID nil: Throw away any words containing characters invalid in labels.
842 t: Throw away only the invalid characters, not the whole word.
843 ABBREV nil: Never abbreviate words.
844 t: Always abbreviate words (see `reftex-abbrev-parameters').
845 not t and not nil: Abbreviate words if necessary to shorten
846 label string below MAXCHAR.
847 SEPARATOR String separating different words in the label.
848 IGNOREWORDS List of words which should not be part of labels.
849 DOWNCASE t: Downcase words before using them."
850 :group
'reftex-making-and-inserting-labels
851 :type
'(list (integer :tag
"Number of words " 3)
852 (integer :tag
"Maximum label length " 20)
853 (choice :tag
"Invalid characters in words"
854 (const :tag
"throw away entire word" nil
)
855 (const :tag
"throw away single chars" t
))
856 (choice :tag
"Abbreviate words "
857 (const :tag
"never" nil
)
858 (const :tag
"always" t
)
859 (const :tag
"when label is too long" 1))
860 (string :tag
"Separator between words " "-")
861 (repeat :tag
"Ignore words"
862 :entry-format
" %i %d %v"
864 (option (boolean :tag
"Downcase words "))))
866 (defcustom reftex-label-regexps
867 '(;; Normal \\label{foo} labels
868 "\\\\label{\\(?1:[^}]*\\)}"
869 ;; keyvals [..., label = {foo}, ...] forms used by ctable,
870 ;; listings, minted, ...
871 "\\[[^]]*\\<label[[:space:]]*=[[:space:]]*{?\\(?1:[^],}]+\\)}?")
872 "List of regexps matching \\label definitions.
873 The default value matches usual \\label{...} definitions and
874 keyval style [..., label = {...}, ...] label definitions. It is
875 assumed that the regexp group 1 matches the label text, so you
876 have to define it using \\(?1:...\\) when adding new regexps."
877 :group
'reftex-defining-label-environments
878 :type
'(repeat (regexp :tag
"Regular Expression")))
880 (defcustom reftex-label-illegal-re
"[^-a-zA-Z0-9_+=:;,.]"
881 "Regexp matching characters not valid in labels."
882 :group
'reftex-making-and-inserting-labels
883 :type
'(regexp :tag
"Regular Expression"))
885 (defcustom reftex-abbrev-parameters
'(4 2 "^aeiou" "aeiou")
886 "Parameters for abbreviation of words.
887 This variable is a list of the following items.
889 MIN-CHARS Minimum number of characters remaining after abbreviation.
890 MIN-KILL Minimum number of characters to remove when abbreviating words.
891 BEFORE Character class before abbrev point in word.
892 AFTER Character class after abbrev point in word."
893 :group
'reftex-making-and-inserting-labels
895 (integer :tag
"Minimum chars per word" 4)
896 (integer :tag
"Shorten by at least " 2)
897 (string :tag
"cut before char class " "^saeiou")
898 (string :tag
"cut after char class " "aeiou")))
900 (defcustom reftex-format-label-function nil
901 "Function which produces the string to insert as a label definition.
902 Normally should be nil, unless you want to do something fancy.
903 The function will be called with two arguments, the LABEL and the DEFAULT
904 FORMAT, which usually is `\\label{%s}'. The function should return the
905 string to insert into the buffer."
906 :group
'reftex-making-and-inserting-labels
911 (defgroup reftex-referencing-labels nil
912 "Options on how to reference labels."
913 :group
'reftex-label-support
)
917 '((const :tag
"on" t
)
918 (const :tag
"off" nil
)
919 (string :tag
"Selected label types"))))
921 (defcustom reftex-label-menu-flags
'(t t nil nil nil nil t nil
)
922 "List of flags governing the label menu makeup.
925 TABLE-OF-CONTENTS Show the labels embedded in a table of context.
926 SECTION-NUMBERS Include section numbers (like 4.1.3) in table of contents.
927 COUNTERS Show counters. This just numbers the labels in the menu.
928 NO-CONTEXT Non-nil means do NOT show the short context.
929 FOLLOW Follow full context in other window.
930 SHOW-COMMENTED Show labels from regions which are commented out.
931 MATCH-IN-TOC Obsolete flag.
932 SHOW FILES Show begin and end of included files.
934 Each of these flags can be set to t or nil, or to a string of type letters
935 indicating the label types for which it should be true. These strings work
936 like character classes in regular expressions. Thus, setting one of the
937 flags to \"sf\" makes the flag true for section and figure labels, nil
938 for everything else. Setting it to \"^sf\" makes it the other way round.
939 The available label types are: s (section), f (figure), t (table), i (item),
940 e (equation), n (footnote), plus any definitions in `reftex-label-alist'.
942 Most options can also be switched from the label menu itself - so if you
943 decide here to not have a table of contents in the label menu, you can still
944 get one interactively during selection from the label menu."
945 :group
'reftex-referencing-labels
948 (choice :tag
"Embed in table of contents " ,@reftex-tmp
)
949 (choice :tag
"Show section numbers " ,@reftex-tmp
)
950 (choice :tag
"Show individual counters " ,@reftex-tmp
)
951 (choice :tag
"Hide short context " ,@reftex-tmp
)
952 (choice :tag
"Follow context in other window " ,@reftex-tmp
)
953 (choice :tag
"Show commented labels " ,@reftex-tmp
)
954 (choice :tag
"Obsolete flag, Don't use. " ,@reftex-tmp
)
955 (choice :tag
"Show begin/end of included files" ,@reftex-tmp
)))
957 (defcustom reftex-multiref-punctuation
'((?
, .
", ") (?- .
"--") (?
+ .
" and "))
958 "Punctuation strings for multiple references.
959 When marking is used in the selection buffer to select several references,
960 this variable associates the 3 marking characters `,-+' with prefix strings
961 to be inserted into the buffer before the corresponding \\ref macro.
962 This is used to string together whole reference sets, like
963 `eqs. 1,2,3-5,6 and 7' in a single call to `reftex-reference'. See manual."
964 :group
'reftex-referencing-labels
965 :type
'(repeat (cons (character) (string))))
967 (defcustom reftex-ref-style-alist
969 (("\\ref" ?\C-m
) ("\\pageref" ?p
)))
970 ("Varioref" "varioref"
971 (("\\vref" ?v
) ("\\vpageref" ?g
) ("\\Vref" ?V
) ("\\Ref" ?R
)))
972 ("Fancyref" "fancyref"
973 (("\\fref" ?f
) ("\\Fref" ?F
)))
974 ("Hyperref" "hyperref"
975 (("\\autoref" ?a
) ("\\autopageref" ?u
))))
976 "Alist of reference styles.
977 Each element is a list of the style name, the name of the LaTeX
978 package associated with the style or t for any package, and an
979 alist of macros where the first entry of each item is the
980 reference macro and the second a key for selecting the macro when
981 the macro type is being prompted for. (See also
982 `reftex-ref-macro-prompt'.) The keys, represented as characters,
984 :group
'reftex-referencing-labels
986 :type
'(alist :key-type
(string :tag
"Style name")
987 :value-type
(group (choice :tag
"Package"
988 (const :tag
"Any package" t
)
989 (string :tag
"Name"))
990 (repeat :tag
"Macros"
991 (group (string :tag
"Macro")
992 (character :tag
"Key"))))))
994 (defcustom reftex-ref-macro-prompt t
995 "If non-nil, `reftex-reference' prompts for the reference macro."
996 :group
'reftex-referencing-labels
1000 (defcustom reftex-vref-is-default nil
1001 "Non-nil means, the varioref reference style is used as default.
1002 The value of this variable determines the default which is active
1003 when entering the selection process. Instead of nil or t, this
1004 may also be a string of type letters indicating the label types
1005 for which it should be true.
1007 This variable is obsolete, use `reftex-ref-style-default-list'
1009 :group
'reftex-referencing-labels
1010 :type
`(choice :tag
"\\vref is default macro" ,@reftex-tmp
))
1011 ;;;###autoload(put 'reftex-vref-is-default 'safe-local-variable (lambda (x) (or (stringp x) (symbolp x))))
1013 (defcustom reftex-fref-is-default nil
1014 "Non-nil means, the fancyref reference style is used as default.
1015 The value of this variable determines the default which is active
1016 when entering the selection process. Instead of nil or t, this
1017 may also be a string of type letters indicating the label types
1018 for which it should be true.
1020 This variable is obsolete, use `reftex-ref-style-default-list'
1022 :group
'reftex-referencing-labels
1023 :type
`(choice :tag
"\\fref is default macro" ,@reftex-tmp
))
1024 ;;;###autoload(put 'reftex-fref-is-default 'safe-local-variable (lambda (x) (or (stringp x) (symbolp x))))
1026 (defcustom reftex-ref-style-default-list
'("Default")
1027 "List of reference styles to be activated by default.
1028 The order is significant and controls the order in which macros
1029 can be cycled in the buffer for selecting a label. The entries
1030 in the list have to match the respective reference style names
1031 used in the variable `reftex-ref-style-alist'."
1032 :group
'reftex-referencing-labels
1034 :type
`(set ,@(mapcar (lambda (x) (list 'const
(car x
)))
1035 reftex-ref-style-alist
)))
1037 ;; Compatibility with obsolete variables.
1038 (when reftex-vref-is-default
1039 (add-to-list 'reftex-ref-style-default-list
"Varioref"))
1040 (when reftex-fref-is-default
1041 (add-to-list 'reftex-ref-style-default-list
"Fancyref"))
1043 (defcustom reftex-level-indent
2
1044 "Number of spaces to be used for indentation per section level."
1045 :group
'reftex-referencing-labels
1047 ;;;###autoload(put 'reftex-level-indent 'safe-local-variable 'integerp)
1049 (defcustom reftex-guess-label-type t
1050 "Non-nil means, `reftex-reference' will try to guess the label type.
1051 To do that, RefTeX will look at the word before the cursor and compare it with
1052 the words given in `reftex-label-alist'. When it finds a match, RefTeX will
1053 immediately offer the correct label menu - otherwise it will prompt you for
1054 a label type. If you set this variable to nil, RefTeX will always prompt."
1055 :group
'reftex-referencing-labels
1057 ;;;###autoload(put 'reftex-guess-label-type 'safe-local-variable (lambda (x) (memq x '(nil t))))
1059 (defcustom reftex-format-ref-function nil
1060 "Function which produces the string to insert as a reference.
1061 Normally should be nil, because the format to insert a reference
1062 can already be specified in `reftex-label-alist'.
1064 This hook also is used by the special commands to insert
1065 e.g. `\\vref' and `\\fref' references, so even if you set this,
1066 your setting will be ignored by the special commands.
1068 The function will be called with three arguments, the LABEL, the
1069 DEFAULT FORMAT, which normally is `~\\ref{%s}' and the REFERENCE
1070 STYLE. The function should return the string to insert into the
1072 :group
'reftex-referencing-labels
1073 :type
'(choice (const nil
) function
))
1075 (defcustom reftex-select-label-mode-hook nil
1076 "Mode hook for `reftex-select-label-mode'."
1077 :group
'reftex-referencing-labels
1080 ;; BibteX citation configuration ----------------------------------------
1082 (defgroup reftex-citation-support nil
1083 "Support for referencing bibliographic data with BibTeX."
1086 (defcustom reftex-bibliography-commands
1087 '("bibliography" "nobibliography" "setupbibtex\\[.*?database=")
1088 "LaTeX commands which specify the BibTeX databases to use with the document."
1089 :group
'reftex-citation-support
1090 :type
'(repeat string
))
1093 (defvar reftex-bibfile-ignore-list nil
) ; compatibility
1094 (defcustom reftex-bibfile-ignore-regexps nil
1095 "List of regular expressions to exclude files in \\bibliography{..}.
1096 File names matched by these regexps will not be parsed by RefTeX.
1097 Intended for files which contain only `@string' macro definitions and the
1098 like, which are ignored by RefTeX anyway."
1099 :group
'reftex-citation-support
1100 :set
'reftex-set-dirty
1101 :type
'(repeat (regexp)))
1103 (defcustom reftex-default-bibliography nil
1104 "List of BibTeX database files which should be used if none are specified.
1105 When `reftex-citation' is called from a document which has neither a
1106 `\\bibliography{..}' statement nor a `thebibliography' environment,
1107 RefTeX will scan these files instead. Intended for using `reftex-citation'
1108 in non-LaTeX files. The files will be searched along the BIBINPUTS or TEXBIB
1110 :group
'reftex-citation-support
1111 :type
'(repeat (file)))
1113 (defcustom reftex-sort-bibtex-matches
'reverse-year
1114 "Sorting of the entries found in BibTeX databases by reftex-citation.
1116 nil Do not sort entries.
1117 'author Sort entries by author name.
1118 'year Sort entries by increasing year.
1119 'reverse-year Sort entries by decreasing year."
1120 :group
'reftex-citation-support
1121 :type
'(choice (const :tag
"not" nil
)
1122 (const :tag
"by author" author
)
1123 (const :tag
"by year" year
)
1124 (const :tag
"by year, reversed" reverse-year
)))
1126 (defcustom reftex-cite-format
'default
1127 "The format of citations to be inserted into the buffer.
1128 It can be a string or an alist or a symbol. In the simplest case this
1129 is just the string \"\\cite{%l}\", which is also the default. See the
1130 definition of `reftex-cite-format-builtin' for more complex examples.
1132 If `reftex-cite-format' is a string, it will be used as the format.
1133 In the format, the following percent escapes will be expanded.
1135 %l The BibTeX label of the citation.
1136 %a List of author names, see also `reftex-cite-punctuation'.
1137 %2a Like %a, but abbreviate more than 2 authors like Jones et al.
1138 %A First author name only.
1139 %e Works like %a, but on list of editor names. (%2e and %E work a well)
1141 It is also possible to access all other BibTeX database fields:
1142 %b booktitle %c chapter %d edition %h howpublished
1143 %i institution %j journal %k key %m month
1144 %n number %N note %o organization %p pages
1145 %P first page %r address %s school %u publisher
1146 %U url %t title %v volume %y year
1147 %B booktitle, abbreviated %T title, abbreviated
1149 Usually, only %l is needed. The other stuff is mainly for the echo area
1150 display, and for (setq reftex-comment-citations t).
1152 %< as a special operator kills punctuation and space around it after the
1153 string has been formatted.
1155 A pair of square brackets indicates an optional argument, and RefTeX
1156 will prompt for the values of these arguments.
1158 Beware that all this only works with BibTeX database files. When
1159 citations are made from the \\bibitems in an explicit thebibliography
1160 environment, only %l is available.
1162 If `reftex-cite-format' is an alist of characters and strings, the user
1163 will be prompted for a character to select one of the possible format
1165 In order to configure this variable, you can either set
1166 `reftex-cite-format' directly yourself or set it to the SYMBOL of one of
1167 the predefined styles. The predefined symbols are those which have an
1168 association in the constant `reftex-cite-format-builtin'.
1169 E.g.: (setq reftex-cite-format 'natbib)"
1170 :group
'reftex-citation-support
1173 :format
"%{%t%}: \n%[Value Menu%] %v"
1174 (radio :tag
"Symbolic Builtins"
1179 (list 'const
:tag
(concat (symbol-name (nth 0 x
))
1182 reftex-cite-format-builtin
))
1183 (string :tag
"format string" "\\cite{%l}")
1184 (repeat :tag
"key-ed format strings"
1185 :value
((?
\r .
"\\cite{%l}")
1186 (?t .
"\\cite{%l}") (?p .
"\\cite{%l}"))
1187 (cons (character :tag
"Key character" ?
\r)
1188 (string :tag
"Format string" "")))))
1190 (defcustom reftex-cite-prompt-optional-args
'maybe
1191 "Non-nil means, prompt for empty optional arguments in cite macros.
1192 When an entry in `reftex-cite-format' is given with square brackets to
1193 indicate optional arguments (for example \\cite[][]{%l}), RefTeX can
1194 prompt for values. Possible values are:
1196 nil Never prompt for optional arguments
1198 maybe Prompt only if `reftex-citation' was called with C-u prefix arg
1200 Unnecessary empty optional arguments are removed before insertion into
1201 the buffer. See `reftex-cite-cleanup-optional-args'."
1202 :group
'reftex-citation-support
1204 (const :tag
"Always" t
)
1205 (const :tag
"When called with prefix arg" maybe
)
1206 (const :tag
"Never" nil
)))
1208 (defcustom reftex-cite-cleanup-optional-args t
1209 "Non-nil means, remove unnecessary empty optional arguments in cite macros.
1210 The cite macros provided by some packages (for example
1211 natbib) allow specifying two optional arguments, one for a prefix to
1212 the citation, and a second for a postfix. When only one optional
1213 argument is given, it is interpreted as postfix. When this option is
1214 t, RefTeX removes unnecessary empty optional arguments from the cite
1215 macro before insertion. For example, it will change
1216 \\cite[][]{Jones} -> \\cite{Jones}
1217 \\cite[][Chapter 1]{Jones} -> \\cite[Chapter 1]{Jones}
1218 \\cite[see][]{Jones} -> \\cite[see][]{Jones}
1219 \\cite[see][Chapter 1]{Jones} -> \\cite{Jones}
1220 Is is possible that other packages have other conventions about which
1221 optional argument is interpreted how - that is why this cleaning up
1223 :group
'reftex-citation-support
1226 (defcustom reftex-comment-citations nil
1227 "Non-nil means add a comment for each citation describing the full entry.
1228 The comment is formatted according to `reftex-cite-comment-format'."
1229 :group
'reftex-citation-support
1232 (defcustom reftex-cite-comment-format
1233 "%% %2a %y, %j %v, %P, %b, %e, %u, %s %<\n"
1234 "Citation format used for commented citations. Must NOT contain %l.
1235 See the variable `reftex-cite-format' for possible percent escapes."
1236 :group
'reftex-citation-support
1239 (defcustom reftex-cite-view-format
"%2a %y, %T, %B, %j %v:%P, %s %<"
1240 "Citation format used to display citation info in the message area.
1241 Must NOT contain %l. See the variable `reftex-cite-format' for
1242 possible percent escapes."
1243 :group
'reftex-citation-support
1244 :group
'reftex-viewing-cross-references
1247 (defcustom reftex-cite-punctuation
'(", " " \\& " " {\\it et al.}")
1248 "Punctuation for formatting of name lists in citations.
1249 This is a list of 3 strings.
1250 1. Normal names separator, like \", \" in Jones, Brown and Miller
1251 2. Final names separator, like \" and \" in Jones, Brown and Miller
1252 3. The \"et al\" string, like \" {\\it et al.}\" in Jones {\\it et al.}"
1253 :group
'reftex-citation-support
1255 (string :tag
"Separator for names ")
1256 (string :tag
"Separator for last name in list")
1257 (string :tag
"string used as et al. ")))
1259 (defcustom reftex-format-cite-function nil
1260 "Function which produces the string to insert as a citation.
1261 Normally should be nil, because the format to insert a reference can
1262 already be specified in `reftex-cite-format'.
1263 The function will be called with two arguments, the CITATION KEY and the
1264 DEFAULT FORMAT, which is taken from `reftex-cite-format'. The function
1265 should return the string to insert into the buffer."
1266 :group
'reftex-citation-support
1267 :type
'(choice (const nil
) function
))
1269 (defcustom reftex-select-bib-mode-hook nil
1270 "Mode hook for reftex-select-bib-mode."
1271 :group
'reftex-citation-support
1274 (defcustom reftex-cite-key-separator
","
1275 "String to be used for separating several keys in a \\cite macro."
1276 :group
'reftex-citation-support
1280 (defcustom reftex-create-bibtex-header nil
1281 "Header to insert in BibTeX files generated by RefTeX."
1282 :group
'reftex-citation-support
1284 :type
'(choice (const :tag
"No header" nil
) string
))
1286 (defcustom reftex-create-bibtex-footer nil
1287 "Footer to insert in BibTeX files generated by RefTeX."
1288 :group
'reftex-citation-support
1290 :type
'(choice (const :tag
"No footer" nil
) string
))
1292 ;; Index Support Configuration
1294 (defgroup reftex-index-support nil
1295 "Support for viewing and editing the index."
1298 (defcustom reftex-support-index t
1299 "Non-nil means, index entries are parsed as well.
1300 Index support is resource intensive and the internal structure holding the
1301 parsed information can become quite big. Therefore it can be turned off.
1302 When this is nil and you execute a command which requires index support,
1303 you will be asked for confirmation to turn it on and rescan the document."
1304 :group
'reftex-index-support
1307 (defcustom reftex-index-special-chars
'("!" "|" "@" "\"" "\\")
1308 "Special characters in index entries. The value is a list of five strings.
1309 These correspond to the makeindex keywords LEVEL ENCAP ACTUAL QUOTE ESCAPE."
1310 :group
'reftex-index-support
1312 (string :tag
"LEVEL separator")
1313 (string :tag
"ENCAP char ")
1314 (string :tag
"ACTUAL char ")
1315 (string :tag
"QUOTE char ")
1316 (string :tag
"ESCAPE char ")))
1318 (defcustom reftex-index-macros nil
1319 "Macros which define index entries.
1323 \(MACRO INDEX-TAG KEY PREFIX EXCLUDE REPEAT)
1325 MACRO is the macro. Arguments should be denoted by empty braces like
1326 \\index[]{*}. Use square brackets to denote optional arguments. The star
1327 marks where the index key is.
1329 INDEX-TAG is a short name of the index. \"idx\" and \"glo\" are
1330 reserved for the default index and the glossary. Other indices can be
1331 defined as well. If this is an integer, the Nth argument of the macro
1332 holds the index tag.
1334 KEY is a character which is used to identify the macro for input with
1335 \\[reftex-index]. ?i, ?I, and ?g are reserved for default index and glossary.
1337 PREFIX can be a prefix which is added to the KEY part of the index entry.
1338 If you have a macro \\newcommand{\\molec}[1]{#1\\index{Molecules!#1}}, this
1339 prefix should be \"Molecules!\". See the manual for details.
1341 EXCLUDE can be a function. If this function exists and returns a non-nil
1342 value, the index entry at point is ignored. This was implemented to support
1343 the (deprecated) `^' and `_' shortcuts in the LaTeX2e `index' package.
1345 REPEAT, if non-nil, means the index macro does not typeset the entry in
1346 the text, so that the text has to be repeated outside the index macro.
1347 Needed for `reftex-index-selection-or-word' and for indexing from the
1350 The final entry may also be a symbol if this entry has a association
1351 in the variable `reftex-index-macros-builtin' to specify the main
1352 indexing package you are using. Valid values are currently
1353 default The LaTeX default - unnecessary to specify this one
1354 multind The multind.sty package
1355 index The index.sty package
1356 index-shortcut The index.sty packages with the ^ and _ shortcuts.
1357 Should not be used - only for old documents.
1358 Note that AUCTeX sets these things internally for RefTeX as well, so
1359 with a sufficiently new version of AUCTeX, you should not set the
1361 :group
'reftex-index-support
1362 :set
'reftex-set-dirty
1366 (list :value
("" "idx" ?a
"" nil
)
1367 (string :tag
"Macro with args")
1368 (choice :tag
"Index Tag "
1370 (integer :tag
"Macro arg Nr" :value
1))
1371 (character :tag
"Access Key ")
1372 (string :tag
"Key Prefix ")
1373 (symbol :tag
"Exclusion hook ")
1374 (boolean :tag
"Repeat Outside ")))
1377 (choice :tag
"Package"
1381 (list 'const
:tag
(concat (symbol-name (nth 0 x
))
1384 reftex-index-macros-builtin
)))))
1386 (defcustom reftex-index-default-macro
'(?i
"idx")
1387 "The default index macro for \\[reftex-index-selection-or-word].
1388 This is a list with (MACRO-KEY DEFAULT-TAG).
1390 MACRO-KEY: Character identifying an index macro - see `reftex-index-macros'.
1391 DEFAULT-TAG: This is the tag to be used if the macro requires a TAG argument.
1392 When this is nil and a TAG is needed, RefTeX will ask for it.
1393 When this is the empty string and the TAG argument of the index
1394 macro is optional, the TAG argument will be omitted."
1395 :group
'reftex-index-support
1397 (character :tag
"Character identifying default macro")
1398 (choice :tag
"Default index tag "
1402 (defcustom reftex-index-default-tag
"idx"
1404 When working with multiple indexes, RefTeX queries for an index tag when
1405 creating index entries or displaying a specific index. This variable controls
1406 the default offered for these queries. The default can be selected with RET
1407 during selection or completion. Valid values of this variable are:
1409 nil Do not provide a default index
1410 \"tag\" The default index tag given as a string, e.g. \"idx\".
1411 last The last used index tag will be offered as default."
1412 :group
'reftex-index-support
1414 (const :tag
"no default" nil
)
1415 (const :tag
"last used " 'last
)
1416 (string :tag
"index tag " "idx")))
1418 (defcustom reftex-index-math-format
"$%s$"
1419 "Format of index entries when copied from inside math mode.
1420 When `reftex-index-selection-or-word' is executed inside TeX math mode,
1421 the index key copied from the buffer is processed with this format string
1422 through the `format' function. This can be used to add the math delimiters
1423 \(e.g. `$') to the string.
1424 Requires the `texmathp.el' library which is part of AUCTeX."
1425 :group
'reftex-index-support
1428 (defcustom reftex-index-phrase-file-extension
".rip"
1429 "File extension for the index phrase file.
1430 This extension will be added to the base name of the master file."
1431 :group
'reftex-index-support
1434 (defcustom reftex-index-phrases-logical-and-regexp
" *&& *"
1435 "Regexp matching the `and' operator for index arguments in phrases file.
1436 When several index arguments in a phrase line are separated by this
1437 operator, each part will generate an index macro. So each match of
1438 the search phrase will produce *several* different index entries.
1440 Note: make sure this does no match things which are not separators.
1441 This logical `and' has higher priority than the logical `or' specified in
1442 `reftex-index-phrases-logical-or-regexp'."
1443 :group
'reftex-index-support
1446 (defcustom reftex-index-phrases-logical-or-regexp
" *|| *"
1447 "Regexp matching the `or' operator for index arguments in phrases file.
1448 When several index arguments in a phrase line are separated by this
1449 operator, the user will be asked to select one of them at each match
1450 of the search phrase. The first index arg will be the default - a
1451 number key 1-9 must be pressed to switch to another.
1453 Note: make sure this does no match things which are not separators.
1454 The logical `and' specified in `reftex-index-phrases-logical-or-regexp'
1455 has higher priority than this logical `or'."
1456 :group
'reftex-index-support
1459 (defcustom reftex-index-phrases-search-whole-words t
1460 "Non-nil means phrases search will look for whole words, not subwords.
1461 This works by requiring word boundaries at the beginning and end of
1462 the search string. When the search phrase already has a non-word-char
1463 at one of these points, no word boundary is required there."
1464 :group
'reftex-index-support
1467 (defcustom reftex-index-phrases-case-fold-search t
1468 "Non-nil means, searching for index phrases will ignore case."
1469 :group
'reftex-index-support
1472 (defcustom reftex-index-verify-function nil
1473 "A function which is called at each match during global indexing.
1474 If the function returns nil, the current match is skipped."
1475 :group
'reftex-index-support
1477 (const :tag
"No verification" nil
)
1480 (defcustom reftex-index-phrases-skip-indexed-matches nil
1481 "Non-nil means, skip matches which appear to be indexed already.
1482 When doing global indexing from the phrases buffer, searches for some
1483 phrases may match at places where that phrase was already indexed. In
1484 particular when indexing an already processed document again, this
1485 will even be the norm. When this variable is non-nil, RefTeX checks if
1486 the match is inside an index macro argument, or if an index macro is directly
1487 before or after the phrase. If that is the case, that match will
1489 :group
'reftex-index-support
1492 (defcustom reftex-index-phrases-wrap-long-lines nil
1493 "Non-nil means, when indexing from the phrases buffer, wrap lines.
1494 Inserting indexing commands in a line makes the line longer - often
1495 so long that it does not fit onto the screen. When this variable is
1496 non-nil, newlines will be added as necessary before and/or after the
1497 indexing command to keep lines short. However, the matched text
1498 phrase and its index command will always end up on a single line."
1499 :group
'reftex-index-support
1502 (defcustom reftex-index-phrases-sort-prefers-entry nil
1503 "Non-nil means when sorting phrase lines, the explicit index entry is used.
1504 Phrase lines in the phrases buffer contain a search phrase, and
1505 sorting is normally based on these. Some phrase lines also have
1506 an explicit index argument specified. When this variable is non-nil,
1507 the index argument will be used for sorting."
1508 :group
'reftex-index-support
1511 (defcustom reftex-index-phrases-sort-in-blocks t
1512 "Non-nil means, empty and comment lines separate phrase buffer into blocks.
1513 Sorting will then preserve blocks, so that lines are re-arranged only
1515 :group
'reftex-index-support
1518 (defcustom reftex-index-section-letters
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
1519 "The letters which denote sections in the index.
1520 Usually these are all capital letters. Don't use any downcase letters.
1521 Order is not significant, the index will be sorted by whatever the sort
1522 function thinks is correct.
1523 In addition to these letters, RefTeX will create a group `!' which
1524 contains all entries sorted below the lowest specified letter.
1525 In the index buffer, pressing any of these capital letters or `!' will jump
1527 :group
'reftex-index-support
1528 :type
'(string :tag
"Capital letters"))
1530 (defcustom reftex-index-include-context nil
1531 "Non-nil means, display the index definition context in the index buffer.
1532 This flag may also be toggled from the index buffer with the `c' key."
1533 :group
'reftex-index-support
1536 (defcustom reftex-index-follow-mode nil
1537 "Non-nil means, point in *Index* buffer will cause other window to follow.
1538 The other window will show the corresponding part of the document.
1539 This flag can be toggled from within the *Index* buffer with the `f' key."
1540 :group
'reftex-table-of-contents-browser
1543 ;; Viewing Cross References
1545 (defgroup reftex-viewing-cross-references nil
1546 "Displaying cross references and citations."
1549 (defcustom reftex-view-crossref-extra nil
1550 "Macros which can be used for the display of cross references.
1551 This is used when `reftex-view-crossref' is called with point in an
1552 argument of a macro. Note that crossref viewing for citations,
1553 references (both ways) and index entries is hard-coded. This variable
1554 is only to configure additional structures for which cross-reference
1555 viewing can be useful. Each entry has the structure
1557 \(MACRO-RE SEARCH-RE HIGHLIGHT).
1559 MACRO-RE is matched against the macro. SEARCH-RE is the regexp used
1560 to search for cross references. `%s' in this regexp is replaced with
1561 with the macro argument at point. HIGHLIGHT is an integer indicating
1562 which subgroup of the match should be highlighted."
1563 :group
'reftex-viewing-cross-references
1564 :type
'(repeat (group (regexp :tag
"Macro Regexp ")
1565 (string :tag
"Search Regexp ")
1566 (integer :tag
"Highlight Group"))))
1568 (defcustom reftex-auto-view-crossref t
1569 "Non-nil means, initially turn automatic viewing of crossref info on.
1570 Automatic viewing of crossref info normally uses the echo area.
1571 Whenever point is idle for more than `reftex-idle-time' seconds on the
1572 argument of a \\ref or \\cite macro, and no other message is being
1573 displayed, the echo area will display information about that cross
1574 reference. You can also set the variable to the symbol `window'. In
1575 this case a small temporary window is used for the display.
1576 This feature can be turned on and off from the menu
1578 :group
'reftex-viewing-cross-references
1579 :type
'(choice (const :tag
"off" nil
)
1580 (const :tag
"in Echo Area" t
)
1581 (const :tag
"in Other Window" window
)))
1583 (defcustom reftex-idle-time
1.2
1584 "Time (secs) Emacs has to be idle before automatic crossref display is done.
1585 Applies also to toc recentering."
1586 :group
'reftex-viewing-cross-references
1589 (defcustom reftex-revisit-to-echo nil
1590 "Non-nil means, automatic citation display will revisit files if necessary.
1591 When nil, citation display in echo area will only be active for cached
1592 entries and for BibTeX database files with live associated buffers."
1593 :group
'reftex-viewing-cross-references
1596 (defcustom reftex-cache-cite-echo t
1597 "Non-nil means, echoed information for cite macros is cached.
1598 The information displayed in the echo area for cite macros is
1599 cached and even saved along with the parsing information. The
1600 cache survives document scans. In order to clear it, use M-x
1601 reftex-reset-mode <RET>."
1602 :group
'reftex-viewing-cross-references
1605 (defcustom reftex-display-copied-context-hook nil
1606 "Normal hook which is run before context is displayed anywhere.
1607 Designed for X-Symbol, but may have other uses as well."
1608 :group
'reftex-viewing-cross-references
1609 :group
'reftex-referencing-labels
1612 ;; Finding Files --------------------------------------------------------
1614 (defgroup reftex-finding-files nil
1615 "Finding files on search paths."
1618 (defcustom reftex-texpath-environment-variables
'("TEXINPUTS")
1619 "List of specifications how to retrieve the search path for TeX files.
1620 Several entries are possible.
1621 - If an element is the name of an environment variable, its content is used.
1622 - If an element starts with an exclamation mark, it is used as a command
1623 to retrieve the path. A typical command with the kpathsearch library would
1624 be `!kpsewhich -show-path=.tex'.
1625 - Otherwise the element itself is interpreted as a path.
1626 Multiple directories can be separated by the system dependent `path-separator'.
1627 Directories ending in `//' or `!!' will be expanded recursively.
1628 See also `reftex-use-external-file-finders'."
1629 :group
'reftex-finding-files
1630 :set
'reftex-set-dirty
1631 :type
'(repeat (string :tag
"Specification")))
1633 (defcustom reftex-bibpath-environment-variables
'("BIBINPUTS" "TEXBIB")
1634 "List of specifications how to retrieve search path for .bib database files.
1635 Several entries are possible.
1636 - If an element is the name of an environment variable, its content is used.
1637 - If an element starts with an exclamation mark, it is used as a command
1638 to retrieve the path. A typical command with the kpathsearch library would
1639 be `!kpsewhich -show-path=.bib'.
1640 - Otherwise the element itself is interpreted as a path.
1641 Multiple directories can be separated by the system dependent `path-separator'.
1642 Directories ending in `//' or `!!' will be expanded recursively.
1643 See also `reftex-use-external-file-finders'."
1644 :group
'reftex-citation-support
1645 :group
'reftex-finding-files
1646 :set
'reftex-set-dirty
1647 :type
'(repeat (string :tag
"Specification")))
1649 (defcustom reftex-file-extensions
'(("tex" .
(".tex" ".ltx"))
1651 "Association list with file extensions for different file types.
1652 This is a list of items, each item is like: (TYPE . (DEF-EXT OTHER-EXT ...))
1654 TYPE: File type like \"bib\" or \"tex\".
1655 DEF-EXT: The default extension for that file type, like \".tex\" or \".bib\".
1656 OTHER-EXT: Any number of other valid extensions for this file type.
1658 When a files is searched and it does not have any of the legal extensions,
1659 we try the default extension first, and then the naked file name.
1661 If you are using AUCTeX, you also need to add new extensions to
1662 TeX-file-extensions."
1663 :group
'reftex-finding-files
1664 :type
'(repeat (cons (string :tag
"File type")
1665 (repeat (string :tag
"Extension")))))
1667 (defcustom reftex-try-all-extensions nil
1668 "Non-nil means, try all extensions listed in `reftex-file-extensions'.
1669 When searching for a file, LaTeX uses only the default extension. However,
1670 if you are working with a noweb system that produces the .tex files from
1671 some other file, and you want RefTeX to scan the web file instead of the
1672 tex file, you need to set this option. You also need to make the noweb
1673 extension the default extension, i.e. the first in the list in
1674 `reftex-file-extensions'.
1675 Note that if you are using external file finders, this option has no effect."
1676 :group
'reftex-finding-files
1679 (defcustom reftex-search-unrecursed-path-first t
1680 "Non-nil means, search all specified directories before trying recursion.
1681 Thus, in a path \".//:/tex/\", search first \"./\", then \"/tex/\" and then
1682 all subdirectories of \"./\". If this option is nil, the subdirectories of
1683 \"./\" are searched before \"/tex/\". This is mainly for speed - most of the
1684 time the recursive path is for the system files and not for the user files.
1685 Set this to nil if the default makes RefTeX finding files with equal names
1687 :group
'reftex-finding-files
1690 (defcustom reftex-use-external-file-finders nil
1691 "Non-nil means, use external programs to find files.
1692 Normally, RefTeX searches the paths given in the environment variables
1693 TEXINPUTS and BIBINPUTS to find TeX files and BibTeX database files.
1694 With this option turned on, it calls an external program specified in the
1695 option `reftex-external-file-finders' instead. As a side effect,
1696 the variables `reftex-texpath-environment-variables' and
1697 `reftex-bibpath-environment-variables' will be ignored."
1698 :group
'reftex-finding-files
1701 (defcustom reftex-external-file-finders
'(("tex" .
"kpsewhich -format=.tex %f")
1702 ("bib" .
"kpsewhich -format=.bib %f"))
1703 "Association list with external programs to call for finding files.
1704 Each entry is a cons cell (TYPE . PROGRAM).
1705 TYPE is either \"tex\" or \"bib\". PROGRAM is the external program to use with
1706 any arguments. %f will be replaced by the name of the file to be found.
1707 Note that these commands will be executed directly, not via a shell.
1708 Only relevant when `reftex-use-external-file-finders' is non-nil."
1709 :group
'reftex-finding-files
1710 :type
'(repeat (cons (string :tag
"File type")
1711 (string :tag
"Program "))))
1713 ;; Tuning the parser ----------------------------------------------------
1715 (defgroup reftex-optimizations-for-large-documents nil
1716 "Configuration of parser speed and memory usage."
1719 (defcustom reftex-keep-temporary-buffers
1
1720 "Non-nil means, keep buffers created for parsing and lookup.
1721 RefTeX sometimes needs to visit files related to the current document.
1722 We distinguish files visited for
1723 PARSING: Parts of a multifile document loaded when (re)-parsing the document.
1724 LOOKUP: BibTeX database files and TeX files loaded to find a reference,
1725 to display label context, etc.
1726 The created buffers can be kept for later use, or be thrown away immediately
1727 after use, depending on the value of this variable:
1729 nil Throw away as much as possible.
1731 1 Throw away buffers created for parsing, but keep the ones created
1734 If a buffer is to be kept, the file is visited normally (which is potentially
1735 slow but will happen only once).
1736 If a buffer is to be thrown away, the initialization of the buffer depends
1737 upon the variable `reftex-initialize-temporary-buffers'."
1738 :group
'reftex-optimizations-for-large-documents
1740 (const :tag
"Throw away everything" nil
)
1741 (const :tag
"Keep everything" t
)
1742 (const :tag
"Keep lookup buffers only" 1)))
1744 (defcustom reftex-initialize-temporary-buffers nil
1745 "Non-nil means do initializations even when visiting file temporarily.
1746 When nil, RefTeX may turn off find-file hooks and other stuff to briefly
1748 When t, the full default initializations are done (find-file-hook etc.).
1749 Instead of t or nil, this variable may also be a list of hook functions to
1750 do a minimal initialization."
1751 :group
'reftex-optimizations-for-large-documents
1753 (const :tag
"Read files literally" nil
)
1754 (const :tag
"Fully initialize buffers" t
)
1755 (repeat :tag
"Hook functions" :value
(nil)
1758 (defcustom reftex-no-include-regexps
'("\\.pstex_t\\'")
1759 "List of regular expressions to exclude certain input files from parsing.
1760 If the name of a file included via \\include or \\input is matched by any
1761 of the regular expressions in this list, that file is not parsed by RefTeX."
1762 :group
'reftex-optimizations-for-large-documents
1763 :type
'(repeat (regexp)))
1765 (defcustom reftex-enable-partial-scans nil
1766 "Non-nil means, re-parse only 1 file when asked to re-parse.
1767 Re-parsing is normally requested with a `C-u' prefix to many RefTeX commands,
1768 or with the `r' key in menus. When this option is t in a multifile document,
1769 we will only parse the current buffer, or the file associated with the label
1770 or section heading near point in a menu. Requesting re-parsing of an entire
1771 multifile document then requires a `C-u C-u' prefix or the capital `R' key
1773 :group
'reftex-optimizations-for-large-documents
1776 (defcustom reftex-allow-automatic-rescan t
1777 "Non-nil means, RefTeX may rescan the document when this seems necessary.
1778 Currently this applies only to rescanning after label insertion, when
1779 the new label cannot be inserted correctly into the internal label
1781 :group
'reftex-optimizations-for-large-documents
1784 (defcustom reftex-save-parse-info nil
1785 "Non-nil means, save information gathered with parsing in a file.
1786 The file MASTER.rel in the same directory as MASTER.tex is used to save the
1787 information. When this variable is t,
1788 - accessing the parsing information for the first time in an editing session
1789 will read that file (if available) instead of parsing the document.
1790 - exiting Emacs or killing a buffer in `reftex-mode' will cause a new version
1791 of the file to be written."
1792 :group
'reftex-optimizations-for-large-documents
1795 (defcustom reftex-parse-file-extension
".rel"
1796 "File extension for the file in which parser information is stored.
1797 This extension is added to the base name of the master file."
1798 :group
'reftex-optimizations-for-large-documents
1801 (defcustom reftex-use-multiple-selection-buffers nil
1802 "Non-nil means use a separate selection buffer for each label type.
1803 These buffers are kept from one selection to the next and need not to be
1804 created for each use - so the menu generally comes up faster. The
1805 selection buffers will be erased (and therefore updated) automatically
1806 when new labels in its category are added. See the variable
1807 `reftex-auto-update-selection-buffers'."
1808 :group
'reftex-optimizations-for-large-documents
1809 :group
'reftex-referencing-labels
1812 (defcustom reftex-auto-update-selection-buffers t
1813 "Non-nil means, selection buffers will be updated automatically.
1814 When a new label is defined with `reftex-label', all selection buffers
1815 associated with that label category are emptied, in order to force an
1816 update upon next use. When nil, the buffers are left alone and have to be
1817 updated by hand, with the `g' key from the label selection process.
1818 The value of this variable will only have any effect when
1819 `reftex-use-multiple-selection-buffers' is non-nil."
1820 :group
'reftex-optimizations-for-large-documents
1821 :group
'reftex-referencing-labels
1824 ;; Fontification and Faces ----------------------------------------------
1826 (defgroup reftex-fontification-configurations nil
1827 "Options concerning the faces used in RefTeX."
1828 :link
'(custom-group-link :tag
"Font Lock Faces group" font-lock-faces
)
1831 (defcustom reftex-use-fonts t
1832 "Non-nil means, use fonts in *toc* and selection buffers.
1833 Font-lock must be loaded as well to actually get fontified display.
1834 When changing this option, a rescan may be necessary to activate the change."
1835 :group
'reftex-fontification-configurations
1838 (defcustom reftex-refontify-context
1
1839 "Non-nil means, re-fontify the context in the label menu with font-lock.
1840 This slightly slows down the creation of the label menu. It is only necessary
1841 when you definitely want the context fontified.
1843 This option may have 3 different values:
1844 nil Never refontify.
1846 1 Refontify when absolutely necessary, e.g. when old versions of X-Symbol.
1847 The option is ignored when `reftex-use-fonts' is nil."
1848 :group
'reftex-fontification-configurations
1849 :group
'reftex-referencing-labels
1851 (const :tag
"Never" nil
)
1852 (const :tag
"Always" t
)
1853 (const :tag
"When necessary" 1)))
1855 (defcustom reftex-highlight-selection
'cursor
1856 "Non-nil mean, highlight selected text in selection and *toc* buffers.
1857 Normally, the text near the cursor is the selected text, and it is
1858 highlighted. This is the entry most keys in the selection and *toc*
1859 buffers act on. However, if you mainly use the mouse to select an
1860 item, you may find it nice to have mouse-triggered highlighting
1861 instead or as well. The variable may have one of these values:
1863 nil No highlighting.
1864 cursor Highlighting is cursor driven.
1865 mouse Highlighting is mouse driven.
1866 both Both cursor and mouse trigger highlighting.
1868 Changing this variable requires to rebuild the selection and *toc* buffers
1869 to become effective (keys `g' or `r')."
1870 :group
'reftex-fontification-configurations
1872 (const :tag
"Never" nil
)
1873 (const :tag
"Cursor driven" cursor
)
1874 (const :tag
"Mouse driven" mouse
)
1875 (const :tag
"Mouse and Cursor driven." both
)))
1877 (defcustom reftex-cursor-selected-face
'highlight
1878 "Face name to highlight cursor selected item in toc and selection buffers.
1879 See also the variable `reftex-highlight-selection'."
1880 :group
'reftex-fontification-configurations
1882 (defcustom reftex-mouse-selected-face
'secondary-selection
1883 "Face name to highlight mouse selected item in toc and selection buffers.
1884 See also the variable `reftex-highlight-selection'."
1885 :group
'reftex-fontification-configurations
1887 (defcustom reftex-file-boundary-face
'font-lock-comment-face
1888 "Face name for file boundaries in selection buffer."
1889 :group
'reftex-fontification-configurations
1891 (defcustom reftex-label-face
'font-lock-constant-face
1892 "Face name for labels in selection buffer."
1893 :group
'reftex-fontification-configurations
1895 (defcustom reftex-section-heading-face
'font-lock-function-name-face
1896 "Face name for section headings in toc and selection buffers."
1897 :group
'reftex-fontification-configurations
1899 (defcustom reftex-toc-header-face
'font-lock-comment-face
1900 "Face name for the header of a toc buffer."
1901 :group
'reftex-fontification-configurations
1903 (defcustom reftex-bib-author-face
'font-lock-keyword-face
1904 "Face name for author names in bib selection buffer."
1905 :group
'reftex-fontification-configurations
1907 (defcustom reftex-bib-year-face
'font-lock-comment-face
1908 "Face name for year in bib selection buffer."
1909 :group
'reftex-fontification-configurations
1911 (defcustom reftex-bib-title-face
'font-lock-function-name-face
1912 "Face name for article title in bib selection buffer."
1913 :group
'reftex-fontification-configurations
1915 (defcustom reftex-bib-extra-face
'font-lock-comment-face
1916 "Face name for bibliographic information in bib selection buffer."
1917 :group
'reftex-fontification-configurations
1919 (defcustom reftex-select-mark-face
'bold
1920 "Face name for marked entries in the selection buffers."
1921 :group
'reftex-fontification-configurations
1923 (defcustom reftex-index-header-face
'font-lock-comment-face
1924 "Face name for the header of an index buffer."
1925 :group
'reftex-fontification-configurations
1927 (defcustom reftex-index-section-face
'font-lock-function-name-face
1928 "Face name for the start of a new letter section in the index."
1929 :group
'reftex-fontification-configurations
1931 (defcustom reftex-index-tag-face
'font-lock-keyword-face
1932 "Face name for index names (for multiple indices)."
1933 :group
'reftex-fontification-configurations
1935 (defcustom reftex-index-face
'font-lock-constant-face
1936 "Face name for index entries."
1937 :group
'reftex-fontification-configurations
1940 (defcustom reftex-pre-refontification-functions nil
1941 "X-Symbol specific hook.
1942 Functions get two arguments, the buffer from where the command started and a
1943 symbol indicating in what context the hook is called."
1944 :group
'reftex-fontification-configurations
1947 ;; Miscellaneous configurations -----------------------------------------
1949 (defgroup reftex-miscellaneous-configurations nil
1950 "Collection of further configurations."
1953 (defcustom reftex-extra-bindings nil
1954 "Non-nil means, make additional key bindings on startup.
1955 These extra bindings are located in the users `C-c letter' map."
1956 :group
'reftex-miscellaneous-configurations
1959 (defcustom reftex-plug-into-AUCTeX nil
1960 "Plug-in flags for AUCTeX interface.
1961 This variable is a list of 5 boolean flags. When a flag is non-nil,
1964 - supply labels in new sections and environments (flag 1)
1965 - supply arguments for macros like `\\label'. (flag 2)
1966 - supply arguments for macros like `\\ref'. (flag 3)
1967 - supply arguments for macros like `\\cite'. (flag 4)
1968 - supply arguments for macros like `\\index'. (flag 5)
1970 You may also set the variable itself to t or nil in order to turn all
1971 plug-ins on or off, respectively.
1972 \\<LaTeX-mode-map>Supplying labels in new sections and environments applies when creating
1973 sections with \\[LaTeX-section] and environments with \\[LaTeX-environment].
1974 Supplying macro arguments applies when you insert such a macro interactively
1975 with \\[TeX-insert-macro].
1976 See the AUCTeX documentation for more information.
1977 RefTeX uses `fset' to take over the function calls. Changing the variable
1978 may require a restart of Emacs in order to become effective."
1979 :group
'reftex-miscellaneous-configurations
1982 (const :tag
"No plug-ins" nil
)
1983 (const :tag
"All possible plug-ins" t
)
1985 :tag
"Individual choice"
1987 (boolean :tag
"supply label in new sections and environments")
1988 (boolean :tag
"supply argument for macros like `\\label' ")
1989 (boolean :tag
"supply argument for macros like `\\ref' ")
1990 (boolean :tag
"supply argument for macros like `\\cite' ")
1991 (boolean :tag
"supply argument for macros like `\\index' "))))
1993 (defcustom reftex-allow-detached-macro-args nil
1994 "Non-nil means, allow arguments of macros to be detached by whitespace.
1995 When this is t, `aaa' will be considered as argument of \\bb in the following
1996 construct: \\bbb [xxx] {aaa}."
1997 :group
'reftex-miscellaneous-configurations
2001 (defcustom reftex-load-hook nil
2002 "Hook which is being run when loading reftex.el."
2003 :group
'reftex-miscellaneous-configurations
2006 (defcustom reftex-mode-hook nil
2007 "Hook which is being run when turning on RefTeX mode."
2008 :group
'reftex-miscellaneous-configurations
2012 (provide 'reftex-vars
)
2014 ;;; reftex-vars.el ends here