Variable: reftex-special-environment-functions

reftex-special-environment-functions is a customizable variable defined in reftex-vars.el.gz.

Value

nil

Documentation

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
              (concat "^[ \\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 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))

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/reftex-vars.el.gz
(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
              (concat \"^[ \\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 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)