[elpa] 191/299: Distinguish common and advanced macros/envs.

[Stefan Monnier]

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

commit f8a3a8bdd4aae28d302b5c04fa602584a7406f4c
Author: Tassilo Horn <address@hidden>
Date:   Thu Nov 7 20:37:25 2013 +0100

    Distinguish common and advanced macros/envs.
    
    * tex.el (TeX-add-advanced-macros/envs): New defcustom.
    (TeX-add-advanced-macros/envs-p): New function.
    
    * doc/auctex.texi: Document addition of common vs. advanced macros
    and environments both for users and style file authors.
    
    * doc/changes.texi: Give a hint to the above.
---
 ChangeLog        |   10 ++++++
 doc/auctex.texi  |   81 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/changes.texi |   11 +++++++
 latex.el         |    5 +++
 tex.el           |   40 ++++++++++++++++++++++++++
 5 files changed, 146 insertions(+), 1 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 945802c..5b2dedf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2013-11-07  Tassilo Horn  <address@hidden>
+
+       * tex.el (TeX-add-advanced-macros/envs): New defcustom.
+       (TeX-add-advanced-macros/envs-p): New function.
+
+       * doc/auctex.texi: Document addition of common vs. advanced macros
+       and environments both for users and style file authors.
+
+       * doc/changes.texi: Give a hint to the above.
+
 2013-11-05  Mos� Giordano  <address@hidden>
 
        * doc/auctex.texi (Folding): Document `TeX-fold-auto' and
diff --git a/doc/auctex.texi b/doc/auctex.texi
index 3cf7dcb..e6deb84 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -1230,7 +1230,22 @@ use its value to decided what to do, whatever the value 
of the variable
 
 Completions work because @AUCTeX{} can analyze @TeX{} files, and store
 symbols in Emacs Lisp files for later retrieval.  @xref{Automatic}, for
-more information.
+more information.  Additionally, @AUCTeX{} comes with a library of
+handwritten style files for various popular @LaTeX{} packages that add
+macros and environments for completion, @xref{Style Files}.  Many
+packages provide a small set of macros/environments that are likely to
+be used by most users.  But often they also provide more advanced macros
+that allow expert users to twiddle and fine-tune the behaviour of a
+package.  The following user option determines if these style files
+should only register the commonly used or also the advanced macros and
+environments.
+
address@hidden TeX-add-advanced-macros/envs
+If nil (the default), only register commonly used macros and
+environments.  If t, also register all advanced macros/environments.
+Else, it should be a list of package names from which advanced macros
+and environments should be registered.
address@hidden defopt
 
 @cindex \cite, completion of
 @cindex address@hidden, completion
@@ -1250,6 +1265,7 @@ the address@hidden files have been saved at least once 
after you enabled
 automatic parsing on save, and that the basename of the address@hidden file
 does not conflict with the basename of one of @TeX{} files.
 
+
 @node Marking
 @section Marking Environments, Sections, or Texinfo Nodes
 
@@ -4052,6 +4068,7 @@ directories instead of @file{auto} directories.
 * Simple Style::                A Simple Style File
 * Adding Macros::               Adding Support for Macros
 * Adding Environments::         Adding Support for Environments
+* Common vs. advanced::         Common versus Advanced Macros and Environments
 * Adding Other::                Adding Other Information
 * Hacking the Parser::          Automatic Extraction of New Things
 @end menu
@@ -4507,6 +4524,68 @@ an optional argument of the @samp{lstlisting} 
environment:
 @end lisp
 @end ftable
 
address@hidden Common vs. advanced
address@hidden Adding Common versus Advanced Macros and Environments
address@hidden Common vs. advanced macros
address@hidden Common vs. advanced environments
address@hidden Macros, adding
address@hidden Environments, adding
address@hidden Defining macros in style hooks
address@hidden Defining environments in style hooks
+
+Many @LaTeX{} packages define a small set of macros and environments
+that are likely to be used by anyone using that package.  But
+oftentimes, they also define many advanced macros or environments that
+allow expert users to twiddle with and fine-tune the package's behavior.
+
+When writing an @AUCTeX{} style file for a package, it makes sense to
+try to distinguish those user-level, common commands from those that are
+not interesting for most users.  Then users can configure the following
+option to enable/disable advanced commands, or to enable them only for a
+specific set of packages.
+
address@hidden TeX-add-advanced-macros/envs
+If nil (the default), only add commonly used macros and environments.
+If t, also add all advanced macros/environments of all used packages.
+Else, it should be a list of package names from which advanced macros
+and environments should be registered.
address@hidden defopt
+
+In order to enable that feature, make your style file add the advanced
+macros and environments only if the following predicate returns non-nil
+when given the name of your style.
+
address@hidden TeX-add-advanced-macros/envs-p @var{style}
+Return non-nil if the advanced macros and environments of @var{style}
+should be added.
address@hidden defun
+
+For example, assume you write a style file for a hypothetical @LaTeX{}
+package @code{fooquux}.  That package provides the commonly used macro
address@hidden, and the environment @code{quux}.  Furthermore, it provides
+the @code{\bar} macro and the @code{fubar} environment, however, those
+are only useful if one needs to fiddle with details, and as such are
+rarely used.  In that case, your style file should go like this:
+
address@hidden
+(TeX-add-style-hook
+ "foobarquux"
+ (lambda ()
+   ;; Add common macros and environments
+   (TeX-add-symbols '("foo" ...))
+   (LaTeX-add-environments '("quux" ...))
+   ;; Also add the advanced commands if the user wants to
+   (when (TeX-add-advanced-macros/envs-p "foobarquux")
+     (TeX-add-symbols '("bar" ...))
+     (LaTeX-add-environments '("fubar" ...)))))
address@hidden lisp
+
+The distinction of what macro or environment is common and what is
+advanced is a pretty subjective issue, of course.  As a general rule of
+thumb, if the package's documentation has a usage, tutorial, or overview
+section, then the macros and environments discussed in there are
+probably the commonly used ones, the rest being advanced.
+
 @node Adding Other
 @subsection Adding Other Information
 @cindex Adding bibliographies
diff --git a/doc/changes.texi b/doc/changes.texi
index 949b2e9..4127384 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -10,6 +10,17 @@
 @heading News in 11.88
 
 @itemize @bullet
+
address@hidden
+Users can now define if style files should add only commonly used macros
+and environments to @AUCTeX{}'s completion machinery, or if advanced,
+rarely used commands are added, too.  This can be configured using the
+new configure option @code{TeX-add-advanced-macros/envs}.
+
+Style file authors are encouraged to distinguish common from advanced
+macros/environments, and add the latter only if the new predicate
address@hidden/envs-p} returns non-nil.
+
 @item
 Management of @LaTeX{} package options in the parser was improved.  You
 might need to reparse your documents, especially if you loaded the
diff --git a/latex.el b/latex.el
index 095a83c..5505fe8 100644
--- a/latex.el
+++ b/latex.el
@@ -6124,4 +6124,9 @@ i.e. you do _not_ have to cater for this yourself by 
adding \\\\' or $."
 
 (provide 'latex)
 
+
+;; Local Variables:
+;; outline-regexp: "\\(;;\\)\\(;+\\)"
+;; End:
+
 ;;; latex.el ends here
diff --git a/tex.el b/tex.el
index 17c8a4f..a3c35d8 100644
--- a/tex.el
+++ b/tex.el
@@ -2586,6 +2586,45 @@ Or alternatively:
 
 (make-variable-buffer-local 'TeX-default-macro)
 
+(defcustom TeX-add-advanced-macros/envs nil
+  "Determines if advanced macros/environments should be added.
+
+When you use some LaTeX package or input some TeX file, AUCTeX
+runs the style file of that package.  AUCTeX comes with a library
+of style files for popular packages like graphicx, href, or
+beamer.  These style files make AUCTeX aware of the macros and
+environments that are provided by a package.  This information is
+used by AUCTeX's syntax highlighting and macro/environment
+completion.
+
+Many packages provide a small set of macros/environments that are
+likely to be used by most users.  But often they also provide
+more advanced macros that allow expert users to twiddle and
+fine-tune the behaviour of a package.
+
+By default, AUCTeX's style files do not add those advanced
+commands in order to keep the macro and environment completion
+slim and discoverable.  Using this variable, it is possible also
+add advanced commands, either of all used packages or of only
+some used packages.
+
+  - nil                      Do not add advanced commands (default)
+  - (\"href\" \"graphicx\")  Register only the advanced commands
+                             of the href and graphicx packages.
+  - t                        Register"
+  :group 'TeX-macro
+  :type '(choice (const  :tag "Of all used packages" t)
+                (repeat :tag "Only of some packages" string)))
+
+(defun TeX-add-advanced-macros/envs-p (style)
+  "Return non-nil if advanced macro/envs of STYLE should be added."
+  (cond
+   ((eq t TeX-add-advanced-macros/envs) t)
+   ((listp TeX-add-advanced-macros/envs)
+    (member style TeX-add-advanced-macros/envs))
+   (t (error "TeX-add-advanced-macros/envs must be nil/t/list of strings but 
was %s"
+            TeX-add-advanced-macros/envs))))
+
 (defcustom TeX-insert-braces t
   "*If non-nil, append a empty pair of braces after inserting a macro.
 
@@ -5809,6 +5848,7 @@ Supports restriction to a region where the XEmacs version 
doesn't."
 
 ;; Local Variables:
 ;; coding: iso-8859-1
+;; outline-regexp: "\\(;;\\)\\(;+\\)"
 ;; End:
 
 ;;; tex.el ends here