[elpa] externals/auctex 3684fde 17/71: Explain how to support option completion

[Tassilo Horn]

branch: externals/auctex
commit 3684fdeb688347e1656cd922d2a658bff704016f
Author: Ikumi Keita <ikumi@ikumi.que.jp>
Commit: Ikumi Keita <ikumi@ikumi.que.jp>

    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.
---
 doc/auctex.texi | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 59 insertions(+), 2 deletions(-)

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