cgit.sxemacs.org Git - packages/blob - xemacs-packages/reftex/reftex-vars.el

   1 ;;; reftex-vars.el --- configuration variables for RefTeX
   2 ;; Copyright (c) 1997, 1998, 1999, 2003 Free Software Foundation, Inc.
   3
   4 ;; Author: Carsten Dominik <dominik@science.uva.nl>
   5 ;; Version: 4.21
   6
   7 ;; This file is part of GNU Emacs.
   8
   9 ;; GNU Emacs is free software; you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation; either version 2, or (at your option)
  12 ;; any later version.
  13
  14 ;; GNU Emacs is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE   See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs; see the file COPYING  If not, write to the
  21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22 ;; Boston, MA 02111-1307, USA.
  23
  24 ;;; Commentary:
  25
  26 ;;; Code:
  27
  28 (eval-when-compile (require 'cl))
  29 (eval-and-compile
  30   (defun reftex-set-dirty (symbol value)
  31     (setq reftex-tables-dirty t)
  32     (set symbol value)))
  33
  34 ;; Define the two constants which are needed during compilation
  35
  36 (eval-and-compile
  37 (defconst reftex-label-alist-builtin
  38   '(
  39     ;; Some aliases, mostly for backward compatibility
  40     (Sideways    "Alias for -->rotating" (rotating))
  41     (AMSTeX      "amsmath with eqref macro"
  42                  ((nil ?e nil "~\\eqref{%s}")
  43                   amsmath))
  44
  45     ;; Individual package defaults
  46     (amsmath "AMS-LaTeX math environments"
  47      (("align"        ?e nil nil eqnarray-like)
  48       ("gather"       ?e nil nil eqnarray-like)
  49       ("multline"     ?e nil nil t)
  50       ("flalign"      ?e nil nil eqnarray-like)
  51       ("alignat"      ?e nil nil alignat-like)
  52       ("xalignat"     ?e nil nil alignat-like)
  53       ("xxalignat"    ?e nil nil alignat-like)
  54       ("subequations" ?e nil nil t)))
  55
  56     (endnotes "The \\endnote macro"
  57      (("\\endnote[]{}" ?N "en:" "~\\ref{%s}" 2
  58        (regexp "endnotes?" "notes?" "Anmerkung\\(en\\)?" "Anm\\."))))
  59
  60     (fancybox "The Beqnarray environment"
  61      (("Beqnarray" ?e nil nil eqnarray-like)))
  62
  63     (floatfig "The floatingfigure environment"
  64      (("floatingfigure" ?f nil nil caption)))
  65
  66     (longtable   "The longtable environment"
  67      (("longtable"  ?t nil nil caption)))
  68
  69     (picinpar    "The figwindow and tabwindow environments"
  70      (("figwindow" ?f nil nil 1)
  71       ("tabwindow" ?f nil nil 1)))
  72
  73     (rotating    "Sidewaysfigure and table"
  74      (("sidewaysfigure" ?f nil nil caption)
  75       ("sidewaystable"  ?t nil nil caption)))
  76
  77     (sidecap      "CSfigure and SCtable"
  78      (("SCfigure"       ?f nil nil caption)
  79       ("SCtable"        ?t nil nil caption)))
  80
  81     (subfigure   "Subfigure environments/macro"
  82      (("subfigure"   ?f nil nil caption)
  83       ("subfigure*"  ?f nil nil caption)
  84       ("\\subfigure[]{}" ?f nil nil 1)))
  85
  86     (supertab    "Supertabular environment"
  87      (("supertabular" ?t nil nil "\\tablecaption{")))
  88
  89     (wrapfig     "The wrapfigure environment"
  90      (("wrapfigure" ?f nil nil caption)))
  91
  92     ;; The LaTeX core stuff
  93     (LaTeX       "LaTeX default environments"
  94      (("section"   ?s "%S" "~\\ref{%s}" (nil . t)
  95        (regexp "parts?" "chapters?" "chap\\." "sections?" "sect?\\."
  96                "paragraphs?" "par\\."
  97                "\\\\S" "\247" "Teile?" "Kapitel" "Kap\\." "Abschnitte?"
  98                "appendi\\(x\\|ces\\)" "App\\."  "Anh\"?ange?" "Anh\\."))
  99
 100       ("enumerate" ?i "item:" "~\\ref{%s}" item
 101        (regexp "items?" "Punkte?"))
 102
 103       ("equation"  ?e "eq:" "~(\\ref{%s})" t
 104        (regexp "equations?" "eqs?\\." "eqn\\." "Gleichung\\(en\\)?"  "Gl\\."))
 105       ("eqnarray"  ?e "eq:" nil eqnarray-like)
 106
 107       ("figure"    ?f "fig:" "~\\ref{%s}" caption
 108        (regexp "figure?[sn]?" "figs?\\." "Abbildung\\(en\\)?" "Abb\\."))
 109       ("figure*"   ?f nil nil caption)
 110
 111       ("table"     ?t "tab:" "~\\ref{%s}" caption
 112        (regexp "tables?" "tab\\." "Tabellen?"))
 113       ("table*"    ?t nil nil caption)
 114
 115       ("\\footnote[]{}" ?n "fn:" "~\\ref{%s}" 2
 116        (regexp "footnotes?" "Fussnoten?"))
 117
 118       ("any"       ?\  " "   "~\\ref{%s}" nil)
 119
 120       ;; The label macro is hard coded, but it *could* be defined like this:
 121       ;;("\\label{*}" nil nil nil nil)
 122       ))
 123
 124     )
 125   "The default label environment descriptions.
 126 Lower-case symbols correspond to a style file of the same name in the LaTeX
 127 distribution.  Mixed-case symbols are convenience aliases.")
 128
 129 (defconst reftex-cite-format-builtin
 130   '((default "Default macro \\cite{%l}"
 131       "\\cite{%l}")
 132     (natbib "The Natbib package"
 133      ((?\C-m . "\\cite{%l}")
 134       (?t    . "\\citet{%l}")
 135       (?T    . "\\citet*{%l}")
 136       (?p    . "\\citep{%l}")
 137       (?P    . "\\citep*{%l}")
 138       (?e    . "\\citep[e.g.][]{%l}")
 139       (?s    . "\\citep[see][]{%l}")
 140       (?a    . "\\citeauthor{%l}")
 141       (?A    . "\\citeauthor*{%l}")
 142       (?y    . "\\citeyear{%l}")
 143       (?n    . "\\nocite{%l}")))
 144     (amsrefs "The AMSRefs package"
 145      ((?\C-m . "\\cite{%l}")
 146       (?p    . "\\cite{%l}")
 147       (?P    . "\\cites{%l}")
 148       (?t    . "\\ocite{%l}")
 149       (?T    . "\\ocites{%l}")
 150       (?y    . "\\ycite{%l}")
 151       (?Y    . "\\ycites{%l}")
 152       (?a    . "\\citeauthor{%l}")
 153       (?A    . "\\citeauthory{%l}")
 154       (?f    . "\\fullcite{%l}")
 155       (?F    . "\\fullocite{%l}")
 156       (?n    . "\\nocite{%l}")))
 157     (bibentry "The Bibentry package"
 158       "\\bibentry{%l}")
 159     (harvard "The Harvard package"
 160      ((?\C-m . "\\cite{%l}")
 161       (?p    . "\\cite{%l}")
 162       (?t    . "\\citeasnoun{%l}")
 163       (?n    . "\\citeasnoun{%l}")
 164       (?s    . "\\possessivecite{%l}")
 165       (?e    . "\\citeaffixed{%l}{?}")
 166       (?y    . "\\citeyear{%l}")
 167       (?a    . "\\citename{%l}")))
 168     (chicago "The Chicago package"
 169      ((?\C-m . "\\cite{%l}")
 170       (?t    . "\\citeN{%l}")
 171       (?T    . "\\shortciteN{%l}")
 172       (?p    . "\\cite{%l}")
 173       (?P    . "\\shortcite{%l}")
 174       (?a    . "\\citeA{%l}")
 175       (?A    . "\\shortciteA{%l}")
 176       (?y    . "\\citeyear{%l}")))
 177     (astron "The Astron package"
 178      ((?\C-m . "\\cite{%l}")
 179       (?p    . "\\cite{%l}" )
 180       (?t    . "%2a (\\cite{%l})")))
 181     (author-year "Do-it-yourself Author-year"
 182      ((?\C-m . "\\cite{%l}")
 183       (?t    . "%2a (%y)\\nocite{%l}")
 184       (?p    . "(%2a %y\\nocite{%l})")))
 185     (locally     "Full info in parenthesis"
 186      "(%2a %y, %j %v, %P, %e: %b, %u, %s %<)")
 187     )
 188   "Builtin versions of the citation format.
 189 The following conventions are valid for all alist entries:
 190 `?\C-m' should always point to a straight \\cite{%l} macro.
 191 `?t'    should point to a textual citation (citation as a noun).
 192 `?p'    should point to a parenthetical citation.")
 193
 194 (defconst reftex-index-macros-builtin
 195   '((default "Default \\index and \\glossary macros"
 196       (("\\index{*}" "idx" ?i "" nil t)
 197        ("\\glossary{*}" "glo" ?g "" nil t)))
 198     (multind "The multind.sty package"
 199        (("\\index{}{*}" 1 ?i "" nil t)))
 200     (index "The index.sty package"
 201            (("\\index[]{*}" 1 ?i "" nil t)
 202             ("\\index*[]{*}" 1 ?I "" nil nil)))
 203     (Index-Shortcut "index.sty with \\shortindexingon"
 204        (("\\index[]{*}" 1 ?i "" nil t)
 205         ("\\index*[]{*}" 1 ?I "" nil nil)
 206         ("^[]{*}" 1 ?^ "" texmathp t)
 207         ("_[]{*}" 1 ?_ "" texmathp nil))))
 208   "Builtin stuff for reftex-index-macros.
 209 Lower-case symbols correspond to a style file of the same name in the LaTeX
 210 distribution.  Mixed-case symbols are convenience aliases.")
 211 )
 212
 213 ;; Configuration Variables and User Options for RefTeX ------------------
 214
 215 (defgroup reftex nil
 216   "LaTeX label and citation support."
 217   :tag "RefTeX"
 218   :link '(url-link :tag "Home Page"
 219                    "http://zon.astro.uva.nl/~dominik/Tools/")
 220   :link '(emacs-commentary-link :tag "Commentary in reftex.el" "reftex.el")
 221   :link '(custom-manual "(reftex)Top")
 222   :prefix "reftex-"
 223   :group 'tex)
 224
 225
 226 ;; Table of contents configuration --------------------------------------
 227
 228 (defgroup reftex-table-of-contents-browser nil
 229   "A multifile table of contents browser."
 230   :group 'reftex)
 231
 232 (defcustom reftex-include-file-commands '("include" "input")
 233   "LaTeX commands which input another file.
 234 The file name is expected after the command, either in braces or separated
 235 by whitespace."
 236   :group 'reftex-table-of-contents-browser
 237   :type '(repeat string))
 238
 239 (defcustom reftex-max-section-depth 12
 240   "Maximum depth of section levels in document structure.
 241 Standard LaTeX needs default is 7, but there are packages for which this
 242 needs to be larger."
 243   :group 'reftex-table-of-contents-browser
 244   :type 'integer)
 245
 246 ;; LaTeX section commands and level numbers
 247 (defcustom reftex-section-levels
 248   '(
 249     ("part"            .  0)
 250     ("chapter"         .  1)
 251     ("section"         .  2)
 252     ("subsection"      .  3)
 253     ("subsubsection"   .  4)
 254     ("paragraph"       .  5)
 255     ("subparagraph"    .  6)
 256     ("addchap"         . -1) ; KOMA-Script
 257     ("addsec"          . -2) ; KOMA-Script
 258 ;;; ("minisec"         . -7) ; KOMA-Script
 259     )
 260   "Commands and levels used for defining sections in the document.
 261 This is an alist with each element like (COMMAND-NAME . LEVEL).
 262 The car of each cons cell is the name of the section macro (without
 263 the backslash).  The cdr is a number indicating its level.  A negative
 264 level means the same level as the positive value, but the section will
 265 never get a number.  The cdr may also be a function which will be called
 266 to after the section-re matched to determine the level.
 267 This list is also used for promotion and demption of sectioning commands.
 268 If you are using a document class which has several sets of sectioning
 269 commands, promotion only works correctly if this list is sorted first
 270 by set, then within each set by level.  The promotion commands always
 271 select the nearest entry with the correct new level."
 272   :group 'reftex-table-of-contents-browser
 273   :set 'reftex-set-dirty
 274   :type '(repeat
 275           (cons (string :tag "sectioning macro" "")
 276                 (choice
 277                  (number :tag "level           " 0)
 278                  (symbol :tag "function        " my-level-func)))))
 279
 280 (defcustom reftex-toc-max-level 100
 281   "*The maximum level of toc entries which will be included in the TOC.
 282 Section headings with a bigger level will be ignored.  In RefTeX, chapters
 283 are level 1, sections are level 2 etc.
 284 This variable can be changed from within the *toc* buffer with the `t' key."
 285   :group 'reftex-table-of-contents-browser
 286   :type 'integer)
 287
 288 (defcustom reftex-part-resets-chapter nil
 289   "*Non-nil means, \\part is like any other sectioning command.
 290 This means, part numbers will be included in the numbering of chapters, and
 291 chapter counters will be reset for each part.
 292 When nil (the default), parts are special, do not reset the chapter counter
 293 and also do not show up in chapter numbers."
 294   :group 'reftex-table-of-contents-browser
 295   :type 'boolean)
 296
 297
 298 (defcustom reftex-auto-recenter-toc 'frame
 299   "*Non-nil means, turn automatic recentering of *TOC* window on.
 300 When active, the *TOC* window will always show the section you
 301 are currently working in.  Recentering happens whenever Emacs is idle for
 302 more than `reftex-idle-time' seconds.
 303
 304 Value t means, turn on immediately when RefTeX gets started.  Then,
 305 recentering will work for any toc window created during the session.
 306
 307 Value 'frame (the default) means, turn automatic recentering on only while the
 308 dedicated TOC frame does exist, and do the recentering only in that frame.  So
 309 when creating that frame (with \"d\" key in an ordinary TOC window), the
 310 automatic recentering is turned on.  When the frame gets destroyed, automatic
 311 recentering is turned off again.
 312
 313 This feature can be turned on and off from the menu
 314 \(Ref->Options)."
 315   :group 'reftex-table-of-contents-browser
 316   :type '(choice
 317           (const :tag "never" nil)
 318           (const :tag "always" t)
 319           (const :tag "in dedicated frame only" frame)))
 320
 321 (defcustom reftex-toc-split-windows-horizontally nil
 322   "*Non-nil means, create TOC window by splitting window horizontally."
 323   :group 'reftex-table-of-contents-browser
 324   :type 'boolean)
 325
 326 (defcustom reftex-toc-split-windows-fraction .3
 327   "*Fraction of the width or height of the frame to be used for TOC window.
 328 See also `reftex-toc-split-windows-horizontally'."
 329   :group 'reftex-table-of-contents-browser
 330   :type 'number)
 331
 332 (defvar reftex-toc-split-windows-horizontally-fraction 0.5
 333   "This variable is obsolete, use `reftex-toc-split-windows-fraction' instead.")
 334
 335 (defcustom reftex-toc-keep-other-windows t
 336   "*Non-nil means, split the selected window to display the *toc* buffer.
 337 This helps to keep the window configuration, but makes the *toc* small.
 338 When nil, all other windows except the selected one will be deleted, so
 339 that the *toc* window fills half the frame."
 340   :group 'reftex-table-of-contents-browser
 341   :type 'boolean)
 342
 343 (defcustom reftex-toc-include-file-boundaries nil
 344   "*Non-nil means, include file boundaries in *toc* buffer.
 345 This flag can be toggled from within the *toc* buffer with the `F' key."
 346   :group 'reftex-table-of-contents-browser
 347   :type 'boolean)
 348
 349 (defcustom reftex-toc-include-labels nil
 350   "*Non-nil means, include labels in *toc* buffer.
 351 This flag can be toggled from within the *toc* buffer with the `l' key."
 352   :group 'reftex-table-of-contents-browser
 353   :type 'boolean)
 354
 355 (defcustom reftex-toc-include-index-entries nil
 356   "*Non-nil means, include index entries in *toc* buffer.
 357 This flag can be toggled from within the *toc* buffer with the `i' key."
 358   :group 'reftex-table-of-contents-browser
 359   :type 'boolean)
 360
 361 (defcustom reftex-toc-confirm-promotion 2
 362   "*Non-nil means, promotion/demotion commands first prompt for confirmation.
 363 When nil, the command is executed immediately.  When this is an integer
 364 N, ask for confirmation only if N or more section commands are going to be
 365 changed."
 366   :group 'reftex-table-of-contents-browser
 367   :type '(choice
 368           (const  :tag "Never" nil)
 369           (const  :tag "Always" t)
 370           (number :tag "When more than N sections" :value 2)))
 371
 372 (defcustom reftex-toc-include-context nil
 373   "*Non-nil means, include context with labels in the *toc* buffer.
 374 Context will only be shown when labels are visible as well.
 375 This flag can be toggled from within the *toc* buffer with the `c' key."
 376   :group 'reftex-table-of-contents-browser
 377   :type 'boolean)
 378
 379 (defcustom reftex-toc-follow-mode nil
 380   "*Non-nil means, point in *toc* buffer will cause other window to follow.
 381 The other window will show the corresponding part of the document.
 382 This flag can be toggled from within the *toc* buffer with the `f' key."
 383   :group 'reftex-table-of-contents-browser
 384   :type 'boolean)
 385
 386 (defcustom reftex-revisit-to-follow nil
 387   "*Non-nil means, follow-mode will revisit files if necessary.
 388 When nil, follow-mode will be suspended for stuff in unvisited files."
 389   :group 'reftex-table-of-contents-browser
 390   :group 'reftex-referencing-labels
 391   :type 'boolean)
 392
 393 (defcustom reftex-toc-mode-hook nil
 394   "Mode hook for reftex-toc-mode."
 395   :group 'reftex-table-of-contents-browser
 396   :type 'hook)
 397
 398 ;; Label Support Configuration
 399
 400 (defgroup reftex-label-support nil
 401   "Support for creation, insertion and referencing of labels in LaTeX."
 402   :group 'reftex)
 403
 404 (defgroup reftex-defining-label-environments nil
 405   "Definition of environments and macros to do with label."
 406   :group 'reftex-label-support)
 407
 408 (defcustom reftex-default-label-alist-entries
 409   '(amsmath endnotes fancybox floatfig longtable picinpar
 410             rotating sidecap subfigure supertab wrapfig LaTeX)
 411   "Default label alist specifications.  LaTeX should always be the last entry.
 412 The value of this variable is a list of symbols with associations in the
 413 constant `reftex-label-alist-builtin'.  Check that constant for a full list
 414 of options."
 415   :group 'reftex-defining-label-environments
 416   :set   'reftex-set-dirty
 417   :type `(set
 418           :indent 4
 419           :inline t
 420           :greedy t
 421           ,@(mapcar
 422              (lambda (x)
 423                (list 'const :tag (concat (symbol-name (nth 0 x))
 424                                          ": " (nth 1 x))
 425                      (nth 0 x)))
 426              reftex-label-alist-builtin)))
 427
 428 (defcustom reftex-label-alist nil
 429   "Alist with information on environments for \\label-\\ref use.
 430
 431 This docstring is easier to understand after reading the configuration
 432 examples in `reftex.el'.  Looking at the builtin defaults in the constant
 433 `reftex-label-alist-builtin' may also be instructive.
 434
 435 Set this variable to define additions and changes to the default.  The only
 436 things you MUST NOT change is that `?s' is the type indicator for section
 437 labels, and SPC for the `any' label type.  These are hard-coded at other
 438 places in the code.
 439
 440 The value of the variable must be a list of items.  Each item is a list
 441 itself and has the following structure:
 442
 443  (ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT CONTEXT-METHOD
 444            (MAGIC-WORD ... ) TOC-LEVEL)
 445
 446 Each list entry describes either an environment carrying a counter for use
 447 with \\label and \\ref, or a LaTeX macro defining a label as (or inside)
 448 one of its arguments.  The elements of each list entry are:
 449
 450 ENV-OR-MACRO
 451     Name of the environment (like \"table\") or macro (like \"\\\\myfig\").
 452     For macros, indicate the macro arguments for best results, as in
 453     \"\\\\myfig[]{}{}{*}{}\".  Use square brackets for optional arguments,
 454     a star to mark the label argument, if any.  The macro does not have to
 455     have a label argument - you could also use \\label{..} inside one of
 456     its arguments.
 457     Special names: `section' for section labels, `any' to define a group
 458     which contains all labels.
 459
 460     This may also be a function to do local parsing and identify point
 461     to be in a non-standard label environment.  The function must take
 462     an argument BOUND and limit backward searches to this value.  It
 463     should return either nil or a cons cell (FUNCTION . POSITION) with
 464     the function symbol and the position where the special environment
 465     starts.  See the Info documentation for an example.
 466
 467     Finally this may also be nil if the entry is only meant to change
 468     some settings associated with the type indicator character (see below).
 469
 470 TYPE-KEY
 471     Type indicator character, like `?t', must be a printable ASCII character.
 472     The type indicator is a single character which defines a label type.
 473     Any label inside the environment or macro is assumed to belong to this
 474     type.  The same character may occur several times in this list, to cover
 475     cases in which different environments carry the same label type (like
 476     `equation' and `eqnarray').
 477     If the type indicator is nil and the macro has a label argument {*},
 478     the macro defines neutral labels just like \\label.  In this case
 479     the reminder of this entry is ignored.
 480
 481 LABEL-PREFIX
 482     Label prefix string, like \"tab:\".
 483     The prefix is a short string used as the start of a label.  It may be the
 484     empty string.  The prefix may contain the following `%' escapes:
 485        %f   Current file name with directory and extension stripped.
 486        %F   Current file name relative to directory of master file.
 487        %u   User login name, on systems which support this.
 488        %S   A section prefix derived with variable `reftex-section-prefixes'.
 489
 490     Example: In a file `intro.tex', \"eq:%f:\" will become \"eq:intro:\").
 491
 492 REFERENCE-FORMAT
 493     Format string for reference insert in buffer.  `%s' will be replaced by
 494     the label.
 495     When the format starts with `~', the `~' will only be inserted if
 496     there is not already a whitespace before point.
 497
 498 CONTEXT-METHOD
 499     Indication on how to find the short context.
 500     - If nil, use the text following the \\label{...} macro.
 501     - If t, use
 502        - the section heading for section labels.
 503        - text following the \\begin{...} statement of environments.
 504          (not a good choice for environments like eqnarray or enumerate,
 505          where one has several labels in a single environment).
 506        - text after the macro name (starting with the first arg) for macros.
 507     - If an integer, use the nth argument of the macro.  As a special case,
 508       1000 means to get text after the last macro argument.
 509     - If a string, use as regexp to search *backward* from the label.  Context
 510       is then the text following the end of the match.  E.g. putting this to
 511       \"\\\\\\\\caption[[{]\" will use the caption in a figure or table
 512       environment.
 513       \"\\\\\\\\begin{eqnarray}\\\\|\\\\\\\\\\\\\\\\\" works for eqnarrays.
 514     - If any of `caption', `item', `eqnarray-like', `alignat-like', this
 515       symbol will internally be translated into an appropriate regexp
 516       (see also the variable `reftex-default-context-regexps').
 517     - If a function, call this function with the name of the environment/macro
 518       as argument.  On call, point will be just after the \\label macro.  The
 519       function is expected to return a suitable context string.  It should
 520       throw an exception (error) when failing to find context.
 521       As an example, here is a function returning the 10 chars following
 522       the label macro as context:
 523
 524         (defun my-context-function (env-or-mac)
 525           (if (> (point-max) (+ 10 (point)))
 526               (buffer-substring (point) (+ 10 (point)))
 527             (error \"Buffer too small\")))
 528
 529     Label context is used in two ways by RefTeX: For display in the label
 530     menu, and to derive a label string.  If you want to use a different
 531     method for each of these, specify them as a dotted pair.
 532     E.g. `(nil . t)' uses the text after the label (nil) for display, and
 533     text from the default position (t) to derive a label string.  This is
 534     actually used for section labels.
 535
 536 MAGIC-WORDS
 537     List of magic words which identify a reference to be of this type.
 538     If the word before point is equal to one of these words when calling
 539     `reftex-reference', the label list offered will be automatically
 540     restricted to labels of the correct type.
 541     If the first element of this wordlist is the symbol `regexp', the
 542     strings are interpreted as regular expressions.  RefTeX will add
 543     a \"\\\\W\" to the beginning and other stuff to the end of the regexp.
 544
 545 TOC-LEVEL
 546     The integer level at which this environment should be added to the
 547     table of contents.  See also `reftex-section-levels'.  A positive
 548     value will number the entries mixed with the sectioning commands of
 549     the same level.  A negative value will make unnumbered entries.
 550     Useful only for theorem-like environments, will be ignored for macros.
 551     When omitted or nil, no TOC entries will be made.
 552
 553 If the type indicator characters of two or more entries are the same, RefTeX
 554 will use
 555  - the first non-nil format and prefix
 556  - the magic words of all involved entries.
 557
 558 Any list entry may also be a symbol.  If that has an association in
 559 `reftex-label-alist-builtin', the cddr of that association is spliced into the
 560 list.  However, builtin defaults should normally be set with the variable
 561 `reftex-default-label-alist-entries."
 562   :group 'reftex-defining-label-environments
 563   :set 'reftex-set-dirty
 564   :type
 565   `(repeat
 566     (choice :tag "Package or Detailed   "
 567      :value ("" ?a nil nil nil nil)
 568      (list :tag "Detailed Entry"
 569            :value ("" ?a nil nil nil nil)
 570            (choice    :tag "Environment or \\macro "
 571                       (const  :tag "Ignore, just use typekey" nil)
 572                       (string "")
 573                       (symbol :tag "Special parser" my-parser))
 574            (choice    :tag "Type specification    "
 575                       (const :tag "unspecified, like in \\label" nil)
 576                       (character :tag "Char  " ?a))
 577            (choice    :tag "Label prefix string   "
 578                       (const  :tag "Default" nil)
 579                       (string :tag "String" "lab:"))
 580            (choice    :tag "Label reference format"
 581                       (const  :tag "Default" nil)
 582                       (string :tag "String" "~\\ref{%s}"))
 583            (choice    :tag "Context method        "
 584                       (const  :tag "Default position" t)
 585                       (const  :tag "After label"      nil)
 586                       (number :tag "Macro arg nr" 1)
 587                       (regexp :tag "Regexp" "")
 588                       (const  :tag "Caption in float" caption)
 589                       (const  :tag "Item in list" item)
 590                       (const  :tag "Eqnarray-like" eqnarray-like)
 591                       (const  :tag "Alignat-like" alignat-like)
 592                       (symbol :tag "Function" my-func))
 593            (repeat :tag "Magic words" :extra-offset 2 (string))
 594            (option (choice :tag "Make TOC entry     "
 595                            (const :tag "No entry" nil)
 596                            (integer :tag "Level" :value -3))))
 597      (choice
 598       :tag "Package"
 599       :value AMSTeX
 600       ,@(mapcar
 601          (lambda (x)
 602            (list 'const :tag (concat (symbol-name (nth 0 x)))
 603                  (nth 0 x)))
 604          reftex-label-alist-builtin)))))
 605
 606 (defcustom reftex-section-prefixes '((0 . "part:") (1 . "cha:") (t . "sec:"))
 607   "Prefixes for section labels.
 608 When the label prefix given in an entry in `reftex-label-alist' contains `%S',
 609 this list is used to determine the correct prefix string depending on the
 610 current section level.
 611 The list is an alist, with each entry of the form (KEY . PREFIX)
 612 Possible keys are sectioning macro names like `chapter', section levels
 613 \(as given in `reftex-section-levels'), and t for the default."
 614   :group 'reftex-defining-label-environments
 615   :type '(repeat
 616           (cons :value (0 . "")
 617                 (choice
 618                  (string :tag  "macro name")
 619                  (integer :tag "section level")
 620                  (const :tag "default" t))
 621                 (string :tag "Prefix"))))
 622
 623 (defcustom reftex-default-context-regexps
 624   '((caption       . "\\\\\\(rot\\)?caption\\*?[[{]")
 625     (item          . "\\\\item\\(\\[[^]]*\\]\\)?")
 626     (eqnarray-like . "\\\\begin{%s}\\|\\\\\\\\")
 627     (alignat-like  . "\\\\begin{%s}{[0-9]*}\\|\\\\\\\\"))
 628 "Alist with default regular expressions for finding context.
 629 The form (format regexp (regexp-quote environment)) is used to calculate
 630 the final regular expression - so %s will be replaced with the environment
 631 or macro."
 632   :group 'reftex-defining-label-environments
 633   :type '(repeat (cons (symbol) (regexp))))
 634
 635 (defcustom reftex-special-environment-functions nil
 636   "List of functions to be called when trying to figure out current environment.
 637 These are special functions to detect \"environments\" which do not
 638 start with \\begin and end with \\end.  Some LaTeX packages seem to
 639 use such non-standard ways to set up environment-like constructs.  The
 640 purpose of each function in this list is to detect if point is
 641 currently inside such a special \"environment\".  If the environment
 642 carries a label, you must also set up an entry for it in
 643 `reftex-label-alist'.
 644
 645 The function should check if point is currently in the special
 646 environment it was written to detect.  If so, the function must return
 647 a cons cell (NAME . POSITION).  NAME is the name of the environment
 648 detected and POSITION is the buffer position where the environment
 649 starts.  The function must return nil on failure to detect the
 650 environment.
 651
 652 The function must take an argument BOUND.  If non-nil, BOUND is a
 653 boundary for backwards searches which should be observed.
 654
 655 Here is an example.  The LaTeX package linguex.sty defines list macros
 656 `\\ex.', `\\a.', etc for lists which are terminated by `\\z.' or an empty
 657 line.
 658
 659     \\ex.  \\label{ex:12} Some text in an exotic language ...
 660           \\a. \\label{ex:13} more stuff
 661           \\b. \\label{ex:14} still more stuff
 662
 663     ... more text after the empty line terminating all lists
 664
 665 And here is the setup for RefTeX:
 666
 667 1. Define a dummy environment for this in `reftex-label-alist'.  Dummy means,
 668    make up an environment name even though it is not used with \\begin and
 669    \\end.  Here we use \"linguex\" as this name.
 670
 671    (setq reftex-label-alist
 672          '((\"linguex\" ?x \"ex:\" \"~\\\\ref{%s}\" nil (\"Example\" \"Ex.\"))))
 673
 674 2. Write a function to detect the list macros and the determinators as well.
 675
 676    (defun my-detect-linguex-list (bound)
 677      (let ((pos (point)) p1)
 678        (save-excursion
 679          ;; Search for any of the linguex item macros at the beginning of a line
 680          (if (re-search-backward
 681               \"^[ \\t]*\\\\(\\\\\\\\\\\\(ex\\\\|a\\\\|b\\\\|c\\\\|d\\\\|e\\\\|f\\\\)g?\\\\.\\\\)\" bound t)
 682              (progn
 683                (setq p1 (match-beginning 1))
 684                ;; Make sure no empty line or \\z. is between us and the item macro
 685                (if (re-search-forward \"\\n[ \\t]*\\n\\\\|\\\\\\\\z\\\\.\" pos t)
 686                    ;; Return nil because list was already closed
 687                    nil
 688                  ;; OK, we got it
 689                  (cons \"linguex\" p1)))
 690            ;; Return nil for not found
 691            nil))))
 692
 693 3. Tell RefTeX to use this function
 694
 695    (setq reftex-special-environment-functions '(my-detect-linguex-list))
 696 "
 697   :group 'reftex-defining-label-environments
 698   :type 'hook)
 699
 700 ;; Label insertion
 701
 702 (defgroup reftex-making-and-inserting-labels nil
 703   "Options on how to create new labels."
 704   :group 'reftex-label-support)
 705
 706 (defcustom reftex-insert-label-flags '("s" "sft")
 707   "Flags governing label insertion.  First flag DERIVE, second flag PROMPT.
 708
 709 If DERIVE is t, RefTeX will try to derive a sensible label from context.
 710 A section label for example will be derived from the section heading.
 711 The conversion of the context to a legal label is governed by the
 712 specifications given in `reftex-derive-label-parameters'.
 713 If RefTeX fails to derive a label, it will prompt the user.
 714 If DERIVE is nil, the label generated will consist of the prefix and a
 715 unique number, like `eq:23'.
 716
 717 If PROMPT is t, the user will be prompted for a label string.  The prompt will
 718 already contain the prefix, and (if DERIVE is t) a default label derived from
 719 context.  When PROMPT is nil, the default label will be inserted without
 720 query.
 721
 722 So the combination of DERIVE and PROMPT controls label insertion.  Here is a
 723 table describing all four possibilities:
 724
 725 DERIVE   PROMPT      ACTION
 726 -------------------------------------------------------------------------
 727  nil     nil     Insert simple label, like eq:22 or sec:13.  No query.
 728  nil     t       Prompt for label.
 729  t       nil     Derive a label from context and insert without query.
 730  t       t       Derive a label from context and prompt for confirmation.
 731
 732 Each flag may be set to t, nil, or a string of label type letters
 733 indicating the label types for which it should be true.  The strings work
 734 like character classes.
 735 Thus, the combination may be set differently for each label type.  The
 736 default settings \"s\" and \"sft\" mean: Derive section labels from headings
 737 \(with confirmation).  Prompt for figure and table labels.  Use simple labels
 738 without confirmation for everything else.
 739 The available label types are: s (section), f (figure), t (table), i (item),
 740 e (equation), n (footnote), N (endnote), plus any definitions in
 741 `reftex-label-alist'."
 742   :group 'reftex-making-and-inserting-labels
 743   :type  '(list (choice :tag "Derive label from context"
 744                          (const  :tag "always" t)
 745                          (const  :tag "never" nil)
 746                          (string :tag "selected label types" ""))
 747                 (choice :tag "Prompt for label string  "
 748                         :entry-format "  %b %v"
 749                         (const  :tag "always" t)
 750                         (const  :tag "never" nil)
 751                         (string :tag "selected label types" ""))))
 752
 753 (defcustom reftex-string-to-label-function 'reftex-string-to-label
 754   "Function to turn an arbitrary string into a legal label.
 755 RefTeX's default function uses the variable `reftex-derive-label-parameters'."
 756   :group 'reftex-making-and-inserting-labels
 757   :type 'symbol)
 758
 759 (defcustom reftex-translate-to-ascii-function 'reftex-latin1-to-ascii
 760   "Filter function which will process a context string before it is used
 761 to derive a label from it.  The intended application is to convert ISO or
 762 Mule characters into something legal in labels.  The default function
 763 removes the accents from Latin-1 characters.  X-Symbol (>=2.6) sets this
 764 variable to the much more general `x-symbol-translate-to-ascii'."
 765   :group 'reftex-making-and-inserting-labels
 766   :type 'symbol)
 767
 768 (defcustom reftex-derive-label-parameters '(3 20 t 1 "-"
 769          ("the" "on" "in" "off" "a" "for" "by" "of" "and" "is" "to") t)
 770   "Parameters for converting a string into a label.
 771 This variable is a list of the following items.
 772
 773 NWORDS      Number of words to use.
 774 MAXCHAR     Maximum number of characters in a label string.
 775 ILLEGAL     nil: Throw away any words containing characters illegal in labels.
 776             t:   Throw away only the illegal characters, not the whole word.
 777 ABBREV      nil: Never abbreviate words.
 778             t:   Always abbreviate words (see `reftex-abbrev-parameters').
 779             not t and not nil: Abbreviate words if necessary to shorten
 780                                label string below MAXCHAR.
 781 SEPARATOR   String separating different words in the label.
 782 IGNOREWORDS List of words which should not be part of labels.
 783 DOWNCASE    t:   Downcase words before using them."
 784   :group 'reftex-making-and-inserting-labels
 785   :type  '(list (integer :tag "Number of words            "  3)
 786                 (integer :tag "Maximum label length       " 20)
 787                 (choice  :tag "Illegal characters in words"
 788                          (const :tag "throw away entire word" nil)
 789                          (const :tag "throw away single chars" t))
 790                 (choice  :tag "Abbreviate words           "
 791                          (const :tag "never" nil)
 792                          (const :tag "always" t)
 793                          (const :tag "when label is too long" 1))
 794                 (string  :tag "Separator between words    " "-")
 795                 (repeat  :tag "Ignore words"
 796                          :entry-format "           %i %d %v"
 797                          (string :tag ""))
 798                 (option (boolean :tag "Downcase words          "))))
 799
 800 (defcustom reftex-label-illegal-re "[^-a-zA-Z0-9_+=:;,.]"
 801   "Regexp matching characters not legal in labels."
 802   :group 'reftex-making-and-inserting-labels
 803   :type '(regexp :tag "Regular Expression"))
 804
 805 (defcustom reftex-abbrev-parameters '(4 2 "^aeiou" "aeiou")
 806   "Parameters for abbreviation of words.
 807 This variable is a list of the following items.
 808
 809 MIN-CHARS    Minimum number of characters remaining after abbreviation.
 810 MIN-KILL     Minimum number of characters to remove when abbreviating words.
 811 BEFORE       Character class before abbrev point in word.
 812 AFTER        Character class after  abbrev point in word."
 813   :group 'reftex-making-and-inserting-labels
 814   :type '(list
 815           (integer :tag "Minimum chars per word" 4)
 816           (integer :tag "Shorten by at least   " 2)
 817           (string  :tag "cut before char class " "^saeiou")
 818           (string  :tag "cut after  char class " "aeiou")))
 819
 820 (defcustom reftex-format-label-function nil
 821   "Function which produces the string to insert as a label definition.
 822 Normally should be nil, unless you want to do something fancy.
 823 The function will be called with two arguments, the LABEL and the DEFAULT
 824 FORMAT, which usually is `\\label{%s}'.  The function should return the
 825 string to insert into the buffer."
 826   :group 'reftex-making-and-inserting-labels
 827   :type 'function)
 828
 829 ;; Label referencing
 830
 831 (defgroup reftex-referencing-labels nil
 832   "Options on how to reference labels."
 833   :group 'reftex-label-support)
 834
 835 (eval-and-compile
 836   (defconst reftex-tmp
 837     '((const :tag "on" t)
 838       (const :tag "off" nil)
 839       (string :tag "Selected label types"))))
 840
 841 (defcustom reftex-label-menu-flags '(t t nil nil nil nil t nil)
 842   "List of flags governing the label menu makeup.
 843 The flags are:
 844
 845 TABLE-OF-CONTENTS  Show the labels embedded in a table of context.
 846 SECTION-NUMBERS    Include section numbers (like 4.1.3) in table of contents.
 847 COUNTERS           Show counters.  This just numbers the labels in the menu.
 848 NO-CONTEXT         Non-nil means do NOT show the short context.
 849 FOLLOW             Follow full context in other window.
 850 SHOW-COMMENTED     Show labels from regions which are commented out.
 851 MATCH-IN-TOC       Obsolete flag.
 852 SHOW FILES         Show begin and end of included files.
 853
 854 Each of these flags can be set to t or nil, or to a string of type letters
 855 indicating the label types for which it should be true.  These strings work
 856 like character classes in regular expressions.  Thus, setting one of the
 857 flags to \"sf\" makes the flag true for section and figure labels, nil
 858 for everything else.  Setting it to \"^sf\" makes it the other way round.
 859 The available label types are: s (section), f (figure), t (table), i (item),
 860 e (equation), n (footnote), plus any definitions in `reftex-label-alist'.
 861
 862 Most options can also be switched from the label menu itself - so if you
 863 decide here to not have a table of contents in the label menu, you can still
 864 get one interactively during selection from the label menu."
 865   :group 'reftex-referencing-labels
 866   :type
 867   `(list
 868     (choice :tag "Embed in table of contents      " ,@reftex-tmp)
 869     (choice :tag "Show section numbers            " ,@reftex-tmp)
 870     (choice :tag "Show individual counters        " ,@reftex-tmp)
 871     (choice :tag "Hide short context              " ,@reftex-tmp)
 872     (choice :tag "Follow context in other window  " ,@reftex-tmp)
 873     (choice :tag "Show commented labels           " ,@reftex-tmp)
 874     (choice :tag "Obsolete flag,  Don't use.      " ,@reftex-tmp)
 875     (choice :tag "Show begin/end of included files" ,@reftex-tmp)))
 876
 877 (defcustom reftex-multiref-punctuation '((?, . ", ") (?- . "--") (?+ . " and "))
 878   "Punctuation strings for multiple references.
 879 When marking is used in the selection buffer to select several references,
 880 this variable associates the 3 marking characters `,-+' with prefix strings
 881 to be inserted into the buffer before the corresponding \\ref macro.
 882 This is used to string together whole reference sets, like
 883 `eqs. 1,2,3-5,6 and 7' in a single call to `reftex-reference'. See manual."
 884   :group 'reftex-referencing-labels
 885   :type '(repeat (cons (character) (string))))
 886
 887 (defcustom reftex-vref-is-default nil
 888   "*Non-nil means, the varioref macro \\vref is used as default.
 889 In the selection buffer, the `v' key toggles the reference macro between
 890 `\\ref' and `\\vref'.  The value of this variable determines the default
 891 which is active when entering the selection process.
 892 Instead of nil or t, this may also be a string of type letters indicating
 893 the label types for which it should be true."
 894   :group  'reftex-referencing-labels
 895   :type `(choice :tag "\\vref is default macro" ,@reftex-tmp))
 896
 897 (defcustom reftex-fref-is-default nil
 898   "*Non-nil means, the fancyref macro \\fref is used as default.
 899 In the selection buffer, the `V' key toggles the reference macro between
 900 `\\ref', `\\fref' and `\\Fref'.  The value of this variable determines
 901 the default which is active when entering the selection process.
 902 Instead of nil or t, this may also be a string of type letters indicating
 903 the label types for which it should be true."
 904   :group  'reftex-referencing-labels
 905   :type `(choice :tag "\\fref is default macro" ,@reftex-tmp))
 906
 907 (defcustom reftex-level-indent 2
 908   "*Number of spaces to be used for indentation per section level."
 909   :group 'reftex-referencing-labels
 910   :type 'integer)
 911
 912 (defcustom reftex-guess-label-type t
 913   "*Non-nil means, `reftex-reference' will try to guess the label type.
 914 To do that, RefTeX will look at the word before the cursor and compare it with
 915 the words given in `reftex-label-alist'.  When it finds a match, RefTeX will
 916 immediately offer the correct label menu - otherwise it will prompt you for
 917 a label type.  If you set this variable to nil, RefTeX will always prompt."
 918   :group 'reftex-referencing-labels
 919   :type 'boolean)
 920
 921 (defcustom reftex-format-ref-function nil
 922   "Function which produces the string to insert as a reference.
 923 Normally should be nil, because the format to insert a reference can
 924 already be specified in `reftex-label-alist'.
 925 This hook also is used by the special commands to insert `\\vref' and `\\fref'
 926 references, so even if you set this, your setting will be ignored by
 927 the special commands.
 928 The function will be called with two arguments, the LABEL and the DEFAULT
 929 FORMAT, which normally is `~\\ref{%s}'.  The function should return the
 930 string to insert into the buffer."
 931   :group 'reftex-referencing-labels
 932   :type 'function)
 933
 934 (defcustom reftex-select-label-mode-hook nil
 935   "Mode hook for reftex-select-label-mode."
 936   :group 'reftex-referencing-labels
 937   :type 'hook)
 938
 939 ;; BibteX citation configuration ----------------------------------------
 940
 941 (defgroup reftex-citation-support nil
 942   "Support for referencing bibliographic data with BibTeX."
 943   :group 'reftex)
 944
 945 (defcustom reftex-bibliography-commands '("bibliography" "nobibliography")
 946   "LaTeX commands which specify the BibTeX databases to use with the document."
 947   :group 'reftex-citation-support
 948   :type '(repeat string))
 949
 950
 951 (defvar reftex-bibfile-ignore-list nil) ; compatibility
 952 (defcustom reftex-bibfile-ignore-regexps nil
 953   "*List of regular expressions to exclude files in \\bibliography{..}.
 954 File names matched by these regexps will not be parsed by RefTeX.
 955 Intended for files which contain only `@string' macro definitions and the
 956 like, which are ignored by RefTeX anyway."
 957   :group 'reftex-citation-support
 958   :set 'reftex-set-dirty
 959   :type '(repeat (regexp)))
 960
 961 (defcustom reftex-default-bibliography nil
 962   "*List of BibTeX database files which should be used if none are specified.
 963 When `reftex-citation' is called from a document which has neither a
 964 `\\bibliography{..}' statement nor a `thebibliography' environment,
 965 RefTeX will scan these files instead.  Intended for using `reftex-citation'
 966 in non-LaTeX files.  The files will be searched along the BIBINPUTS or TEXBIB
 967 path."
 968   :group 'reftex-citation-support
 969   :type '(repeat (file)))
 970
 971 (defcustom reftex-sort-bibtex-matches 'reverse-year
 972   "*Sorting of the entries found in BibTeX databases by reftex-citation.
 973 Possible values:
 974 nil            Do not sort entries.
 975 'author        Sort entries by author name.
 976 'year          Sort entries by increasing year.
 977 'reverse-year  Sort entries by decreasing year."
 978   :group 'reftex-citation-support
 979   :type '(choice (const :tag "not" nil)
 980                  (const :tag "by author" author)
 981                  (const :tag "by year"   year)
 982                  (const :tag "by year, reversed" reverse-year)))
 983
 984 (defcustom reftex-cite-format 'default
 985   "*The format of citations to be inserted into the buffer.
 986 It can be a string or an alist or a symbol.  In the simplest case this
 987 is just the string \"\\cite{%l}\", which is also the default.  See the
 988 definition of `reftex-cite-format-builtin' for more complex examples.
 989
 990 If `reftex-cite-format' is a string, it will be used as the format.
 991 In the format, the following percent escapes will be expanded.
 992
 993 %l   The BibTeX label of the citation.
 994 %a   List of author names, see also `reftex-cite-punctuation'.
 995 %2a  Like %a, but abbreviate more than 2 authors like Jones et al.
 996 %A   First author name only.
 997 %e   Works like %a, but on list of editor names. (%2e and %E work a well)
 998
 999 It is also possible to access all other BibTeX database fields:
1000 %b booktitle     %c chapter        %d edition    %h howpublished
1001 %i institution   %j journal        %k key        %m month
1002 %n number        %o organization   %p pages      %P first page
1003 %r address       %s school         %u publisher  %t title
1004 %v volume        %y year
1005 %B booktitle, abbreviated          %T title, abbreviated
1006
1007 Usually, only %l is needed.  The other stuff is mainly for the echo area
1008 display, and for (setq reftex-comment-citations t).
1009
1010 %< as a special operator kills punctuation and space around it after the
1011 string has been formatted.
1012
1013 Beware that all this only works with BibTeX database files.  When
1014 citations are made from the \\bibitems in an explicit thebibliography
1015 environment, only %l is available.
1016
1017 If `reftex-cite-format' is an alist of characters and strings, the user
1018 will be prompted for a character to select one of the possible format
1019 strings.
1020   In order to configure this variable, you can either set
1021 `reftex-cite-format' directly yourself or set it to the SYMBOL of one of
1022 the predefined styles.  The predefined symbols are those which have an
1023 association in the constant `reftex-cite-format-builtin'.
1024 E.g.: (setq reftex-cite-format 'natbib)"
1025   :group 'reftex-citation-support
1026   :type
1027   `(choice
1028     :format "%{%t%}: \n%[Value Menu%] %v"
1029     (radio :tag "Symbolic Builtins"
1030            :indent 4
1031            :value default
1032            ,@(mapcar
1033               (lambda (x)
1034                 (list 'const :tag (concat (symbol-name (nth 0 x))
1035                                            ": " (nth 1 x))
1036                       (nth 0 x)))
1037               reftex-cite-format-builtin))
1038     (string :tag "format string" "\\cite{%l}")
1039     (repeat :tag "key-ed format strings"
1040             :value ((?\r . "\\cite{%l}")
1041                     (?t  . "\\cite{%l}") (?p . "\\cite{%l}"))
1042             (cons (character :tag "Key character" ?\r)
1043                   (string    :tag "Format string" "")))))
1044
1045 (defcustom reftex-comment-citations nil
1046   "*Non-nil means add a comment for each citation describing the full entry.
1047 The comment is formatted according to `reftex-cite-comment-format'."
1048   :group 'reftex-citation-support
1049   :type 'boolean)
1050
1051 (defcustom reftex-cite-comment-format
1052   "%% %2a %y, %j %v, %P, %b, %e, %u, %s %<\n"
1053   "Citation format used for commented citations.  Must NOT contain %l.
1054 See the variable `reftex-cite-format' for possible percent escapes."
1055   :group 'reftex-citation-support
1056   :type 'string)
1057
1058 (defcustom reftex-cite-view-format "%2a %y, %T, %B, %j %v:%P, %s %<"
1059   "Citation format used to display citation info in the message area.
1060 Must NOT contain %l.  See the variable `reftex-cite-format' for
1061 possible percent escapes."
1062   :group 'reftex-citation-support
1063   :group 'reftex-viewing-cross-references
1064   :type 'string)
1065
1066 (defcustom reftex-cite-punctuation '(", " " \\& " " {\\it et al.}")
1067   "Punctuation for formatting of name lists in citations.
1068 This is a list of 3 strings.
1069 1. normal names separator, like \", \"     in Jones, Brown and Miller
1070 2. final names separator,  like \" and \"  in Jones, Brown and Miller
1071 3. The \"et al\" string,   like \" {\\it et al.}\" in Jones {\\it et al.}"
1072   :group 'reftex-citation-support
1073   :type '(list
1074           (string :tag "Separator for names            ")
1075           (string :tag "Separator for last name in list")
1076           (string :tag "string used as et al.          ")))
1077
1078 (defcustom reftex-format-cite-function nil
1079   "Function which produces the string to insert as a citation.
1080 Normally should be nil, because the format to insert a reference can
1081 already be specified in `reftex-cite-format'.
1082 The function will be called with two arguments, the CITATION KEY and the
1083 DEFAULT FORMAT, which is taken from `reftex-cite-format'.  The function
1084 should return the string to insert into the buffer."
1085   :group 'reftex-citation-support
1086   :type 'function)
1087
1088 (defcustom reftex-select-bib-mode-hook nil
1089   "Mode hook for reftex-select-bib-mode."
1090   :group 'reftex-citation-support
1091   :type 'hook)
1092
1093 ;; Index Support Configuration
1094
1095 (defgroup reftex-index-support nil
1096   "Support for viewing and editing the index."
1097   :group 'reftex)
1098
1099 (defcustom reftex-support-index t
1100   "*Non-nil means, index entries are parsed as well.
1101 Index support is resource intensive and the internal structure holding the
1102 parsed information can become quite big.  Therefore it can be turned off.
1103 When this is nil and you execute a command which requires index support,
1104 you will be asked for confirmation to turn it on and rescan the document."
1105   :group 'reftex-index-support
1106   :type 'boolean)
1107
1108 (defcustom reftex-index-special-chars '("!" "|" "@" "\"" "\\")
1109   "Special characters in index entries.  The value is a list of five strings.
1110 These correspond to the makeindex keywords LEVEL ENCAP ACTUAL QUOTE ESCAPE."
1111   :group 'reftex-index-support
1112   :type '(list
1113           (string :tag "LEVEL  separator")
1114           (string :tag "ENCAP  char     ")
1115           (string :tag "ACTUAL char     ")
1116           (string :tag "QUOTE  char     ")
1117           (string :tag "ESCAPE char     ")))
1118
1119 (defcustom reftex-index-macros nil
1120   "Macros which define index entries.  The structure is
1121
1122 \(MACRO INDEX-TAG KEY PREFIX EXCLUDE REPEAT)
1123
1124 MACRO is the macro.  Arguments should be denoted by empty braces like
1125 \\index[]{*}.  Use square brackets to denote optional arguments.  The star
1126 marks where the index key is.
1127
1128 INDEX-TAG is a short name of the index.  \"idx\" and \"glo\" are
1129 reserved for the default index and the glossary.  Other indices can be
1130 defined as well.  If this is an integer, the Nth argument of the macro
1131 holds the index tag.
1132
1133 KEY is a character which is used to identify the macro for input with
1134 \\[reftex-index].  ?i, ?I, and ?g are reserved for default index and glossary.
1135
1136 PREFIX can be a prefix which is added to the KEY part of the index entry.
1137 If you have a macro \\newcommand{\\molec}[1]{#1\\index{Molecules!#1}}, this
1138 prefix should be \"Molecules!\".  See the manual for details.
1139
1140 EXCLUDE can be a function.  If this function exists and returns a non-nil
1141 value, the index entry at point is ignored.  This was implemented to support
1142 the (deprecated) `^' and `_' shortcuts in the LaTeX2e `index' package.
1143
1144 REPEAT, if non-nil, means the index macro does not typeset the entry in
1145 the text, so that the text has to be repeated outside the index macro.
1146 Needed for `reftex-index-selection-or-word' and for indexing from the
1147 phrase buffer.
1148
1149 The final entry may also be a symbol if this entry has a association
1150 in the variable `reftex-index-macros-builtin' to specify the main
1151 indexing package you are using.  Legal values are currently
1152 default         The LaTeX default - unnecessary to specify this one
1153 multind         The multind.sty package
1154 index           The index.sty package
1155 index-shortcut  The index.sty packages with the ^ and _ shortcuts.
1156                 Should not be used - only for old documents.
1157 Note that AUCTeX sets these things internally for RefTeX as well, so
1158 with a sufficiently new version of AUCTeX, you should not set the
1159 package here."
1160   :group 'reftex-index-support
1161   :set 'reftex-set-dirty
1162   :type `(list
1163           (repeat
1164            :inline t
1165            (list :value ("" "idx" ?a "" nil)
1166                  (string  :tag "Macro with args")
1167                  (choice  :tag "Index Tag      "
1168                          (string)
1169                          (integer :tag "Macro arg Nr" :value 1))
1170                  (character :tag "Access Key     ")
1171                  (string  :tag "Key Prefix     ")
1172                  (symbol  :tag "Exclusion hook ")
1173                  (boolean :tag "Repeat Outside ")))
1174           (option
1175            :tag "Package:"
1176            (choice :tag "Package"
1177                    :value index
1178                    ,@(mapcar
1179                       (lambda (x)
1180                         (list 'const :tag (concat (symbol-name (nth 0 x))
1181                                                   ": " (nth 1 x))
1182                               (nth 0 x)))
1183                       reftex-index-macros-builtin)))))
1184
1185 (defcustom reftex-index-default-macro '(?i "idx")
1186   "The default index macro for \\[reftex-index-selection-or-word].
1187 This is a list with (MACRO-KEY DEFAULT-TAG).
1188
1189 MACRO-KEY:   Character identifying an index macro - see `reftex-index-macros'.
1190 DEFAULT-TAG: This is the tag to be used if the macro requires a TAG argument.
1191              When this is nil and a TAG is needed, RefTeX will ask for it.
1192              When this is the empty string and the TAG argument of the index
1193              macro is optional, the TAG argument will be omitted."
1194   :group 'reftex-index-support
1195   :type '(list
1196           (character :tag "Character identifying default macro")
1197           (choice    :tag "Default index tag                  "
1198                   (const nil)
1199                   (string))))
1200
1201 (defcustom reftex-index-default-tag "idx"
1202   "Default index tag.
1203 When working with multiple indexes, RefTeX queries for an index tag when
1204 creating index entries or displaying a specific index.  This variable controls
1205 the default offered for these queries.  The default can be selected with RET
1206 during selection or completion.  Legal values of this variable are:
1207
1208 nil       Do not provide a default index
1209 \"tag\"     The default index tag given as a string, e.g. \"idx\".
1210 last      The last used index tag will be offered as default."
1211   :group 'reftex-index-support
1212   :type '(choice
1213           (const :tag  "no default" nil)
1214           (const :tag  "last used " 'last)
1215           (string :tag "index tag " "idx")))
1216
1217 (defcustom reftex-index-math-format "$%s$"
1218   "Format of index entries when copied from inside math mode.
1219 When `reftex-index-selection-or-word' is executed inside TeX math mode,
1220 the index key copied from the buffer is processed with this format string
1221 through the `format' function.  This can be used to add the math delimiters
1222 \(e.g. `$') to the string.
1223 Requires the `texmathp.el' library which is part of AUCTeX."
1224   :group 'reftex-index-support
1225   :type 'string)
1226
1227 (defcustom reftex-index-phrase-file-extension ".rip"
1228   "File extension for the index phrase file.
1229 This extension will be added to the base name of the master file."
1230   :group 'reftex-index-support
1231   :type 'string)
1232
1233 (defcustom reftex-index-phrases-logical-and-regexp " *&& *"
1234   "Regexp matching the `and' operator for index arguments in phrases file.
1235 When several index arguments in a phrase line are separated by this
1236 operator, each part will generate an index macro.  So each match of
1237 the search phrase will produce *several* different index entries.
1238
1239 Note: make sure this does no match things which are not separators.
1240 This logical `and' has higher priority than the logical `or' specified in
1241 `reftex-index-phrases-logical-or-regexp'."
1242   :group 'reftex-index-support
1243   :type 'regexp)
1244
1245 (defcustom reftex-index-phrases-logical-or-regexp " *|| *"
1246   "Regexp matching the `or' operator for index arguments in phrases file.
1247 When several index arguments in a phrase line are separated by this
1248 operator, the user will be asked to select one of them at each match
1249 of the search phrase.  The first index arg will be the default - a
1250 number key 1-9 must be pressed to switch to another.
1251
1252 Note: make sure this does no match things which are not separators.
1253 The logical `and' specified in `reftex-index-phrases-logical-or-regexp'
1254 has higher priority than this logical `or'."
1255   :group 'reftex-index-support
1256   :type 'regexp)
1257
1258 (defcustom reftex-index-phrases-search-whole-words t
1259   "*Non-nil means phrases search will look for whole words, not subwords.
1260 This works by requiring word boundaries at the beginning and end of
1261 the search string.  When the search phrase already has a non-word-char
1262 at one of these points, no word boundary is required there."
1263   :group 'reftex-index-support
1264   :type 'boolean)
1265
1266 (defcustom reftex-index-phrases-case-fold-search t
1267   "*Non-nil means, searching for index phrases will ignore case."
1268   :group 'reftex-index-support
1269   :type 'boolean)
1270
1271 (defcustom reftex-index-verify-function nil
1272   "A function which is called  at each match during global indexing.
1273 If the function returns nil, the current match is skipped."
1274   :group 'reftex-index-support
1275   :type '(choice
1276           (const :tag "No verification" nil)
1277           (function)))
1278
1279 (defcustom reftex-index-phrases-skip-indexed-matches nil
1280   "*Non-nil means, skip matches which appear to be indexed already.
1281 When doing global indexing from the phrases buffer, searches for some
1282 phrases may match at places where that phrase was already indexed.  In
1283 particular when indexing an already processed document again, this
1284 will even be the norm.  When this variable is non-nil, RefTeX checks if
1285 the match is inside an index macro argument, or if an index macro is directly
1286 before or after the phrase.  If that is the case, that match will
1287 be ignored."
1288   :group 'reftex-index-support
1289   :type 'boolean)
1290
1291 (defcustom reftex-index-phrases-wrap-long-lines nil
1292   "*Non-nil means, when indexing from the phrases buffer, wrap lines.
1293 Inserting indexing commands in a line makes the line longer - often
1294 so long that it does not fit onto the screen.  When this variable is
1295 non-nil, newlines will be added as necessary before and/or after the
1296 indexing command to keep lines short.  However, the matched text
1297 phrase and its index command will always end up on a single line.")
1298
1299 (defcustom reftex-index-phrases-sort-prefers-entry nil
1300   "*Non-nil means when sorting phrase lines, the explicit index entry is used.
1301 Phrase lines in the phrases buffer contain a search phrase, and
1302 sorting is normally based on these.  Some phrase lines also have
1303 an explicit index argument specified.  When this variable is non-nil,
1304 the index argument will be used for sorting."
1305   :group 'reftex-index-support
1306   :type 'boolean)
1307
1308 (defcustom reftex-index-phrases-sort-in-blocks t
1309   "*Non-nil means, empty and comment lines separate phrase buffer into blocks.
1310 Sorting will then preserve blocks, so that lines are re-arranged only
1311 within blocks."
1312   :group 'reftex-index-support
1313   :type 'boolean)
1314
1315 (defcustom reftex-index-section-letters "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
1316   "The letters which denote sections in the index.
1317 Usually these are all capital letters.  Don't use any downcase letters.
1318 Order is not significant, the index will be sorted by whatever the sort
1319 function thinks is correct.
1320 In addition to these letters, RefTeX will create a group `!' which
1321 contains all entries sorted below the lowest specified letter.
1322 In the index buffer, pressing any of these capital letters or `!' will jump
1323 to that section."
1324   :group 'reftex-index-support
1325   :type '(string :tag "Capital letters"))
1326
1327 (defcustom reftex-index-include-context nil
1328   "*Non-nil means, display the index definition context in the index buffer.
1329 This flag may also be toggled from the index buffer with the `c' key."
1330   :group 'reftex-index-support
1331   :type 'boolean)
1332
1333 (defcustom reftex-index-follow-mode nil
1334   "*Non-nil means, point in *Index* buffer will cause other window to follow.
1335 The other window will show the corresponding part of the document.
1336 This flag can be toggled from within the *Index* buffer with the `f' key."
1337   :group 'reftex-table-of-contents-browser
1338   :type 'boolean)
1339
1340 ;; Viewing Cross References
1341
1342 (defgroup reftex-viewing-cross-references nil
1343   "Displaying cross references and citations."
1344   :group 'reftex)
1345
1346 (defcustom reftex-view-crossref-extra nil
1347   "Macros which can be used for the display of cross references.
1348 This is used when `reftex-view-crossref' is called with point in an
1349 argument of a macro.  Note that crossref viewing for citations,
1350 references (both ways) and index entries is hard-coded.  This variable
1351 is only to configure additional structures for which crossreference
1352 viewing can be useful.  Each entry has the structure
1353
1354 \(MACRO-RE SEARCH-RE HIGHLIGHT).
1355
1356 MACRO-RE is matched against the macro.  SEARCH-RE is the regexp used
1357 to search for cross references.  `%s' in this regexp is replaced with
1358 with the macro argument at point.  HIGHLIGHT is an integer indicating
1359 which subgroup of the match should be highlighted."
1360   :group 'reftex-viewing-cross-references
1361   :type '(repeat (group (regexp  :tag "Macro  Regexp  ")
1362                         (string  :tag "Search Regexp  ")
1363                         (integer :tag "Highlight Group"))))
1364
1365 (defcustom reftex-auto-view-crossref t
1366   "*Non-nil means, initially turn automatic viewing of crossref info on.
1367 Automatic viewing of crossref info normally uses the echo area.
1368 Whenever point is idle for more than `reftex-idle-time' seconds on the
1369 argument of a \\ref or \\cite macro, and no other message is being
1370 displayed, the echo area will display information about that cross
1371 reference.  You can also set the variable to the symbol `window'.  In
1372 this case a small temporary window is used for the display.
1373 This feature can be turned on and off from the menu
1374 \(Ref->Options)."
1375   :group 'reftex-viewing-cross-references
1376   :type '(choice (const :tag "off" nil)
1377                  (const :tag "in Echo Area" t)
1378                  (const :tag "in Other Window" window)))
1379
1380 (defcustom reftex-idle-time 1.2
1381   "*Time (secs) Emacs has to be idle before automatic crossref display is done.
1382 Applies also to toc recentering."
1383   :group 'reftex-viewing-cross-references
1384   :type 'number)
1385
1386 (defcustom reftex-revisit-to-echo nil
1387   "*Non-nil means, automatic citation display will revisit files if necessary.
1388 When nil, citation display in echo area will only be active for cached
1389 entries and for BibTeX database files with live associated buffers."
1390   :group 'reftex-viewing-cross-references
1391   :type 'boolean)
1392
1393 (defcustom reftex-cache-cite-echo t
1394   "*Non-nil means, the information displayed in the echo area for cite macros
1395 is cached and even saved along with the parsing information.  The cache
1396 survives document scans.  In order to clear it, use M-x reftex-reset-mode."
1397   :group 'reftex-viewing-cross-references
1398   :type 'boolean)
1399
1400 (defcustom reftex-display-copied-context-hook nil
1401   "Normal Hook which is run before context is displayed anywhere.  Designed
1402 for X-Symbol, but may have other uses as well."
1403   :group 'reftex-viewing-cross-references
1404   :group 'reftex-referencing-labels
1405   :type 'hook)
1406
1407 ;; Finding Files --------------------------------------------------------
1408
1409 (defgroup reftex-finding-files nil
1410   "Finding files on search paths."
1411   :group 'reftex)
1412
1413 (defcustom reftex-texpath-environment-variables '("TEXINPUTS")
1414   "*List of specifications how to retrieve the search path for TeX files.
1415 Several entries are possible.
1416 - If an element is the name of an environment variable, its content is used.
1417 - If an element starts with an exclamation mark, it is used as a command
1418   to retrieve the path.  A typical command with the kpathsearch library would
1419   be `!kpsewhich -show-path=.tex'.
1420 - Otherwise the element itself is interpreted as a path.
1421 Multiple directories can be separated by the system dependent `path-separator'.
1422 Directories ending in `//' or `!!' will be expanded recursively.
1423 See also `reftex-use-external-file-finders'."
1424   :group 'reftex-finding-files
1425   :set 'reftex-set-dirty
1426   :type '(repeat (string :tag "Specification")))
1427
1428 (defcustom reftex-bibpath-environment-variables '("BIBINPUTS" "TEXBIB")
1429   "*List of specifications how to retrieve search path for .bib database files.
1430 Several entries are possible.
1431 - If an element is the name of an environment variable, its content is used.
1432 - If an element starts with an exclamation mark, it is used as a command
1433   to retrieve the path.  A typical command with the kpathsearch library would
1434   be `!kpsewhich -show-path=.bib'.
1435 - Otherwise the element itself is interpreted as a path.
1436 Multiple directories can be separated by the system dependent `path-separator'.
1437 Directories ending in `//' or `!!' will be expanded recursively.
1438 See also `reftex-use-external-file-finders'."
1439   :group 'reftex-citation-support
1440   :group 'reftex-finding-files
1441   :set 'reftex-set-dirty
1442   :type '(repeat (string :tag "Specification")))
1443
1444 (defcustom reftex-file-extensions '(("tex" . (".tex" ".ltx"))
1445                                     ("bib" . (".bib")))
1446   "*Association list with file extensions for different file types.
1447 This is a list of items, each item is like: (TYPE . (DEF-EXT OTHER-EXT ...))
1448
1449 TYPE:       File type like \"bib\" or \"tex\".
1450 DEF-EXT:    The default extension for that file type, like \".tex\" or \".bib\".
1451 OTHER-EXT:  Any number of other legal extensions for this file type.
1452
1453 When a files is searched and it does not have any of the legal extensions,
1454 we try the default extension first, and then the naked file name.
1455
1456 If you are using AUCTeX, you also need to add new extensions to
1457 TeX-file-extensions."
1458   :group 'reftex-finding-files
1459   :type '(repeat (cons (string :tag "File type")
1460                        (repeat (string :tag "Extension")))))
1461
1462 (defcustom reftex-search-unrecursed-path-first t
1463   "*Non-nil means, search all specified directories before trying recursion.
1464 Thus, in a path \".//:/tex/\", search first \"./\", then \"/tex/\" and then
1465 all subdirectories of \"./\".  If this option is nil, the subdirectories of
1466 \"./\" are searched before \"/tex/\". This is mainly for speed - most of the
1467 time the recursive path is for the system files and not for the user files.
1468 Set this to nil if the default makes RefTeX finding files with equal names
1469 in wrong sequence."
1470   :group 'reftex-finding-files
1471   :type 'boolean)
1472
1473 (defcustom reftex-use-external-file-finders nil
1474   "*Non-nil means, use external programs to find files.
1475 Normally, RefTeX searches the paths given in the environment variables
1476 TEXINPUTS and BIBINPUTS to find TeX files and BibTeX database files.
1477 With this option turned on, it calls an external program specified in the
1478 option `reftex-external-file-finders' instead.  As a side effect,
1479 the variables `reftex-texpath-environment-variables' and
1480 `reftex-bibpath-environment-variables' will be ignored."
1481   :group 'reftex-finding-files
1482   :type 'boolean)
1483
1484 (defcustom reftex-external-file-finders '(("tex" . "kpsewhich -format=.tex %f")
1485                                           ("bib" . "kpsewhich -format=.bib %f"))
1486   "*Association list with external programs to call for finding files.
1487 Each entry is a cons cell (TYPE . PROGRAM).
1488 TYPE is either \"tex\" or \"bib\".  PROGRAM is the external program to use with
1489 any arguments.  %f will be replaced by the name of the file to be found.
1490 Note that these commands will be executed directly, not via a shell.
1491 Only relevant when `reftex-use-external-file-finders' is non-nil."
1492   :group 'reftex-finding-files
1493   :type '(repeat (cons (string :tag "File type")
1494                        (string :tag "Program  "))))
1495
1496 ;; Tuning the parser ----------------------------------------------------
1497
1498 (defgroup reftex-optimizations-for-large-documents nil
1499   "Configuration of parser speed and memory usage."
1500   :group 'reftex)
1501
1502 (defcustom reftex-keep-temporary-buffers 1
1503   "*Non-nil means, keep buffers created for parsing and lookup.
1504 RefTeX sometimes needs to visit files related to the current document.
1505 We distinguish files visited for
1506 PARSING: Parts of a multifile document loaded when (re)-parsing the document.
1507 LOOKUP:  BibTeX database files and TeX files loaded to find a reference,
1508          to display label context, etc.
1509 The created buffers can be kept for later use, or be thrown away immediately
1510 after use, depending on the value of this variable:
1511
1512 nil  Throw away as much as possible.
1513 t    Keep everything.
1514 1    Throw away buffers created for parsing, but keep the ones created
1515      for lookup.
1516
1517 If a buffer is to be kept, the file is visited normally (which is potentially
1518 slow but will happen only once).
1519 If a buffer is to be thrown away, the initialization of the buffer depends
1520 upon the variable `reftex-initialize-temporary-buffers'."
1521   :group 'reftex-optimizations-for-large-documents
1522   :type '(choice
1523           (const :tag "Throw away everything" nil)
1524           (const :tag "Keep everything" t)
1525           (const :tag "Keep lookup buffers only" 1)))
1526
1527 (defcustom reftex-initialize-temporary-buffers nil
1528   "*Non-nil means do initializations even when visiting file temporarily.
1529 When nil, RefTeX may turn off find-file hooks and other stuff to briefly
1530 visit a file.
1531 When t, the full default initializations are done (find-file-hook etc.).
1532 Instead of t or nil, this variable may also be a list of hook functions to
1533 do a minimal initialization."
1534   :group 'reftex-optimizations-for-large-documents
1535   :type '(choice
1536           (const :tag "Read files literally" nil)
1537           (const :tag "Fully initialize buffers" t)
1538           (repeat :tag "Hook functions" :value (nil)
1539            (function-item))))
1540
1541 (defcustom reftex-no-include-regexps '("\\.pstex_t\\'")
1542   "*List of regular expressions to exclude certain input files from parsing.
1543 If the name of a file included via \\include or \\input is matched by any
1544 of the regular expressions in this list, that file is not parsed by RefTeX."
1545   :group 'reftex-optimizations-for-large-documents
1546   :type '(repeat (regexp)))
1547
1548 (defcustom reftex-enable-partial-scans nil
1549   "*Non-nil means, re-parse only 1 file when asked to re-parse.
1550 Re-parsing is normally requested with a `C-u' prefix to many RefTeX commands,
1551 or with the `r' key in menus.  When this option is t in a multifile document,
1552 we will only parse the current buffer, or the file associated with the label
1553 or section heading near point in a menu.  Requesting re-parsing of an entire
1554 multifile document then requires a `C-u C-u' prefix or the capital `R' key
1555 in menus."
1556   :group 'reftex-optimizations-for-large-documents
1557   :type 'boolean)
1558
1559 (defcustom reftex-allow-automatic-rescan t
1560   "*Non-nil means, RefTeX may rescan the document when this seems necessary.
1561 Currently this applies only to rescanning after label insertion, when
1562 the new label cannot be inserted correctly into the internal label
1563 list."
1564   :group 'reftex-optimizations-for-large-documents
1565   :type 'boolean)
1566
1567 (defcustom reftex-save-parse-info nil
1568   "*Non-nil means, save information gathered with parsing in a file.
1569 The file MASTER.rel in the same directory as MASTER.tex is used to save the
1570 information.  When this variable is t,
1571 - accessing the parsing information for the first time in an editing session
1572   will read that file (if available) instead of parsing the document.
1573 - exiting Emacs or killing a buffer in reftex-mode will cause a new version
1574   of the file to be written."
1575   :group 'reftex-optimizations-for-large-documents
1576   :type 'boolean)
1577
1578 (defcustom reftex-parse-file-extension ".rel"
1579   "*File extension for the file in which parser information is stored.
1580 This extension is added to the base name of the master file."
1581   :group 'reftex-optimizations-for-large-documents
1582   :type 'string)
1583
1584 (defcustom reftex-use-multiple-selection-buffers nil
1585   "*Non-nil means use a separate selection buffer for each label type.
1586 These buffers are kept from one selection to the next and need not to be
1587 created for each use - so the menu generally comes up faster.  The
1588 selection buffers will be erased (and therefore updated) automatically
1589 when new labels in its category are added.  See the variable
1590 `reftex-auto-update-selection-buffers'."
1591   :group 'reftex-optimizations-for-large-documents
1592   :group 'reftex-referencing-labels
1593   :type 'boolean)
1594
1595 (defcustom reftex-auto-update-selection-buffers t
1596   "*Non-nil means, selection buffers will be updated automatically.
1597 When a new label is defined with `reftex-label', all selection buffers
1598 associated with that label category are emptied, in order to force an
1599 update upon next use.  When nil, the buffers are left alone and have to be
1600 updated by hand, with the `g' key from the label selection process.
1601 The value of this variable will only have any effect when
1602 `reftex-use-multiple-selection-buffers' is non-nil."
1603   :group 'reftex-optimizations-for-large-documents
1604   :group 'reftex-referencing-labels
1605   :type 'boolean)
1606
1607 ;; Fontification and Faces ----------------------------------------------
1608
1609 (defgroup reftex-fontification-configurations nil
1610   "Options concerning the faces used in RefTeX."
1611   :group 'reftex)
1612
1613 (defcustom reftex-use-fonts t
1614   "*Non-nil means, use fonts in *toc* and selection buffers.
1615 Font-lock must be loaded as well to actually get fontified display.
1616 When changing this option, a rescan may be necessary to activate the change."
1617   :group 'reftex-fontification-configurations
1618   :type 'boolean)
1619
1620 (defcustom reftex-refontify-context 1
1621   "*Non-nil means, re-fontify the context in the label menu with font-lock.
1622 This slightly slows down the creation of the label menu.  It is only necessary
1623 when you definitely want the context fontified.
1624
1625 This option may have 3 different values:
1626 nil  Never refontify.
1627 t    Always refontify.
1628 1    Refontify when absolutely necessary, e.g. when old versions of X-Symbol.
1629 The option is ignored when `reftex-use-fonts' is nil."
1630   :group 'reftex-fontification-configurations
1631   :group 'reftex-referencing-labels
1632   :type '(choice
1633           (const :tag "Never" nil)
1634           (const :tag "Always" t)
1635           (const :tag "When necessary" 1)))
1636
1637 (defcustom reftex-highlight-selection 'cursor
1638   "*Non-nil mean, highlight selected text in selection and *toc* buffers.
1639 Normally, the text near the cursor is the selected text, and it is
1640 highlighted.  This is the entry most keys in the selction and *toc*
1641 buffers act on.  However, if you mainly use the mouse to select an
1642 item, you may find it nice to have mouse-triggered highlighting
1643 instead or as well. The variable may have one of these values:
1644
1645    nil      No highlighting.
1646    cursor   Highlighting is cursor driven.
1647    mouse    Highlighting is mouse driven.
1648    both     Both cursor and mouse trigger highlighting.
1649
1650 Changing this variable requires to rebuild the selection and *toc* buffers
1651 to become effective (keys `g' or `r')."
1652   :group 'reftex-fontification-configurations
1653   :type '(choice
1654           (const :tag "Never" nil)
1655           (const :tag "Cursor driven" cursor)
1656           (const :tag "Mouse driven" mouse)
1657           (const :tag "Mouse and Cursor driven." both)))
1658
1659 (defcustom reftex-cursor-selected-face 'highlight
1660   "Face name to highlight cursor selected item in toc and selection buffers.
1661 See also the variable `reftex-highlight-selection'."
1662   :group 'reftex-fontification-configurations
1663   :type 'symbol)
1664 (defcustom reftex-mouse-selected-face 'secondary-selection
1665   "Face name to highlight mouse selected item in toc and selection buffers.
1666 See also the variable `reftex-highlight-selection'."
1667   :group 'reftex-fontification-configurations
1668   :type 'symbol)
1669 (defcustom reftex-file-boundary-face 'font-lock-comment-face
1670   "Face name for file boundaries in selection buffer."
1671   :group 'reftex-fontification-configurations
1672   :type 'symbol)
1673 (defcustom reftex-label-face 'font-lock-constant-face
1674   "Face name for labels in selection buffer."
1675   :group 'reftex-fontification-configurations
1676   :type 'symbol)
1677 (defcustom reftex-section-heading-face 'font-lock-function-name-face
1678   "Face name for section headings in toc and selection buffers."
1679   :group 'reftex-fontification-configurations
1680   :type 'symbol)
1681 (defcustom reftex-toc-header-face 'font-lock-comment-face
1682   "Face name for the header of a toc buffer."
1683   :group 'reftex-fontification-configurations
1684   :type 'symbol)
1685 (defcustom reftex-bib-author-face 'font-lock-keyword-face
1686   "Face name for author names in bib selection buffer."
1687   :group 'reftex-fontification-configurations
1688   :type 'symbol)
1689 (defcustom reftex-bib-year-face 'font-lock-comment-face
1690   "Face name for year in bib selection buffer."
1691   :group 'reftex-fontification-configurations
1692   :type 'symbol)
1693 (defcustom reftex-bib-title-face 'font-lock-function-name-face
1694   "Face name for article title in bib selection buffer."
1695   :group 'reftex-fontification-configurations
1696   :type 'symbol)
1697 (defcustom reftex-bib-extra-face 'font-lock-comment-face
1698   "Face name for bibliographic information in bib selection buffer."
1699   :group 'reftex-fontification-configurations
1700   :type 'symbol)
1701 (defcustom reftex-select-mark-face 'bold
1702   "Face name for marked entries in the selection buffers."
1703   :group 'reftex-fontification-configurations
1704   :type 'symbol)
1705 (defcustom reftex-index-header-face 'font-lock-comment-face
1706   "Face name for the header of an index buffer."
1707   :group 'reftex-fontification-configurations
1708   :type 'symbol)
1709 (defcustom reftex-index-section-face 'font-lock-function-name-face
1710   "Face name for the start of a new letter section in the index."
1711   :group 'reftex-fontification-configurations
1712   :type 'symbol)
1713 (defcustom reftex-index-tag-face 'font-lock-keyword-face
1714   "Face name for index names (for multiple indices)."
1715   :group 'reftex-fontification-configurations
1716   :type 'symbol)
1717 (defcustom reftex-index-face 'font-lock-constant-face
1718   "Face name for index entries."
1719   :group 'reftex-fontification-configurations
1720   :type 'symbol)
1721
1722 (defcustom reftex-pre-refontification-functions nil
1723   "X-Symbol specific hook.
1724 Functions get two arguments, the buffer from where the command started and a
1725 symbol indicating in what context the hook is called."
1726   :group 'reftex-fontification-configurations
1727   :type 'hook)
1728
1729 ;; Miscellaneous configurations -----------------------------------------
1730
1731 (defgroup reftex-miscellaneous-configurations nil
1732   "Collection of further configurations."
1733   :group 'reftex)
1734
1735 (defcustom reftex-extra-bindings nil
1736   "Non-nil means, make additional key bindings on startup.
1737 These extra bindings are located in the users `C-c letter' map."
1738   :group 'reftex-miscellaneous-configurations
1739   :type 'boolean)
1740
1741 (defcustom reftex-plug-into-AUCTeX nil
1742   "*Plug-in flags for AUCTeX interface.
1743 This variable is a list of 4 boolean flags.  When a flag is non-nil,
1744 RefTeX will
1745
1746   - supply labels in new sections and environments  (flag 1)
1747   - supply arguments for macros like `\\label'.      (flag 2)
1748   - supply arguments for macros like `\\ref'.        (flag 3)
1749   - supply arguments for macros like `\\cite'.       (flag 4)
1750   - supply arguments for macros like `\\index'.      (flag 5)
1751
1752 You may also set the variable itself to t or nil in order to turn all
1753 plug-ins on or off, respectively.
1754 \\<LaTeX-mode-map>Supplying labels in new sections and environments applies when creating
1755 sections with \\[LaTeX-section] and environments with \\[LaTeX-environment].
1756 Supplying macro arguments applies when you insert such a macro interactively
1757 with \\[TeX-insert-macro].
1758 See the AUCTeX documentation for more information.
1759 RefTeX uses `fset' to take over the function calls.  Changing the variable
1760 may require a restart of Emacs in order to become effective."
1761   :group 'reftex-miscellaneous-configurations
1762   :group 'LaTeX
1763   :type '(choice
1764           (const :tag "No plug-ins" nil)
1765           (const :tag "All possible plug-ins" t)
1766           (list
1767            :tag "Individual choice"
1768            :value (t t t t t)
1769            (boolean :tag "supply label in new sections and environments")
1770            (boolean :tag "supply argument for macros like `\\label'     ")
1771            (boolean :tag "supply argument for macros like `\\ref'       ")
1772            (boolean :tag "supply argument for macros like `\\cite'      ")
1773            (boolean :tag "supply argument for macros like `\\index'     ")
1774            )))
1775
1776 (defcustom reftex-allow-detached-macro-args nil
1777   "*Non-nil means, allow arguments of macros to be detached by whitespace.
1778 When this is t, `aaa' will be considered as argument of \\bb in the following
1779 construct:  \\bbb [xxx] {aaa}."
1780   :group 'reftex-miscellaneous-configurations
1781   :type 'boolean)
1782
1783
1784 (defcustom reftex-load-hook nil
1785   "Hook which is being run when loading reftex.el."
1786   :group 'reftex-miscellaneous-configurations
1787   :type 'hook)
1788
1789 (defcustom reftex-mode-hook nil
1790   "Hook which is being run when turning on RefTeX mode."
1791   :group 'reftex-miscellaneous-configurations
1792   :type 'hook)
1793
1794
1795 (provide 'reftex-vars)
1796
1797 ;;; reftex-vars.el ends here