[AUCTeX-diffs] GNU AUCTeX branch, master, updated. 3684fdeb688347e1656cd922d2a658bff704016f

[Ikumi Keita]

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  3684fdeb688347e1656cd922d2a658bff704016f (commit)
       via  ec9362d5fb7140ffbd266e80c9c039bbe7bb9120 (commit)
      from  f72f849368817f91b33929f96a033ab788ab608e (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 3684fdeb688347e1656cd922d2a658bff704016f
Author: Ikumi Keita <ikumi@ikumi.que.jp>
Date:   Thu Sep 23 02:11:21 2021 +0900

    Explain how to support option completion
    
    * doc/auctex.texi (Adding Other): Add explanation for style file
    authors: How to provide support for completion of optional arguments
    for \usepackage and \documentclass.

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 5f8df63..3a9ae01 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -5610,6 +5610,8 @@ Expert environments are completed depending on 
@code{TeX-complete-expert-command
 @cindex Bibliographies, adding
 @cindex Examining package/class options
 @cindex package/class options, Examining
+@cindex Adding support for completion of package/class options
+@cindex support for completion of package/class options, Adding
 @cindex Viewer predicates
 @cindex Defining bibliographies in style hooks
 @cindex Adding labels
@@ -5633,10 +5635,10 @@ Add each @var{bibliography} to list of loaded 
bibliographies.
 Add each @var{label} to the list of known labels.
 @end defun
 
-@subsubsection Examining package/class options
+@subsubsection Examining Package/Class Options
 
 In @LaTeX{} documents, style hooks can find the package names and those
-options given as optional argument(s) of @code{\usepackage} in
+options given as optional argument(s) of @samp{\usepackage} in
 @code{LaTeX-provided-package-options}.
 
 @defvar LaTeX-provided-package-options
@@ -5685,6 +5687,61 @@ first found class option matching @var{regexp}, or nil 
if not found.
 These functions are also useful to implement customized predicate(s) in
 @code{TeX-view-predicate-list}.  @xref{Starting Viewers}.
 
+@subsubsection Adding Support for Option Completion
+When the user inserts @samp{\usepackage} by @kbd{C-c C-m}, @AUCTeX{} asks
+for the optional arguments after the package name is given.  The style
+file of that package can provide completion support for the optional
+arguments.
+
+@defvar LaTeX-@var{packagename}-package-options
+List of optional arguments available for the package.
+@end defvar
+
+Here is an excerption from @samp{acronym.el}:
+@lisp
+(defvar LaTeX-acronym-package-options
+  '("footnote" "nohyperlinks" "printonlyused" "withpage" "smaller" "dua" 
"nolist")
+  "Package options for the acronym package.")
+@end lisp
+
+When the package accepts key-value style optional arguments, more
+sophisticated completion support is needed.  The package style file can
+provide dynamic completion support by custom elisp function.
+
+@defun LaTeX-@var{packagename}-package-options
+This function should ask the user for optional arguments and return them
+as a string, instead of built-in option query facility.  When this function
+is defined, @AUCTeX{} calls it with no argument.
+@end defun
+
+Here is an excerption from @samp{acro.el}:
+@lisp
+(defun LaTeX-acro-package-options ()
+  "Prompt for package options for the acro package."
+  (TeX-read-key-val t LaTeX-acro-package-options-list))
+@end lisp
+
+As you can see in the above example, a utility function
+@code{TeX-read-key-val} is available to read key-value pair(s) from users.
+
+Note that @code{defvar} or @code{defun} of
+@code{LaTeX-@var{packagename}-package-options} should be at the top level
+of the style file and not inside the style hook, because the style hook is
+not yet called when the user inputs the optional arguments in response to
+@kbd{C-c C-m}.
+
+There are similar facilities for class options.  When the user inserts
+@samp{\documentclass} by @kbd{C-c C-e}, the respective class style file
+can provide completion support for the optional arguments.
+
+@defvar LaTeX-@var{classname}-class-options
+List of optional arguments available for the class.
+@end defvar
+
+@defun LaTeX-@var{classname}-class-options
+Which see.
+@end defun
+
 @node Hacking the Parser
 @subsection Automatic Extraction of New Things
 @cindex Parsing new macros

commit ec9362d5fb7140ffbd266e80c9c039bbe7bb9120
Author: Ikumi Keita <ikumi@ikumi.que.jp>
Date:   Thu Sep 23 00:23:58 2021 +0900

    ; * doc/todo.texi (Mid-term Goals): Fix spacing.

diff --git a/doc/todo.texi b/doc/todo.texi
index 3c0c13f..5172e54 100644
--- a/doc/todo.texi
+++ b/doc/todo.texi
@@ -61,14 +61,14 @@ using Ref@TeX{}.
 
 @item Fix remove-style feature
 
-Currently @code{TeX-remove-style} implementation isn't good. It is
-common practice that major mode functions directly add macros and
-environments via @code{TeX-add-symbols} and
-@code{LaTeX-add-environments}, but those macros and environments are
-lost once @code{TeX-remove-style} runs. It is necessary to run major
-mode function, by e.g.@: @code{normal-mode}, again to recover them, but
-that makes no point in running @code{TeX-remove-style} itself because
-major mode function kills all buffer-local variables.
+Currently @code{TeX-remove-style} implementation isn't good.  It is common
+practice that major mode functions directly add macros and environments
+via @code{TeX-add-symbols} and @code{LaTeX-add-environments}, but those
+macros and environments are lost once @code{TeX-remove-style} runs.  It is
+necessary to run major mode function, by e.g.@: @code{normal-mode}, again
+to recover them, but that makes no point in running
+@code{TeX-remove-style} itself because major mode function kills all
+buffer-local variables.
 
 As of @AUCTeX{} 12.3, @code{TeX-remove-style} is no longer used by any
 other codes.

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

Summary of changes:
 doc/auctex.texi | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 doc/todo.texi   | 16 +++++++--------
 2 files changed, 67 insertions(+), 10 deletions(-)


hooks/post-receive
-- 
GNU AUCTeX