[elpa] 194/299: Distinguish normal and expert macros/envs.

[Stefan Monnier]

monnier pushed a commit to branch externals/auctex
in repository elpa.

commit 76ca21ccacc3d8aa112edcc67f15f17b9b65fbb5
Author: Tassilo Horn <address@hidden>
Date:   Fri Nov 8 20:12:05 2013 +0100

    Distinguish normal and expert macros/envs.
    
    * tex.el (TeX-complete-expert-commands): New defcustom.
    (TeX-complete-make-expert-command-functions): New macro.
    (TeX-insert-macro): Restrict completion depending on
    `TeX-complete-expert-commands'.
    (VirTeX-common-initialization): Ditto.
    
    * latex.el (LaTeX-environment, LaTeX-common-initialization):
    
    * tex-info.el (TeX-texinfo-mode): Restrict completion depending on
    `TeX-complete-expert-commands'.
    
    * doc/auctex.texi: Document normal vs. expert commands for users
    and style file authors.
    
    * doc/changes.texi: Mention normal vs. expert commands.
---
 ChangeLog        |   16 +++++++++++++
 doc/auctex.texi  |   60 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/changes.texi |    9 +++++++
 latex.el         |   10 ++++----
 tex-info.el      |    2 +-
 tex.el           |   63 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 6 files changed, 152 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 600e061..6a4bfbe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,21 @@
 2013-11-08  Tassilo Horn  <address@hidden>
 
+       * tex.el (TeX-complete-expert-commands): New defcustom.
+       (TeX-complete-make-expert-command-functions): New macro.
+       (TeX-insert-macro): Restrict completion depending on
+       `TeX-complete-expert-commands'.
+       (VirTeX-common-initialization): Ditto.
+
+       * latex.el (LaTeX-environment, LaTeX-common-initialization): 
+
+       * tex-info.el (TeX-texinfo-mode): Restrict completion depending on
+       `TeX-complete-expert-commands'.
+
+       * doc/auctex.texi: Document normal vs. expert commands for users
+       and style file authors.
+
+       * doc/changes.texi: Mention normal vs. expert commands.
+
        * latex.el (LaTeX-common-initialization): Fix void-function
        LaTeX-symbol-list error.
 
diff --git a/doc/auctex.texi b/doc/auctex.texi
index 3cf7dcb..6ebb22c 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -869,6 +869,21 @@ document, @AUCTeX{} will default to insert a `document' 
environment.
 Most of these are described further in the following sections, and you
 may easily specify more.  @xref{Customizing Environments}.
 
address@hidden distinguishes normal and expert environments.  By default, it
+will offer completion only for normal environments.  This behavior is
+controlled by the user option @code{TeX-complete-expert-commands}.
+
address@hidden TeX-complete-expert-commands
+Complete macros and environments marked as expert commands.
+
+Possible values are nil, t, or a list of style names.
+
+  - nil           Don't complete expert commands (default).
+  - t             Always complete expert commands.
+  - (STYLES ...)  Only complete expert commands of STYLES.
address@hidden defopt
+
+
 @menu
 * Equations::                   Equations
 * Floats::                      Floats
@@ -1232,6 +1247,21 @@ Completions work because @AUCTeX{} can analyze @TeX{} 
files, and store
 symbols in Emacs Lisp files for later retrieval.  @xref{Automatic}, for
 more information.
 
address@hidden distinguishes normal and expert macros.  By default, it will
+offer completion only for normal commands.  This behavior can be
+controlled using the user option @code{TeX-complete-expert-commands}.
+
address@hidden TeX-complete-expert-commands
+Complete macros and environments marked as expert commands.
+
+Possible values are nil, t, or a list of style names.
+
+  - nil           Don't complete expert commands (default).
+  - t             Always complete expert commands.
+  - (STYLES ...)  Only complete expert commands of STYLES.
address@hidden defopt
+
+
 @cindex \cite, completion of
 @cindex address@hidden, completion
 @cindex cite, completion of
@@ -4369,6 +4399,21 @@ inserting.  If you want point to be located somewhere 
else after all
 hooks have been processed, set the value of @code{exit-mark}.  It will
 point nowhere, until the argument hook sets it.
 
+Some packages provide macros that are rarely useful to non-expert users.
+Those should be marked as expert macros using
address@hidden
+
address@hidden TeX-declare-expert-macros @var{pairs}...
+Declare the macros in PAIRS as expert macros.
+
+Each entry in PAIRS has the form (MACRO . STYLE), declaring MACRO
+to be an expert macro provided by STYLE.  If STYLE is nil,
+declare MACRO to be non-expert.
+
+Expert macros are completed depending on `TeX-complete-expert-commands'.
address@hidden defun
+
+
 @node Adding Environments
 @subsection Adding Support for Environments
 @cindex Adding environments
@@ -4507,6 +4552,21 @@ an optional argument of the @samp{lstlisting} 
environment:
 @end lisp
 @end ftable
 
+Some packages provide environments that are rarely useful to non-expert
+users.  Those should be marked as expert environments using
address@hidden
+
address@hidden LaTeX-declare-expert-environments @var{pairs}...
+Declare the environments in PAIRS as expert environments.
+
+Each entry in PAIRS has the form (ENVIRONMENT . STYLE), declaring ENVIRONMENT
+to be an expert environment provided by STYLE.  If STYLE is nil,
+declare ENVIRONMENT to be non-expert.
+
+Expert environments are completed depending on `TeX-complete-expert-commands'.
address@hidden defun
+
+
 @node Adding Other
 @subsection Adding Other Information
 @cindex Adding bibliographies
diff --git a/doc/changes.texi b/doc/changes.texi
index 949b2e9..a6147fb 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -11,6 +11,15 @@
 
 @itemize @bullet
 @item
+Style file authors are encouraged to distinguish common from expert
+macros/environments, and mark the latter using
address@hidden and
address@hidden
+
+Users can then restrict completion using
address@hidden
+
address@hidden
 Management of @LaTeX{} package options in the parser was improved.  You
 might need to reparse your documents, especially if you loaded the
 @samp{babel} package with language options.
diff --git a/latex.el b/latex.el
index de5de5e..e3ff30c 100644
--- a/latex.el
+++ b/latex.el
@@ -540,7 +540,7 @@ It may be customized with the following variables:
                   (t LaTeX-default-environment)))
     (environment (completing-read (concat "Environment type: (default "
                                          default ") ")
-                                 (LaTeX-environment-list) nil nil nil
+                                 (LaTeX-environment-list-filtered) nil nil nil
                                  'LaTeX-environment-history)))
     ;; Get default
     (cond ((zerop (length environment))
@@ -5642,12 +5642,12 @@ i.e. you do _not_ have to cater for this yourself by 
adding \\\\' or $."
                  ("\\\\pageref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
                  ("\\\\\\(index\\|glossary\\){\\([^{}\n\r\\%]*\\)"
                   2 LaTeX-index-entry-list "}")
-                 ("\\\\begin{\\([A-Za-z]*\\)" 1 LaTeX-environment-list "}")
-                 ("\\\\end{\\([A-Za-z]*\\)" 1 LaTeX-environment-list "}")
+                 ("\\\\begin{\\([A-Za-z]*\\)" 1 
LaTeX-environment-list-filtered "}")
+                 ("\\\\end{\\([A-Za-z]*\\)" 1 LaTeX-environment-list-filtered 
"}")
                  ("\\\\renewcommand\\*?{\\\\\\([A-Za-z]*\\)"
-                  1 TeX-symbol-list "}")
+                  1 TeX-symbol-list-filtered "}")
                  ("\\\\renewenvironment\\*?{\\([A-Za-z]*\\)"
-                  1 LaTeX-environment-list "}")
+                  1 LaTeX-environment-list-filtered "}")
                   ("\\\\\\(this\\)?pagestyle{\\([A-Za-z]*\\)"
                   1 LaTeX-pagestyle-list "}"))
                TeX-complete-list))
diff --git a/tex-info.el b/tex-info.el
index 2e19ce1..c1df5ec 100644
--- a/tex-info.el
+++ b/tex-info.el
@@ -609,7 +609,7 @@ value of `Texinfo-mode-hook'."
 
   (make-local-variable 'TeX-complete-list)
   (setq TeX-complete-list
-       (list (list "@\\([a-zA-Z]*\\)" 1 'TeX-symbol-list nil)
+       (list (list "@\\([a-zA-Z]*\\)" 1 'TeX-symbol-list-filtered nil)
              (list "" TeX-complete-word)))
 
   (make-local-variable 'TeX-font-list)
diff --git a/tex.el b/tex.el
index 17c8a4f..58fef46 100644
--- a/tex.el
+++ b/tex.el
@@ -2515,6 +2515,64 @@ FORCE is not nil."
   "*Function to call for completing non-macros in `tex-mode'."
   :group 'TeX-macro)
 
+(defcustom TeX-complete-expert-commands nil
+  "Complete macros and environments marked as expert commands.
+
+Possible values are nil, t, or a list of style names.
+
+  - nil           Don't complete expert commands (default).
+  - t             Always complete expert commands.
+  - (STYLES ...)  Only complete expert commands of STYLES."
+  :group 'TeX-macro
+  :type '(choice (const  :tag "Don't complete expert commands" nil)
+                (const  :tag "Always complete expert commands" t)
+                (repeat :tag "Complete expert commands of certain styles" 
string)))
+
+(defmacro TeX-complete-make-expert-command-functions (thing list-var prefix)
+  (let ((plural (concat thing "s"))
+       (upcase (upcase thing)))
+    `(progn
+       (defvar ,(intern (format "%s-expert-%s-table" prefix thing))
+        (make-hash-table :test 'equal)
+        ,(format "A hash-table mapping %s names to the style name providing it.
+
+A %s occuring in this table is considered an expert %s and
+treated specially in the completion." thing thing thing))
+
+       (defun ,(intern (format "%s-declare-expert-%s" prefix plural)) (&rest 
pairs)
+        ,(format "Declare the %s in PAIRS as expert %s.
+
+Each entry in PAIRS has the form (%s . STYLE), declaring %s
+to be an expert %s provided by STYLE.  If STYLE is nil,
+declare %s to be non-expert.
+
+Expert %s are completed depending on `TeX-complete-expert-commands'."
+                plural plural upcase upcase thing upcase plural)
+        (dolist (entry pairs)
+          (let ((macro (car entry))
+                (style (cdr entry)))
+            (if (null style)
+                (remhash macro TeX-expert-macro-table)
+              (puthash macro style TeX-expert-macro-table)))))
+
+       (defun ,(intern (format "%s-filtered" list-var)) ()
+        ,(format "Return (%s) filtered depending on 
`TeX-complete-expert-commands'."
+                 list-var)
+        (delq nil
+              (mapcar
+               (lambda (entry)
+                 (if (eq t TeX-complete-expert-commands)
+                     entry
+                   (let* ((cmd (car entry))
+                          (style (gethash cmd TeX-expert-macro-table)))
+                     (when (or (null style)
+                               (member style TeX-complete-expert-commands))
+                       entry))))
+               (,list-var)))))))
+
+(TeX-complete-make-expert-command-functions "macro" TeX-symbol-list "TeX")
+(TeX-complete-make-expert-command-functions "environment" 
LaTeX-environment-list "LaTeX")
+
 (defvar TeX-complete-list nil
   "List of ways to complete the preceding text.
 
@@ -2656,7 +2714,7 @@ is called with \\[universal-argument]."
                                              TeX-default-macro
                                              "): "
                                              TeX-esc)
-                                     (TeX-symbol-list) nil nil nil
+                                     (TeX-symbol-list-filtered) nil nil nil
                                      'TeX-macro-history)))
   (cond ((string-equal symbol "")
         (setq symbol TeX-default-macro))
@@ -3074,7 +3132,8 @@ The algorithm is as follows:
   (make-local-variable 'TeX-complete-list)
   (setq TeX-complete-list
        (list (list "\\\\\\([a-zA-Z]*\\)"
-                   1 'TeX-symbol-list (if TeX-insert-braces "{}"))
+                   1 'TeX-symbol-list-filtered
+                   (if TeX-insert-braces "{}"))
              (list "" TeX-complete-word)))
 
   (funcall TeX-install-font-lock)