root/trunk/lisp/textmodes/reftex-vars.el

;;; reftex-vars.el --- configuration variables for RefTeX

;; Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005,
;;   2006, 2007, 2008 Free Software Foundation, Inc.

;; Author: Carsten Dominik <dominik@science.uva.nl>
;; Maintainer: auctex-devel@gnu.org
;; Version: 4.31

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE   See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING  If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.

;;; Commentary:

;;; Code:
(eval-when-compile (defvar reftex-tables-dirty))
(eval-when-compile (require 'cl))
(eval-and-compile
  (defun reftex-set-dirty (symbol value)
    (setq reftex-tables-dirty t)
    (set symbol value)))

;; Define the two constants which are needed during compilation

(eval-and-compile
(defconst reftex-label-alist-builtin
  '(
    ;; Some aliases, mostly for backward compatibility
    (Sideways    "Alias for -->rotating" (rotating))
    (AMSTeX      "amsmath with eqref macro"
                 ((nil ?e nil "~\\eqref{%s}")
                  amsmath))

    ;; Individual package defaults
    (amsmath "AMS-LaTeX math environments"
     (("align"        ?e nil nil eqnarray-like)
      ("gather"       ?e nil nil eqnarray-like)
      ("multline"     ?e nil nil t)
      ("flalign"      ?e nil nil eqnarray-like)
      ("alignat"      ?e nil nil alignat-like)
      ("xalignat"     ?e nil nil alignat-like)
      ("xxalignat"    ?e nil nil alignat-like)
      ("subequations" ?e nil nil t)))

    (endnotes "The \\endnote macro"
     (("\\endnote[]{}" ?N "en:" "~\\ref{%s}" 2
       (regexp "endnotes?" "notes?" "Anmerkung\\(en\\)?" "Anm\\."))))

    (fancybox "The Beqnarray environment"
     (("Beqnarray" ?e nil nil eqnarray-like)))

    (floatfig "The floatingfigure environment"
     (("floatingfigure" ?f nil nil caption)))

    (longtable   "The longtable environment"
     (("longtable"  ?t nil nil caption)))

    (picinpar    "The figwindow and tabwindow environments"
     (("figwindow" ?f nil nil 1)
      ("tabwindow" ?f nil nil 1)))

    (rotating    "Sidewaysfigure and table"
     (("sidewaysfigure" ?f nil nil caption)
      ("sidewaystable"  ?t nil nil caption)))

    (sidecap      "CSfigure and SCtable"
     (("SCfigure"       ?f nil nil caption)
      ("SCtable"        ?t nil nil caption)))

    (subfigure   "Subfigure environments/macro"
     (("subfigure"   ?f nil nil caption)
      ("subfigure*"  ?f nil nil caption)
      ("\\subfigure[]{}" ?f nil nil 1)))

    (supertab    "Supertabular environment"
     (("supertabular" ?t nil nil "\\tablecaption{")))

    (wrapfig     "The wrapfigure environment"
     (("wrapfigure" ?f nil nil caption)))

    ;; The LaTeX core stuff
    (LaTeX       "LaTeX default environments"
     (("section"   ?s "%S" "~\\ref{%s}" (nil . t)
       (regexp "parts?" "chapters?" "chap\\." "sections?" "sect?\\."
               "paragraphs?" "par\\."
               "\\\\S" "\247" "Teile?" "Kapitel" "Kap\\." "Abschnitte?"
               "appendi\\(x\\|ces\\)" "App\\."  "Anh\"?ange?" "Anh\\."))

      ("enumerate" ?i "item:" "~\\ref{%s}" item
       (regexp "items?" "Punkte?"))
      
      ("equation"  ?e "eq:" "~(\\ref{%s})" t
       (regexp "equations?" "eqs?\\." "eqn\\." "Gleichung\\(en\\)?"  "Gl\\."))
      ("eqnarray"  ?e "eq:" nil eqnarray-like)
      
      ("figure"    ?f "fig:" "~\\ref{%s}" caption
       (regexp "figure?[sn]?" "figs?\\." "Abbildung\\(en\\)?" "Abb\\."))
      ("figure*"   ?f nil nil caption)
      
      ("table"     ?t "tab:" "~\\ref{%s}" caption
       (regexp "tables?" "tab\\." "Tabellen?"))
      ("table*"    ?t nil nil caption)
      
      ("\\footnote[]{}" ?n "fn:" "~\\ref{%s}" 2
       (regexp "footnotes?" "Fussnoten?"))
      
      ("any"       ?\  " "   "~\\ref{%s}" nil)

      ;; The label macro is hard coded, but it *could* be defined like this:
      ;;("\\label{*}" nil nil nil nil)
      ))

    )
  "The default label environment descriptions.
Lower-case symbols correspond to a style file of the same name in the LaTeX
distribution.  Mixed-case symbols are convenience aliases.")

(defconst reftex-cite-format-builtin
  '((default "Default macro \\cite{%l}"
      "\\cite[]{%l}")
    (natbib "The Natbib package"
     ((?\C-m . "\\cite[][]{%l}")
      (?t    . "\\citet[][]{%l}")
      (?T    . "\\citet*[][]{%l}")
      (?p    . "\\citep[][]{%l}")
      (?P    . "\\citep*[][]{%l}")
      (?e    . "\\citep[e.g.][]{%l}")
      (?s    . "\\citep[see][]{%l}")
      (?a    . "\\citeauthor{%l}")
      (?A    . "\\citeauthor*{%l}")
      (?y    . "\\citeyear{%l}")
      (?n    . "\\nocite{%l}")))
    (amsrefs "The AMSRefs package"
     ((?\C-m . "\\cite{%l}")
      (?p    . "\\cite{%l}")
      (?P    . "\\cites{%l}")
      (?t    . "\\ocite{%l}")
      (?T    . "\\ocites{%l}")
      (?y    . "\\ycite{%l}")
      (?Y    . "\\ycites{%l}")
      (?a    . "\\citeauthor{%l}")
      (?A    . "\\citeauthory{%l}")
      (?f    . "\\fullcite{%l}")
      (?F    . "\\fullocite{%l}")
      (?n    . "\\nocite{%l}")))
    (jurabib "The Jurabib package"
     ((?\C-m . "\\cite{%l}")
      (?c    . "\\cite[][]{%l}")
      (?t    . "\\citet{%l}")
      (?p    . "\\citep{%l}")
      (?e    . "\\citep[e.g.][]{%l}")
      (?s    . "\\citep[see][]{%l}")
      (?u    . "\\fullcite{%l}")
      (?i    . "\\citetitle{%l}")
      (?a    . "\\citeauthor{%l}")
      (?e    . "\\citefield{}{%l}")
      (?y    . "\\citeyear{%l}")
      (?f    . "\\footcite{%l}")
      (?F    . "\\footcite[][]{%l}")
      (?l    . "\\footfullcite{%l}")))
    (bibentry "The Bibentry package"
      "\\bibentry{%l}")
    (harvard "The Harvard package"
     ((?\C-m . "\\cite[]{%l}")
      (?p    . "\\cite[]{%l}")
      (?t    . "\\citeasnoun{%l}")
      (?n    . "\\citeasnoun{%l}")
      (?s    . "\\possessivecite{%l}")
      (?e    . "\\citeaffixed{%l}{?}")
      (?y    . "\\citeyear{%l}")
      (?a    . "\\citename{%l}")))
    (chicago "The Chicago package"
     ((?\C-m . "\\cite[]{%l}")
      (?t    . "\\citeN[]{%l}")
      (?T    . "\\shortciteN{%l}")
      (?p    . "\\cite[]{%l}")
      (?P    . "\\shortcite{%l}")
      (?a    . "\\citeA{%l}")
      (?A    . "\\shortciteA{%l}")
      (?y    . "\\citeyear{%l}")))
    (astron "The Astron package"
     ((?\C-m . "\\cite[]{%l}")
      (?p    . "\\cite[]{%l}" )
      (?t    . "%2a (\\cite{%l})")))
    (author-year "Do-it-yourself Author-year"
     ((?\C-m . "\\cite{%l}")
      (?t    . "%2a (%y)\\nocite{%l}")
      (?p    . "(%2a %y\\nocite{%l})")))
    (locally     "Full info in parenthesis"
     "(%2a %y, %j %v, %P, %e: %b, %u, %s %<)")
    )
  "Builtin versions of the citation format.
The following conventions are valid for all alist entries:
`?\C-m' should always point to a straight \\cite{%l} macro.
`?t'    should point to a textual citation (citation as a noun).
`?p'    should point to a parenthetical citation.")

(defconst reftex-index-macros-builtin 
  '((default "Default \\index and \\glossary macros"
      (("\\index{*}" "idx" ?i "" nil t)
       ("\\glossary{*}" "glo" ?g "" nil t)))
    (multind "The multind.sty package"
       (("\\index{}{*}" 1 ?i "" nil t)))
    (index "The index.sty package"
           (("\\index[]{*}" 1 ?i "" nil t)
            ("\\index*[]{*}" 1 ?I "" nil nil)))
    (Index-Shortcut "index.sty with \\shortindexingon"
       (("\\index[]{*}" 1 ?i "" nil t)
        ("\\index*[]{*}" 1 ?I "" nil nil)
        ("^[]{*}" 1 ?^ "" texmathp t)   
        ("_[]{*}" 1 ?_ "" texmathp nil))))
  "Builtin stuff for reftex-index-macros.
Lower-case symbols correspond to a style file of the same name in the LaTeX
distribution.  Mixed-case symbols are convenience aliases.")
)

;; Configuration Variables and User Options for RefTeX ------------------

(defgroup reftex nil
  "LaTeX label and citation support."
  :tag "RefTeX"
  :link '(url-link :tag "Home Page" 
                   "http://staff.science.uva.nl/~dominik/Tools/reftex/")
  :link '(emacs-commentary-link :tag "Commentary in reftex.el" "reftex.el")
  :link '(custom-manual "(reftex)Top")
  :prefix "reftex-"
  :group 'tex)


;; Table of contents configuration --------------------------------------

(defgroup reftex-table-of-contents-browser nil
  "A multifile table of contents browser."
  :group 'reftex)

(defcustom reftex-include-file-commands '("include" "input")
  "LaTeX commands which input another file.
The file name is expected after the command, either in braces or separated
by whitespace."
  :group 'reftex-table-of-contents-browser
  :type '(repeat string))

(defcustom reftex-max-section-depth 12
  "Maximum depth of section levels in document structure.
Standard LaTeX needs default is 7, but there are packages for which this
needs to be larger."
  :group 'reftex-table-of-contents-browser
  :type 'integer)

;; LaTeX section commands and level numbers
(defcustom reftex-section-levels
  '(
    ("part"            .  0)
    ("chapter"         .  1)
    ("section"         .  2)
    ("subsection"      .  3)
    ("subsubsection"   .  4)
    ("paragraph"       .  5)
    ("subparagraph"    .  6)
    ("addchap"         . -1) ; KOMA-Script
    ("addsec"          . -2) ; KOMA-Script
;;; ("minisec"         . -7) ; KOMA-Script
    )
  "Commands and levels used for defining sections in the document.
This is an alist with each element like (COMMAND-NAME . LEVEL).
The car of each cons cell is the name of the section macro (without
the backslash).  The cdr is a number indicating its level.  A negative
level means the same level as the positive value, but the section will
never get a number.  The cdr may also be a function which will be called
to after the section-re matched to determine the level.
This list is also used for promotion and demption of sectioning commands.
If you are using a document class which has several sets of sectioning
commands, promotion only works correctly if this list is sorted first
by set, then within each set by level.  The promotion commands always
select the nearest entry with the correct new level."
  :group 'reftex-table-of-contents-browser
  :set 'reftex-set-dirty
  :type '(repeat
          (cons (string :tag "sectioning macro" "")
                (choice
                 (number :tag "level           " 0)
                 (symbol :tag "function        " my-level-func)))))

(defcustom reftex-toc-max-level 100
  "*The maximum level of toc entries which will be included in the TOC.
Section headings with a bigger level will be ignored.  In RefTeX, chapters
are level 1, sections are level 2 etc.
This variable can be changed from within the *toc* buffer with the `t' key."
  :group 'reftex-table-of-contents-browser
  :type 'integer)

(defcustom reftex-part-resets-chapter nil
  "*Non-nil means, \\part is like any other sectioning command.
This means, part numbers will be included in the numbering of chapters, and
chapter counters will be reset for each part.
When nil (the default), parts are special, do not reset the chapter counter
and also do not show up in chapter numbers."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)


(defcustom reftex-auto-recenter-toc 'frame
  "*Non-nil means, turn automatic recentering of *TOC* window on.
When active, the *TOC* window will always show the section you
are currently working in.  Recentering happens whenever Emacs is idle for
more than `reftex-idle-time' seconds.

Value t means, turn on immediately when RefTeX gets started.  Then,
recentering will work for any toc window created during the session.

Value 'frame (the default) means, turn automatic recentering on only while the
dedicated TOC frame does exist, and do the recentering only in that frame.  So
when creating that frame (with \"d\" key in an ordinary TOC window), the
automatic recentering is turned on.  When the frame gets destroyed, automatic
recentering is turned off again.

This feature can be turned on and off from the menu 
\(Ref->Options)."
  :group 'reftex-table-of-contents-browser
  :type '(choice
          (const :tag "never" nil)
          (const :tag "always" t)
          (const :tag "in dedicated frame only" frame)))
 
(defcustom reftex-toc-split-windows-horizontally nil
  "*Non-nil means, create TOC window by splitting window horizontally."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-split-windows-fraction .3
  "*Fraction of the width or height of the frame to be used for TOC window.
See also `reftex-toc-split-windows-horizontally'."
  :group 'reftex-table-of-contents-browser
  :type 'number)

(defvar reftex-toc-split-windows-horizontally-fraction 0.5
  "This variable is obsolete, use `reftex-toc-split-windows-fraction' instead.")

(defcustom reftex-toc-keep-other-windows t
  "*Non-nil means, split the selected window to display the *toc* buffer.
This helps to keep the window configuration, but makes the *toc* small.
When nil, all other windows except the selected one will be deleted, so
that the *toc* window fills half the frame."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-include-file-boundaries nil
  "*Non-nil means, include file boundaries in *toc* buffer.
This flag can be toggled from within the *toc* buffer with the `F' key."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-include-labels nil
  "*Non-nil means, include labels in *toc* buffer.
This flag can be toggled from within the *toc* buffer with the `l' key."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-include-index-entries nil
  "*Non-nil means, include index entries in *toc* buffer.
This flag can be toggled from within the *toc* buffer with the `i' key."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-confirm-promotion 2
  "*Non-nil means, promotion/demotion commands first prompt for confirmation.
When nil, the command is executed immediately.  When this is an integer
N, ask for confirmation only if N or more section commands are going to be
changed."
  :group 'reftex-table-of-contents-browser
  :type '(choice
          (const  :tag "Never" nil)
          (const  :tag "Always" t)
          (number :tag "When more than N sections" :value 2)))

(defcustom reftex-toc-include-context nil
  "*Non-nil means, include context with labels in the *toc* buffer.
Context will only be shown when labels are visible as well.
This flag can be toggled from within the *toc* buffer with the `c' key."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-toc-follow-mode nil
  "*Non-nil means, point in *toc* buffer will cause other window to follow.
The other window will show the corresponding part of the document.
This flag can be toggled from within the *toc* buffer with the `f' key."
  :group 'reftex-table-of-contents-browser
  :type 'boolean)

(defcustom reftex-revisit-to-follow nil
  "*Non-nil means, follow-mode will revisit files if necessary.
When nil, follow-mode will be suspended for stuff in unvisited files."
  :group 'reftex-table-of-contents-browser
  :group 'reftex-referencing-labels
  :type 'boolean)

(defcustom reftex-toc-mode-hook nil
  "Mode hook for reftex-toc-mode."
  :group 'reftex-table-of-contents-browser
  :type 'hook)

;; Label Support Configuration

(defgroup reftex-label-support nil
  "Support for creation, insertion and referencing of labels in LaTeX."
  :group 'reftex)

(defgroup reftex-defining-label-environments nil
  "Definition of environments and macros to do with label."
  :group 'reftex-label-support)

(defcustom reftex-default-label-alist-entries
  '(amsmath endnotes fancybox floatfig longtable picinpar
            rotating sidecap subfigure supertab wrapfig LaTeX)
  "Default label alist specifications.  LaTeX should always be the last entry.
The value of this variable is a list of symbols with associations in the 
constant `reftex-label-alist-builtin'.  Check that constant for a full list
of options."
  :group 'reftex-defining-label-environments
  :set   'reftex-set-dirty
  :type `(set
          :indent 4
          :inline t
          :greedy t
          ,@(mapcar
             (lambda (x)
               (list 'const :tag (concat (symbol-name (nth 0 x))
                                         ": " (nth 1 x))
                     (nth 0 x)))
             reftex-label-alist-builtin)))

(defcustom reftex-label-alist nil
  "Alist with information on environments for \\label-\\ref use.

This docstring is easier to understand after reading the configuration
examples in `reftex.el'.  Looking at the builtin defaults in the constant
`reftex-label-alist-builtin' may also be instructive.

Set this variable to define additions and changes to the default.  The only
things you MUST NOT change is that `?s' is the type indicator for section
labels, and SPC for the `any' label type.  These are hard-coded at other
places in the code.

The value of the variable must be a list of items.  Each item is a list
itself and has the following structure:

 (ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT CONTEXT-METHOD
           (MAGIC-WORD ... ) TOC-LEVEL)

Each list entry describes either an environment carrying a counter for use
with \\label and \\ref, or a LaTeX macro defining a label as (or inside)
one of its arguments.  The elements of each list entry are:

ENV-OR-MACRO
    Name of the environment (like \"table\") or macro (like \"\\\\myfig\").
    For macros, indicate the macro arguments for best results, as in
    \"\\\\myfig[]{}{}{*}{}\".  Use square brackets for optional arguments,
    a star to mark the label argument, if any.  The macro does not have to
    have a label argument - you could also use \\label{..} inside one of
    its arguments.
    Special names: `section' for section labels, `any' to define a group
    which contains all labels.

    This may also be a function to do local parsing and identify point
    to be in a non-standard label environment.  The function must take
    an argument BOUND and limit backward searches to this value.  It
    should return either nil or a cons cell (FUNCTION . POSITION) with
    the function symbol and the position where the special environment
    starts.  See the Info documentation for an example.

    Finally this may also be nil if the entry is only meant to change
    some settings associated with the type indicator character (see below).

TYPE-KEY
    Type indicator character, like `?t', must be a printable ASCII character.
    The type indicator is a single character which defines a label type.
    Any label inside the environment or macro is assumed to belong to this
    type.  The same character may occur several times in this list, to cover
    cases in which different environments carry the same label type (like
    `equation' and `eqnarray').
    If the type indicator is nil and the macro has a label argument {*},
    the macro defines neutral labels just like \\label.  In this case
    the reminder of this entry is ignored.

LABEL-PREFIX
    Label prefix string, like \"tab:\".
    The prefix is a short string used as the start of a label.  It may be the
    empty string.  The prefix may contain the following `%' escapes:
       %f   Current file name with directory and extension stripped.
       %F   Current file name relative to directory of master file.
       %m   Master file name, directory and extension stripped.
       %M   Directory name (without path) where master file is located.
       %u   User login name, on systems which support this.
       %S   A section prefix derived with variable `reftex-section-prefixes'.

    Example: In a file `intro.tex', \"eq:%f:\" will become \"eq:intro:\").

REFERENCE-FORMAT
    Format string for reference insert in buffer.  `%s' will be replaced by
    the label.
    When the format starts with `~', the `~' will only be inserted if
    there is not already a whitespace before point.

CONTEXT-METHOD
    Indication on how to find the short context.
    - If nil, use the text following the \\label{...} macro.
    - If t, use
       - the section heading for section labels.
       - text following the \\begin{...} statement of environments.
         (not a good choice for environments like eqnarray or enumerate,
         where one has several labels in a single environment).
       - text after the macro name (starting with the first arg) for macros.
    - If an integer, use the nth argument of the macro.  As a special case,
      1000 means to get text after the last macro argument.
    - If a string, use as regexp to search *backward* from the label.  Context
      is then the text following the end of the match.  E.g. putting this to
      \"\\\\\\\\caption[[{]\" will use the caption in a figure or table
      environment.
      \"\\\\\\\\begin{eqnarray}\\\\|\\\\\\\\\\\\\\\\\" works for eqnarrays.
    - If any of `caption', `item', `eqnarray-like', `alignat-like', this
      symbol will internally be translated into an appropriate regexp
      (see also the variable `reftex-default-context-regexps').
    - If a function, call this function with the name of the environment/macro
      as argument.  On call, point will be just after the \\label macro.  The
      function is expected to return a suitable context string.  It should
      throw an exception (error) when failing to find context.
      As an example, here is a function returning the 10 chars following
      the label macro as context:

        (defun my-context-function (env-or-mac)
          (if (> (point-max) (+ 10 (point)))
              (buffer-substring (point) (+ 10 (point)))
            (error \"Buffer too small\")))

    Label context is used in two ways by RefTeX: For display in the label
    menu, and to derive a label string.  If you want to use a different
    method for each of these, specify them as a dotted pair.
    E.g. `(nil . t)' uses the text after the label (nil) for display, and
    text from the default position (t) to derive a label string.  This is
    actually used for section labels.

MAGIC-WORDS
    List of magic words which identify a reference to be of this type.
    If the word before point is equal to one of these words when calling
    `reftex-reference', the label list offered will be automatically
    restricted to labels of the correct type.
    If the first element of this wordlist is the symbol `regexp', the
    strings are interpreted as regular expressions.  RefTeX will add
    a \"\\\\W\" to the beginning and other stuff to the end of the regexp.

TOC-LEVEL
    The integer level at which this environment should be added to the
    table of contents.  See also `reftex-section-levels'.  A positive
    value will number the entries mixed with the sectioning commands of
    the same level.  A negative value will make unnumbered entries.
    Useful only for theorem-like environments, will be ignored for macros.
    When omitted or nil, no TOC entries will be made.

If the type indicator characters of two or more entries are the same, RefTeX
will use
 - the first non-nil format and prefix
 - the magic words of all involved entries.

Any list entry may also be a symbol.  If that has an association in
`reftex-label-alist-builtin', the cddr of that association is spliced into the
list.  However, builtin defaults should normally be set with the variable
`reftex-default-label-alist-entries."
  :group 'reftex-defining-label-environments
  :set 'reftex-set-dirty
  :type
  `(repeat
    (choice :tag "Package or Detailed   "
     :value ("" ?a nil nil nil nil)
     (list :tag "Detailed Entry"
           :value ("" ?a nil nil nil nil)
           (choice    :tag "Environment or \\macro "
                      (const  :tag "Ignore, just use typekey" nil)
                      (string "")
                      (symbol :tag "Special parser" my-parser))
           (choice    :tag "Type specification    "
                      (const :tag "unspecified, like in \\label" nil)
                      (character :tag "Char  " ?a))
           (choice    :tag "Label prefix string   "
                      (const  :tag "Default" nil)
                      (string :tag "String" "lab:"))
           (choice    :tag "Label reference format"
                      (const  :tag "Default" nil)
                      (string :tag "String" "~\\ref{%s}"))
           (choice    :tag "Context method        "
                      (const  :tag "Default position" t)
                      (const  :tag "After label"      nil)
                      (number :tag "Macro arg nr" 1)
                      (regexp :tag "Regexp" "")
                      (const  :tag "Caption in float" caption)
                      (const  :tag "Item in list" item)
                      (const  :tag "Eqnarray-like" eqnarray-like)
                      (const  :tag "Alignat-like" alignat-like)
                      (symbol :tag "Function" my-func))
           (repeat :tag "Magic words" :extra-offset 2 (string))
           (option (choice :tag "Make TOC entry     "
                           (const :tag "No entry" nil)
                           (integer :tag "Level" :value -3))))
     (choice
      :tag "Package"
      :value AMSTeX
      ,@(mapcar
         (lambda (x)
           (list 'const :tag (concat (symbol-name (nth 0 x)))
                 (nth 0 x)))
         reftex-label-alist-builtin)))))

(defcustom reftex-section-prefixes '((0 . "part:") (1 . "cha:") (t . "sec:"))
  "Prefixes for section labels.
When the label prefix given in an entry in `reftex-label-alist' contains `%S',
this list is used to determine the correct prefix string depending on the 
current section level.
The list is an alist, with each entry of the form (KEY . PREFIX)
Possible keys are sectioning macro names like `chapter', section levels
\(as given in `reftex-section-levels'), and t for the default."
  :group 'reftex-defining-label-environments
  :type '(repeat
          (cons :value (0 . "")
                (choice
                 (string :tag  "macro name")
                 (integer :tag "section level")
                 (const :tag "default" t))
                (string :tag "Prefix"))))

(defcustom reftex-default-context-regexps
  '((caption       . "\\\\\\(rot\\)?caption\\*?[[{]")
    (item          . "\\\\item\\(\\[[^]]*\\]\\)?")
    (eqnarray-like . "\\\\begin{%s}\\|\\\\\\\\")
    (alignat-like  . "\\\\begin{%s}{[0-9]*}\\|\\\\\\\\"))
"Alist with default regular expressions for finding context.
The form (format regexp (regexp-quote environment)) is used to calculate
the final regular expression - so %s will be replaced with the environment
or macro."
  :group 'reftex-defining-label-environments
  :type '(repeat (cons (symbol) (regexp))))

(defcustom reftex-trust-label-prefix nil
  "Non-nil means, trust the label prefix when determining label type.
It is customary to use special label prefixes to distinguish different label
types.  The label prefixes have no syntactic meaning in LaTeX (unless
special packages like fancyref are being used).  RefTeX can and by
default does parse around each label to detect the correct label type,
but this process can be slow when a document contains thousands of
labels.  If you use label prefixes consistently, you may speed up
document parsing by setting this variable to a non-nil value.  RefTeX
will then compare the label prefix with the prefixes found in
`reftex-label-alist' and derive the correct label type in this way.
Possible values for this option are:

t          This means to trust any label prefixes found.
regexp     If a regexp, only prefixes matched by the regexp are trusted.
list       List of accepted prefixes, as strings.  The colon is part of
           the prefix, e.g. (\"fn:\" \"eqn:\" \"item:\").
nil        Never trust a label prefix.

The only disadvantage of using this feature is that the label context
displayed in the label selection buffer along with each label is
simply some text after the label definition.  This is no problem if you
place labels keeping this in mind (e.g. *before* the equation, *at
the beginning* of a fig/tab caption ...).  Anyway, it is probably best
to use the regexp or the list value types to fine-tune this feature.
For example, if your document contains thousands of footnotes with
labels fn:xxx, you may want to set this variable to the value \"^fn:$\" or
\(\"fn:\").  Then RefTeX will still do extensive parsing for any
non-footnote labels."
  :group 'reftex-defining-label-environments
  :type '(choice
          (const :tag "Always" t)
          (const :tag "Never" nil)
          (regexp)
          (repeat :tag "List"
                  (string :tag "prefix (with colon)"))))
  
(defcustom reftex-special-environment-functions nil
  "List of functions to be called when trying to figure out current environment.
These are special functions to detect \"environments\" which do not
start with \\begin and end with \\end.  Some LaTeX packages seem to
use such non-standard ways to set up environment-like constructs.  The
purpose of each function in this list is to detect if point is
currently inside such a special \"environment\".  If the environment
carries a label, you must also set up an entry for it in
`reftex-label-alist'.

The function should check if point is currently in the special
environment it was written to detect.  If so, the function must return
a cons cell (NAME . POSITION).  NAME is the name of the environment
detected and POSITION is the buffer position where the environment
starts.  The function must return nil on failure to detect the
environment.

The function must take an argument BOUND.  If non-nil, BOUND is a
boundary for backwards searches which should be observed.

Here is an example.  The LaTeX package linguex.sty defines list macros
`\\ex.', `\\a.', etc for lists which are terminated by `\\z.' or an empty
line.

    \\ex.  \\label{ex:12} Some text in an exotic language ...
          \\a. \\label{ex:13} more stuff
          \\b. \\label{ex:14} still more stuff

    ... more text after the empty line terminating all lists

And here is the setup for RefTeX:

1. Define a dummy environment for this in `reftex-label-alist'.  Dummy means,
   make up an environment name even though it is not used with \\begin and
   \\end.  Here we use \"linguex\" as this name.

   (setq reftex-label-alist
         '((\"linguex\" ?x \"ex:\" \"~\\\\ref{%s}\" nil (\"Example\" \"Ex.\"))))

2. Write a function to detect the list macros and the determinators as well.

   (defun my-detect-linguex-list (bound)
     (let ((pos (point)) p1)
       (save-excursion
         ;; Search for any of the linguex item macros at the beginning of a line
         (if (re-search-backward 
              \"^[ \\t]*\\\\(\\\\\\\\\\\\(ex\\\\|a\\\\|b\\\\|c\\\\|d\\\\|e\\\\|f\\\\)g?\\\\.\\\\)\" bound t)
             (progn
               (setq p1 (match-beginning 1))
               ;; Make sure no empty line or \\z. is between us and the item macro
               (if (re-search-forward \"\\n[ \\t]*\\n\\\\|\\\\\\\\z\\\\.\" pos t)
                   ;; Return nil because list was already closed
                   nil
                 ;; OK, we got it
                 (cons \"linguex\" p1)))
           ;; Return nil for not found 
           nil))))

3. Tell RefTeX to use this function

   (setq reftex-special-environment-functions '(my-detect-linguex-list))
"
  :group 'reftex-defining-label-environments
  :type 'hook)

;; Label insertion

(defgroup reftex-making-and-inserting-labels nil
  "Options on how to create new labels."
  :group 'reftex-label-support)