[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] 191/299: Distinguish common and advanced macros/envs.
From: |
Stefan Monnier |
Subject: |
[elpa] 191/299: Distinguish common and advanced macros/envs. |
Date: |
Sun, 02 Nov 2014 03:11:22 +0000 |
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
- [elpa] 185/299: Add completion for ProvidesPackage, ProvidesClass, and ProvidesFile., (continued)
- [elpa] 185/299: Add completion for ProvidesPackage, ProvidesClass, and ProvidesFile., Stefan Monnier, 2014/11/01
- [elpa] 198/299: Declare expert macros and envs in biblatex style file., Stefan Monnier, 2014/11/01
- [elpa] 194/299: Distinguish normal and expert macros/envs., Stefan Monnier, 2014/11/01
- [elpa] 196/299: * bib-cite.el (bib-highlight-mouse): Change regexp to cope with multiple optional arguments of a macro., Stefan Monnier, 2014/11/01
- [elpa] 192/299: Revert "Distinguish common and advanced macros/envs.", Stefan Monnier, 2014/11/01
- [elpa] 197/299: Fix C-x ` (next-error) for compile commands., Stefan Monnier, 2014/11/01
- [elpa] 200/299: Fix of the fix, my fault., Stefan Monnier, 2014/11/01
- [elpa] 195/299: Better signature of expert declaration functions., Stefan Monnier, 2014/11/01
- [elpa] 204/299: Revert "Skip comment or file in parens in output.", Stefan Monnier, 2014/11/01
- [elpa] 201/299: Disable electric-pair-mode., Stefan Monnier, 2014/11/01
- [elpa] 191/299: Distinguish common and advanced macros/envs.,
Stefan Monnier <=
- [elpa] 207/299: Add font name completion in fontspec.el., Stefan Monnier, 2014/11/01
- [elpa] 202/299: Disable electric-pair-mode conditionally., Stefan Monnier, 2014/11/01
- [elpa] 205/299: Handle package messages with parenthesized text., Stefan Monnier, 2014/11/01
- [elpa] 208/299: Use TeX-electric-math in LaTeX-math-insert/cal., Stefan Monnier, 2014/11/01
- [elpa] 199/299: Fix bindings of narrowing functions., Stefan Monnier, 2014/11/01
- [elpa] 209/299: Fix a bug with reftex where tex-info and LaTeX interferred., Stefan Monnier, 2014/11/01
- [elpa] 206/299: New style files and a fix to imakeidx.el., Stefan Monnier, 2014/11/01
- [elpa] 203/299: Skip comment or file in parens in output., Stefan Monnier, 2014/11/01
- [elpa] 211/299: Adapt style/babel.el to babel 3.9., Stefan Monnier, 2014/11/01
- [elpa] 210/299: Make search for \begin and \end case sensitive., Stefan Monnier, 2014/11/01