code.delx.au - gnu-emacs/blob - lisp/textmodes/reftex-vars.el

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