[AUCTeX-diffs] GNU AUCTeX branch, master, updated. 76ca21ccacc3d8aa112edcc67f15f17b9b65fbb5

[Tassilo Horn]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU AUCTeX".

The branch, master has been updated
       via  76ca21ccacc3d8aa112edcc67f15f17b9b65fbb5 (commit)
      from  e39e0dab8cf59cc7574ac8537a82f70ccc57e0d0 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
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.

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)

-----------------------------------------------------------------------

Summary of changes:
 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(-)


hooks/post-receive
-- 
GNU AUCTeX