Document completion-extra-properties in Lisp manual.

* doc/lispref/minibuf.texi (Programmed Completion): Remove obsolete variable
completion-annotate-function.
(Completion Variables): Rename from Completion Styles.  Document
completion-extra-properties.  Document completion-styles-alist
change.

* lisp/minibuffer.el (completion-extra-properties): Doc fix.

5 files changed, 112 insertions, 97 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 89e740603f8..6385400572e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,11 @@
 2012-04-04  Chong Yidong  <cyd@gnu.org>
 
+        * minibuf.texi (Programmed Completion): Remove obsolete variable
+        completion-annotate-function.
+        (Completion Variables): Rename from Completion Styles.  Document
+        completion-extra-properties.  Document completion-styles-alist
+        change.
+
         * display.texi (Delayed Warnings): New node.
 
         * os.texi (Notifications): Copyedits.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 508b0251a7a..a87a7ff3fa2 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -649,8 +649,8 @@ Completion
                               (reading buffer name, file name, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
-* Completion Styles::       Specifying rules for performing completion.
-* Programmed Completion::   Writing your own completion-function.
+* Completion Variables::    Variables controlling completion behavior.
+* Programmed Completion::   Writing your own completion function.
 * Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 1224d80fdf8..0d7e2350bd7 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -631,8 +631,8 @@ for reading certain kinds of names with completion.
                              (reading buffer name, file name, etc.).
 * Reading File Names::     Using completion to read file names and
                              shell commands.
-* Completion Styles::      Specifying rules for performing completion.
-* Programmed Completion::  Writing your own completion-function.
+* Completion Variables::   Variables controlling completion behavior.
+* Programmed Completion::  Writing your own completion function.
 * Completion in Buffers::  Completing text in ordinary buffers.
 @end menu
 
@@ -795,7 +795,7 @@ example for @code{try-completion}:
 @defun test-completion string collection &optional predicate
 @anchor{Definition of test-completion}
 This function returns non-@code{nil} if @var{string} is a valid
-completion possibility specified by @var{collection} and
+completion alternative specified by @var{collection} and
 @var{predicate}.  The arguments are the same as in
 @code{try-completion}.  For instance, if @var{collection} is a list of
 strings, this is true if @var{string} appears in the list and
@@ -1429,7 +1429,7 @@ current buffer visit no file using @code{M-x set-visited-file-name}.
 
 If @var{predicate} is non-@code{nil}, it specifies a function of one
 argument that decides which file names are acceptable completion
-possibilities.  A file name is an acceptable value if @var{predicate}
+alternatives.  A file name is an acceptable value if @var{predicate}
 returns non-@code{nil} for it.
 
 Here is an example of using @code{read-file-name}:
@@ -1480,7 +1480,7 @@ when performing completion.
 
 @defun read-directory-name prompt &optional directory default require-match initial
 This function is like @code{read-file-name} but allows only directory
-names as completion possibilities.
+names as completion alternatives.
 
 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
 @code{read-directory-name} constructs a substitute default by
@@ -1563,57 +1563,85 @@ This keymap is used by @code{read-shell-command} for completing
 command and file names that are part of a shell command.
 @end defvar
 
-@node Completion Styles
-@subsection Completion Styles
-@cindex completion styles
+@node Completion Variables
+@subsection Completion Variables
 
-  A @dfn{completion style} is a set of rules for generating
-completions.  The user option @code{completion-styles} stores a list
-of completion styles, which are represented by symbols.
+  Here are some variables which can be used to alter the default
+completion behavior.
 
+@cindex completion styles
 @defopt completion-styles
-This is a list of completion style symbols to use for performing
-completion.  Each completion style in this list must be defined in
+The value of this variable is a list of completion styles to use for
+performing completion.  A @dfn{completion style} is a set of rules for
+generating completions.
+
+Each style listed in this variable must be one of those defined in
 @code{completion-styles-alist}.
 @end defopt
 
 @defvar completion-styles-alist
 This variable stores a list of available completion styles.  Each
-element in the list must have the form @samp{(@var{name}
-@var{try-completion} @var{all-completions})}.  Here, @var{name} is the
-name of the completion style (a symbol), which may be used in
-@code{completion-styles-alist} to refer to this style.
-
-@var{try-completion} is the function that does the completion, and
-@var{all-completions} is the function that lists the completions.
-These functions should accept four arguments: @var{string},
-@var{collection}, @var{predicate}, and @var{point}.  The @var{string},
-@var{collection}, and @var{predicate} arguments have the same meanings
-as in @code{try-completion} (@pxref{Basic Completion}), and the
-@var{point} argument is the position of point within @var{string}.
-Each function should return a non-@code{nil} value if it performed its
-job, and @code{nil} if it did not (e.g., if there is no way to
-complete @var{string} according to the completion style).
-
-When the user calls a completion command, such as
+element in the list has the form
+
+@example
+(@var{name} @var{try-completion} @var{all-completions} @var{doc})
+@end example
+
+@noindent
+Here, @var{name} is the name of the completion style (a symbol), which
+may be used in @code{completion-styles-alist} to refer to this style;
+@var{try-completion} is the function that does the completion;
+@var{all-completions} is the function that lists the completions; and
+@var{doc} is a string describing the completion style.
+
+The @var{try-completion} and @var{all-completions} functions should
+each accept four arguments: @var{string}, @var{collection},
+@var{predicate}, and @var{point}.  The @var{string}, @var{collection},
+and @var{predicate} arguments have the same meanings as in
+@code{try-completion} (@pxref{Basic Completion}), and the @var{point}
+argument is the position of point within @var{string}.  Each function
+should return a non-@code{nil} value if it performed its job, and
+@code{nil} if it did not (e.g.@: if there is no way to complete
+@var{string} according to the completion style).
+
+When the user calls a completion command like
 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
 for the first style listed in @code{completion-styles} and calls its
 @var{try-completion} function.  If this function returns @code{nil},
-Emacs moves to the next completion style listed in
-@code{completion-styles} and calls its @var{try-completion} function,
-and so on until one of the @var{try-completion} functions successfully
-performs completion and returns a non-@code{nil} value.  A similar
-procedure is used for listing completions, via the
-@var{all-completions} functions.
+Emacs moves to the next listed completion style and calls its
+@var{try-completion} function, and so on until one of the
+@var{try-completion} functions successfully performs completion and
+returns a non-@code{nil} value.  A similar procedure is used for
+listing completions, via the @var{all-completions} functions.
+
+@xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
+description of the available completion styles.
 @end defvar
 
-  By default, @code{completion-styles-alist} contains five pre-defined
-completion styles: @code{basic}, a basic completion style;
-@code{partial-completion}, which does partial completion (completing
-each word in the input separately); @code{emacs22}, which performs
-completion according to the rules used in Emacs 22; @code{emacs21},
-which performs completion according to the rules used in Emacs 21; and
-@code{initials}, which completes acronyms and initialisms.
+@defvar completion-extra-properties
+This variable is used to specify extra properties of the current
+completion command.  It is intended to be let-bound by specialized
+completion commands.  Its value should be a list of property and value
+pairs.  The following properties are supported:
+
+@table @code
+@item :annotation-function
+The value should be a function to add annotations in the completions
+buffer.  This function must accept one argument, a completion, and
+should either return @code{nil} or a string to be displayed next to
+the completion.
+
+@item :exit-function
+The value should be a function to run after performing completion.
+The function should accept two arguments, @var{string} and
+@var{status}, where @var{string} is the text to which the field was
+completed and @var{status} indicates what kind of operation happened:
+@code{finished} if text is now complete, @code{sole} if the text
+cannot be further completed but completion is not finished, or
+@code{exact} if the text is a valid completion but may be further
+completed.
+@end table
+@end defvar
 
 @node Programmed Completion
 @subsection Programmed Completion
@@ -1640,47 +1668,41 @@ the work.
 The string to be completed.
 
 @item
-The predicate function to filter possible matches, or @code{nil} if
-none.  Your function should call the predicate for each possible match,
-and ignore the possible match if the predicate returns @code{nil}.
+A predicate function with which to filter possible matches, or
+@code{nil} if none.  The function should call the predicate for each
+possible match, and ignore the match if the predicate returns
+@code{nil}.
 
 @item
-A flag specifying the type of operation.  The best way to think about
-it is that the function stands for an object (in the
-``object-oriented'' sense of the word), and this third argument
-specifies which method to run.
-@end itemize
+A flag specifying the type of completion operation to perform.  This
+is one of the following four values:
 
-  There are currently four methods, i.e. four flag values, one for
-each of the four different basic operations:
-
-@itemize @bullet
-@item
-@code{nil} specifies @code{try-completion}.  The completion function
-should return the completion of the specified string, or @code{t} if the
-string is a unique and exact match already, or @code{nil} if the string
-matches no possibility.
-
-If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function should return the string, not
-@code{t}.
-
-@item
-@code{t} specifies @code{all-completions}.  The completion function
+@table @code
+@item nil
+This specifies a @code{try-completion} operation.  The function should
+return @code{t} if the specified string is a unique and exact match;
+if there is more than one match, it should return the common substring
+of all matches (if the string is an exact match for one completion
+alternative but also matches other longer alternatives, the return
+value is the string); if there are no matches, it should return
+@code{nil}.
+
+@item t
+This specifies an @code{all-completions} operation.  The function
 should return a list of all possible completions of the specified
 string.
 
-@item
-@code{lambda} specifies @code{test-completion}.  The completion
-function should return @code{t} if the specified string is an exact
-match for some possibility; @code{nil} otherwise.
+@item lambda
+This specifies a @code{test-completion} operation.  The function
+should return @code{t} if the specified string is an exact match for
+some completion alternative; @code{nil} otherwise.
 
-@item
-@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}.
-The function should return a value of the form @code{(boundaries
-START . END)} where START is the position of the beginning boundary
-in the string to complete, and END is the position of the end boundary
-in SUFFIX.
+@item (boundaries . @var{suffix})
+This specifies a @code{completion-boundaries} operation.  The function
+should return @code{(boundaries START . END)}, where START is the
+position of the beginning boundary in the specified string, and END is
+the position of the end boundary in SUFFIX.
+@end table
 @end itemize
 
 @defun completion-table-dynamic function
@@ -1692,19 +1714,6 @@ possible completions of it.  You can think of
 and the interface for programmed completion functions.
 @end defun
 
-@defvar completion-annotate-function
-The value of this variable, if non-@code{nil}, should be a function
-for ``annotating'' the entries in the @samp{*Completions*} buffer.
-The function should accept a single argument, the completion string
-for an entry.  It should return an additional string to display next
-to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
-additional string is to be displayed.
-
-The function can determine the collection used for the current
-completion via the variable @code{minibuffer-completion-table}
-(@pxref{Completion Commands}).
-@end defvar
-
 @node Completion in Buffers
 @subsection Completion in Ordinary Buffers
 @cindex inline completion
@@ -1740,7 +1749,7 @@ that text, in a form suitable for passing as the second argument to
 @code{try-completion} (@pxref{Basic Completion}); completion
 alternatives will be generated from this completion table in the usual
 way, via the completion styles defined in @code{completion-styles}
-(@pxref{Completion Styles}).  @var{props} is a property list for
+(@pxref{Completion Variables}).  @var{props} is a property list for
 additional information; the following optional properties are
 recognized:
 
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 52681510a51..e1fe8ba3277 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -671,8 +671,8 @@ Completion
                               (reading buffer name, file name, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
-* Completion Styles::       Specifying rules for performing completion.
-* Programmed Completion::   Writing your own completion-function.
+* Completion Variables::    Variables controlling completion behavior.
+* Programmed Completion::   Writing your own completion function.
 * Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 3be2628f5e1..650d1672538 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -670,8 +670,8 @@ Completion
                               (reading buffer name, file name, etc.).
 * Reading File Names::      Using completion to read file names and
                               shell commands.
-* Completion Styles::       Specifying rules for performing completion.
-* Programmed Completion::   Writing your own completion-function.
+* Completion Variables::    Variables controlling completion behavior.
+* Programmed Completion::   Writing your own completion function.
 * Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop