comparison lisp/textmodes/reftex.el @ 21892:f718f5a51f59

C. Dominik <[e-mail]> Added :version tags to defcustoms

21891:7d49e4c824b6

Normally should be nil, unless you want to do something fancy.
The function will be called with two arguments, the LABEL and the DEFAULT
FORMAT, which usually is `\label{%s}'.  The function should return the
string to insert into the buffer."
  :group 'reftex-making-and-inserting-labels
  :type 'function)

;; Label referencing

(defgroup reftex-referencing-labels nil

already be specified in `reftex-label-alist'.
The function will be called with two arguments, the LABEL and the DEFAULT
FORMAT, which normally is `~\ref{%s}'.  The function should return the
string to insert into the buffer."
  :group 'reftex-referencing-labels
  :type 'function)

;; BibteX citation configuration ----------------------------------------

(defgroup reftex-citation-support nil

The file names have to be in the exact same form as in the bibliography
macro - i.e. without the `.bib' extension.
Intended for files which contain only `@string' macro definitions and the
like, which are ignored by RefTeX anyway."
  :group 'reftex-citation-support
  :set 'reftex-set-dirty
  :type '(repeat (string :tag "File name")))

(defcustom reftex-default-bibliography nil
  "*List of BibTeX database file which should be used if none are specified.
When `reftex-citation' is called from a document which has neither a
`\bibliography{..}' statement nor a `thebibliography' environment,
RefTeX will scan these files instead.  Intended for using
`reftex-citation' in non-LaTeX files."
  :group 'reftex-citation-support
  :type '(repeat (file)))

(defcustom reftex-sort-bibtex-matches 'reverse-year
  "*Sorting of the entries found in BibTeX databases by reftex-citation.
Possible values:

already be specified in `reftex-cite-format'.
The function will be called with two arguments, the CITATION KEY and the
DEFAULT FORMAT, which is taken from `reftex-cite-format'.  The function
should return the string to insert into the buffer."
  :group 'reftex-citation-support
  :type 'function)

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

(defgroup reftex-table-of-contents-browser nil

If a buffer is to be kept, the file is visited normally (which is potentially
slow but will happen only once).
If a buffer is to be thrown away, the initialization of the buffer depends
upon the variable `reftex-initialize-temporary-buffers'."
  :group 'reftex-miscellaneous-configurations
  :type '(choice
          (const :tag "Throw away everything" nil)
          (const :tag "Keep everything" t)
          (const :tag "Keep lookup buffers only" 1)))

visit a file.
When t, the full default initializations are done (find-file-hook etc.).
Instead of t or nil, this variable may also be a list of hook functions to
do a minimal initialization."
  :group 'reftex-miscellaneous-configurations
  :type '(choice
          (const :tag "Read files literally" nil)
          (const :tag "Fully initialize buffers" t)
          (repeat :tag "Hook functions" :value (nil)
           (function-item))))

(defcustom reftex-no-include-regexps '("\\.pstex_t\\'") ; default for x-symbol
  "*List of regular expressions to exclude certain input files from parsing.
If the name of a file included via \\include or \\input is matched by any
of the regular expressions in this list, that file is not parsed by RefTeX."
  :group 'reftex-optimizations-for-large-documents
  :type '(repeat (regexp)))

(defcustom reftex-enable-partial-scans nil
  "*Non-nil means, re-parse only 1 file when asked to re-parse.
Re-parsing is normally requested with a `C-u' prefix to many RefTeX commands,

we will only parse the current buffer, or the file associated with the label
or section heading near point in a menu.  Requesting re-parsing of an entire
multifile document then requires a `C-u C-u' prefix or the capital `R' key
in menus."
  :group 'reftex-optimizations-for-large-documents
  :type 'boolean)

(defcustom reftex-allow-automatic-rescan t
  "*Non-nil means, RefTeX may rescan the document when this seems necessary.
Currently this applies only to rescanning after label insertion, when
the new label cannot be inserted correctly into the internal label
list."
  :group 'reftex-optimizations-for-large-documents
  :type 'boolean)

(defcustom reftex-save-parse-info nil
  "*Non-nil means, save information gathered with parsing in a file.
The file MASTER.rel in the same directory as MASTER.tex is used to save the

- accessing the parsing information for the first time in an editing session
  will read that file (if available) instead of parsing the document.
- each time (part of) the document is rescanned, a new version of the file
  is written."
  :group 'reftex-optimizations-for-large-documents
  :type 'boolean)

(defcustom reftex-use-multiple-selection-buffers nil
  "*Non-nil means use a separate selection buffer for each label type.
These buffers are kept from one selection to the next and need not to be
created for each use - so the menu generally comes up faster.  The
selection buffers will be erased (and therefore updated) automatically
when new labels in its category are added.  See the variable
`reftex-auto-update-selection-buffers'."
  :group 'reftex-optimizations-for-large-documents
  :type 'boolean)

(defcustom reftex-auto-update-selection-buffers t
  "*Non-nil means, selection buffers will be updated automatically.
When a new label is defined with `reftex-label', all selection buffers

update upon next use.  When nil, the buffers are left alone and have to be
updated by hand, with the `g' key from the label selection process.
The value of this variable will only have any effect when
`reftex-use-multiple-selection-buffers' is non-nil."
  :group 'reftex-optimizations-for-large-documents
  :type 'boolean)

;; Fontification and Faces ----------------------------------------------

(defgroup reftex-fontification-configurations nil

nil  Never refontify.
t    Always refontify.
1    Refontify when absolutely necessary, e.g. when with the x-symbol package.
The option is ignored when `reftex-use-fonts' is nil."
  :group 'reftex-fontification-configurations
  :type '(choice
          (const :tag "Never" nil)
          (const :tag "Always" t)
          (const :tag "When necessary" 1)))

   nil      No highlighting.
   cursor   Highlighting is cursor driven.
   mouse    Highlighting is mouse driven.
   both     Both cursor and mouse trigger highlighting."
  :group 'reftex-fontification-configurations
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "Cursor driven" cursor)
	  (const :tag "Mouse driven" mouse)
	  (const :tag "Mouse and Cursor driven." both)))

(defcustom reftex-cursor-selected-face 'highlight
  "Face name to highlight cursor selected item in toc and selection buffers.
See also the variable `reftex-highlight-selection'."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-mouse-selected-face 'secondary-selection
  "Face name to highlight mouse selected item in toc and selection buffers.
See also the variable `reftex-highlight-selection'."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-file-boundary-face 'font-lock-comment-face
  "Face name for file boundaries in selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-label-face 'font-lock-constant-face
  "Face name for labels in selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-section-heading-face 'font-lock-function-name-face
  "Face name for section headings in toc and selection buffers."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-toc-header-face 'font-lock-comment-face
  "Face name for the header of a toc buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-bib-author-face 'font-lock-keyword-face
  "Face name for author names in bib selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-bib-year-face 'font-lock-comment-face
  "Face name for year in bib selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-bib-title-face 'font-lock-function-name-face
  "Face name for article title in bib selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)
(defcustom reftex-bib-extra-face 'font-lock-comment-face
  "Face name for bibliographic information in bib selection buffer."
  :group 'reftex-fontification-configurations
  :type 'symbol)

;; Miscellaneous configurations -----------------------------------------

(defgroup reftex-miscellaneous-configurations nil

(defcustom reftex-revisit-to-follow t
  "*Non-nil means, follow-mode will revisit files if necessary.
When nil, follow-mode will be suspended for stuff in unvisited files."
  :group 'reftex-miscellaneous-configurations
  :type '(boolean))

(defcustom reftex-load-hook nil
  "Hook which is being run when loading reftex.el."
  :group 'reftex-miscellaneous-configurations

21892:f718f5a51f59

Normally should be nil, unless you want to do something fancy.
The function will be called with two arguments, the LABEL and the DEFAULT
FORMAT, which usually is `\label{%s}'.  The function should return the
string to insert into the buffer."
  :group 'reftex-making-and-inserting-labels
  :version "20.3"
  :type 'function)

;; Label referencing

(defgroup reftex-referencing-labels nil

already be specified in `reftex-label-alist'.
The function will be called with two arguments, the LABEL and the DEFAULT
FORMAT, which normally is `~\ref{%s}'.  The function should return the
string to insert into the buffer."
  :group 'reftex-referencing-labels
  :version "20.3"
  :type 'function)

;; BibteX citation configuration ----------------------------------------

(defgroup reftex-citation-support nil

The file names have to be in the exact same form as in the bibliography
macro - i.e. without the `.bib' extension.
Intended for files which contain only `@string' macro definitions and the
like, which are ignored by RefTeX anyway."
  :group 'reftex-citation-support
  :version "20.3"
  :set 'reftex-set-dirty
  :type '(repeat (string :tag "File name")))

(defcustom reftex-default-bibliography nil
  "*List of BibTeX database file which should be used if none are specified.
When `reftex-citation' is called from a document which has neither a
`\bibliography{..}' statement nor a `thebibliography' environment,
RefTeX will scan these files instead.  Intended for using
`reftex-citation' in non-LaTeX files."
  :group 'reftex-citation-support
  :version "20.3"
  :type '(repeat (file)))

(defcustom reftex-sort-bibtex-matches 'reverse-year
  "*Sorting of the entries found in BibTeX databases by reftex-citation.
Possible values:

already be specified in `reftex-cite-format'.
The function will be called with two arguments, the CITATION KEY and the
DEFAULT FORMAT, which is taken from `reftex-cite-format'.  The function
should return the string to insert into the buffer."
  :group 'reftex-citation-support
  :version "20.3"
  :type 'function)

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

(defgroup reftex-table-of-contents-browser nil

If a buffer is to be kept, the file is visited normally (which is potentially
slow but will happen only once).
If a buffer is to be thrown away, the initialization of the buffer depends
upon the variable `reftex-initialize-temporary-buffers'."
  :group 'reftex-miscellaneous-configurations
  :version "20.3"
  :type '(choice
          (const :tag "Throw away everything" nil)
          (const :tag "Keep everything" t)
          (const :tag "Keep lookup buffers only" 1)))

visit a file.
When t, the full default initializations are done (find-file-hook etc.).
Instead of t or nil, this variable may also be a list of hook functions to
do a minimal initialization."
  :group 'reftex-miscellaneous-configurations
  :version "20.3"
  :type '(choice
          (const :tag "Read files literally" nil)
          (const :tag "Fully initialize buffers" t)
          (repeat :tag "Hook functions" :value (nil)
           (function-item))))

(defcustom reftex-no-include-regexps '("\\.pstex_t\\'") ; default for x-symbol
  "*List of regular expressions to exclude certain input files from parsing.
If the name of a file included via \\include or \\input is matched by any
of the regular expressions in this list, that file is not parsed by RefTeX."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type '(repeat (regexp)))

(defcustom reftex-enable-partial-scans nil
  "*Non-nil means, re-parse only 1 file when asked to re-parse.
Re-parsing is normally requested with a `C-u' prefix to many RefTeX commands,

we will only parse the current buffer, or the file associated with the label
or section heading near point in a menu.  Requesting re-parsing of an entire
multifile document then requires a `C-u C-u' prefix or the capital `R' key
in menus."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type 'boolean)

(defcustom reftex-allow-automatic-rescan t
  "*Non-nil means, RefTeX may rescan the document when this seems necessary.
Currently this applies only to rescanning after label insertion, when
the new label cannot be inserted correctly into the internal label
list."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type 'boolean)

(defcustom reftex-save-parse-info nil
  "*Non-nil means, save information gathered with parsing in a file.
The file MASTER.rel in the same directory as MASTER.tex is used to save the

- accessing the parsing information for the first time in an editing session
  will read that file (if available) instead of parsing the document.
- each time (part of) the document is rescanned, a new version of the file
  is written."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type 'boolean)

(defcustom reftex-use-multiple-selection-buffers nil
  "*Non-nil means use a separate selection buffer for each label type.
These buffers are kept from one selection to the next and need not to be
created for each use - so the menu generally comes up faster.  The
selection buffers will be erased (and therefore updated) automatically
when new labels in its category are added.  See the variable
`reftex-auto-update-selection-buffers'."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type 'boolean)

(defcustom reftex-auto-update-selection-buffers t
  "*Non-nil means, selection buffers will be updated automatically.
When a new label is defined with `reftex-label', all selection buffers

update upon next use.  When nil, the buffers are left alone and have to be
updated by hand, with the `g' key from the label selection process.
The value of this variable will only have any effect when
`reftex-use-multiple-selection-buffers' is non-nil."
  :group 'reftex-optimizations-for-large-documents
  :version "20.3"
  :type 'boolean)

;; Fontification and Faces ----------------------------------------------

(defgroup reftex-fontification-configurations nil

nil  Never refontify.
t    Always refontify.
1    Refontify when absolutely necessary, e.g. when with the x-symbol package.
The option is ignored when `reftex-use-fonts' is nil."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type '(choice
          (const :tag "Never" nil)
          (const :tag "Always" t)
          (const :tag "When necessary" 1)))

   nil      No highlighting.
   cursor   Highlighting is cursor driven.
   mouse    Highlighting is mouse driven.
   both     Both cursor and mouse trigger highlighting."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "Cursor driven" cursor)
	  (const :tag "Mouse driven" mouse)
	  (const :tag "Mouse and Cursor driven." both)))

(defcustom reftex-cursor-selected-face 'highlight
  "Face name to highlight cursor selected item in toc and selection buffers.
See also the variable `reftex-highlight-selection'."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-mouse-selected-face 'secondary-selection
  "Face name to highlight mouse selected item in toc and selection buffers.
See also the variable `reftex-highlight-selection'."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-file-boundary-face 'font-lock-comment-face
  "Face name for file boundaries in selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-label-face 'font-lock-constant-face
  "Face name for labels in selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-section-heading-face 'font-lock-function-name-face
  "Face name for section headings in toc and selection buffers."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-toc-header-face 'font-lock-comment-face
  "Face name for the header of a toc buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-bib-author-face 'font-lock-keyword-face
  "Face name for author names in bib selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-bib-year-face 'font-lock-comment-face
  "Face name for year in bib selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-bib-title-face 'font-lock-function-name-face
  "Face name for article title in bib selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)
(defcustom reftex-bib-extra-face 'font-lock-comment-face
  "Face name for bibliographic information in bib selection buffer."
  :group 'reftex-fontification-configurations
  :version "20.3"
  :type 'symbol)

;; Miscellaneous configurations -----------------------------------------

(defgroup reftex-miscellaneous-configurations nil

(defcustom reftex-revisit-to-follow t
  "*Non-nil means, follow-mode will revisit files if necessary.
When nil, follow-mode will be suspended for stuff in unvisited files."
  :group 'reftex-miscellaneous-configurations
  :version "20.3"
  :type '(boolean))

(defcustom reftex-load-hook nil
  "Hook which is being run when loading reftex.el."
  :group 'reftex-miscellaneous-configurations