[Emacs-diffs] /srv/bzr/emacs/trunk r107760: Document completion-extra-properties in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107760
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-04-04 17:19:32 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/minibuf.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/minibuffer.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-04 08:11:01 +0000
+++ b/doc/lispref/ChangeLog     2012-04-04 09:19:32 +0000
@@ -1,5 +1,11 @@
 2012-04-04  Chong Yidong  <address@hidden>
 
+       * 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.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-04-04 07:54:02 +0000
+++ b/doc/lispref/elisp.texi    2012-04-04 09:19:32 +0000
@@ -649,8 +649,8 @@
                               (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

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2012-02-15 13:45:02 +0000
+++ b/doc/lispref/minibuf.texi  2012-04-04 09:19:32 +0000
@@ -631,8 +631,8 @@
                              (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 @@
 @defun test-completion string collection &optional predicate
 @anchor{Definition of test-completion}
 This function returns address@hidden 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 @@
 
 If @var{predicate} is address@hidden, 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 address@hidden for it.
 
 Here is an example of using @code{read-file-name}:
@@ -1480,7 +1480,7 @@
 
 @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 address@hidden,
 @code{read-directory-name} constructs a substitute default by
@@ -1563,57 +1563,85 @@
 command and file names that are part of a shell command.
 @end defvar
 
address@hidden Completion Styles
address@hidden Completion Styles
address@hidden Completion Variables
address@hidden Completion Variables
+
+  Here are some variables which can be used to alter the default
+completion behavior.
+
 @cindex completion styles
-
-  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.
-
 @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}
address@hidden @var{all-completions})}.  Here, @var{name} is the
-name of the completion style (a symbol), which may be used in
address@hidden to refer to this style.
-
address@hidden is the function that does the completion, and
address@hidden is the function that lists the completions.
-These functions should accept four arguments: @var{string},
address@hidden, @var{predicate}, and @var{point}.  The @var{string},
address@hidden, and @var{predicate} arguments have the same meanings
-as in @code{try-completion} (@pxref{Basic Completion}), and the
address@hidden argument is the position of point within @var{string}.
-Each function should return a address@hidden 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
+
address@hidden
+(@var{name} @var{try-completion} @var{all-completions} @var{doc})
address@hidden example
+
address@hidden
+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;
address@hidden is the function that does the completion;
address@hidden is the function that lists the completions; and
address@hidden 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},
address@hidden, and @var{point}.  The @var{string}, @var{collection},
+and @var{predicate} arguments have the same meanings as in
address@hidden (@pxref{Basic Completion}), and the @var{point}
+argument is the position of point within @var{string}.  Each function
+should return a address@hidden value if it performed its job, and
address@hidden if it did not (e.g.@: if there is no way to complete
address@hidden 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
address@hidden and calls its @var{try-completion} function,
-and so on until one of the @var{try-completion} functions successfully
-performs completion and returns a address@hidden value.  A similar
-procedure is used for listing completions, via the
address@hidden functions.
address@hidden defvar
-
-  By default, @code{completion-styles-alist} contains five pre-defined
-completion styles: @code{basic}, a basic completion style;
address@hidden, 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
address@hidden, which completes acronyms and initialisms.
+Emacs moves to the next listed completion style and calls its
address@hidden function, and so on until one of the
address@hidden functions successfully performs completion and
+returns a address@hidden value.  A similar procedure is used for
+listing completions, via the @var{all-completions} functions.
+
address@hidden Styles,,, emacs, The GNU Emacs Manual}, for a
+description of the available completion styles.
address@hidden defvar
+
address@hidden 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:
+
address@hidden @code
address@hidden :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.
+
address@hidden :exit-function
+The value should be a function to run after performing completion.
+The function should accept two arguments, @var{string} and
address@hidden, where @var{string} is the text to which the field was
+completed and @var{status} indicates what kind of operation happened:
address@hidden if text is now complete, @code{sole} if the text
+cannot be further completed but completion is not finished, or
address@hidden if the text is a valid completion but may be further
+completed.
address@hidden table
address@hidden defvar
 
 @node Programmed Completion
 @subsection Programmed Completion
@@ -1640,47 +1668,41 @@
 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}.
-
address@hidden
-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.
address@hidden itemize
-
-  There are currently four methods, i.e. four flag values, one for
-each of the four different basic operations:
-
address@hidden @bullet
address@hidden
address@hidden 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
address@hidden
-
address@hidden
address@hidden specifies @code{all-completions}.  The completion function
+A predicate function with which to filter possible matches, or
address@hidden if none.  The function should call the predicate for each
+possible match, and ignore the match if the predicate returns
address@hidden
+
address@hidden
+A flag specifying the type of completion operation to perform.  This
+is one of the following four values:
+
address@hidden @code
address@hidden 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
address@hidden
+
address@hidden t
+This specifies an @code{all-completions} operation.  The function
 should return a list of all possible completions of the specified
 string.
 
address@hidden
address@hidden 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.
address@hidden 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.
 
address@hidden
address@hidden(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.
address@hidden (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.
address@hidden table
 @end itemize
 
 @defun completion-table-dynamic function
@@ -1692,19 +1714,6 @@
 and the interface for programmed completion functions.
 @end defun
 
address@hidden completion-annotate-function
-The value of this variable, if address@hidden, 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}).
address@hidden defvar
-
 @node Completion in Buffers
 @subsection Completion in Ordinary Buffers
 @cindex inline completion
@@ -1740,7 +1749,7 @@
 @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:
 

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-04-04 07:54:02 +0000
+++ b/doc/lispref/vol1.texi     2012-04-04 09:19:32 +0000
@@ -671,8 +671,8 @@
                               (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

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-04-04 07:54:02 +0000
+++ b/doc/lispref/vol2.texi     2012-04-04 09:19:32 +0000
@@ -670,8 +670,8 @@
                               (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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-04-04 07:54:02 +0000
+++ b/etc/NEWS  2012-04-04 09:19:32 +0000
@@ -1329,6 +1329,7 @@
 *** Functions on `completion-at-point-functions' can return any of the
 properties valid for `completion-extra-properties'.
 
++++
 *** `completion-annotate-function' is obsolete.
 
 *** New `metadata' method for completion tables.  The metadata thus returned

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-04-04 07:54:02 +0000
+++ b/lisp/ChangeLog    2012-04-04 09:19:32 +0000
@@ -1,5 +1,7 @@
 2012-04-04  Chong Yidong  <address@hidden>
 
+       * minibuffer.el (completion-extra-properties): Doc fix.
+
        * subr.el (delayed-warnings-hook): Doc fix.
 
 2012-04-04  Daiki Ueno  <address@hidden>

=== modified file 'lisp/minibuffer.el'
--- a/lisp/minibuffer.el        2012-03-12 04:10:59 +0000
+++ b/lisp/minibuffer.el        2012-04-04 09:19:32 +0000
@@ -1269,17 +1269,24 @@
 (defvar completion-extra-properties nil
   "Property list of extra properties of the current completion job.
 These include:
-`:annotation-function': Function to add annotations in the completions buffer.
-   The function takes a completion and should either return nil, or a string
-   that will be displayed next to the completion.  The function can access the
-   completion data via `minibuffer-completion-table' and related variables.
+
+`:annotation-function': Function to annotate the completions buffer.
+   The function must accept one argument, a completion string,
+   and return either nil or a string which is to be displayed
+   next to the completion (but which is not part of the
+   completion).  The function can access the completion data via
+   `minibuffer-completion-table' and related variables.
+
 `:exit-function': Function to run after completion is performed.
-   The function takes at least 2 parameters (STRING and STATUS) where STRING
-   is the text to which the field was completed and STATUS indicates what
-   kind of operation happened: if text is now complete it's `finished', if text
-   cannot be further completed but completion is not finished, it's `sole', if
-   text is a valid completion but may be further completed, it's `exact', and
-   other STATUSes may be added in the future.")
+
+   The function must accept two arguments, STRING and STATUS.
+   STRING is the text to which the field was completed, and
+   STATUS indicates what kind of operation happened:
+     `finished' - text is now complete
+     `sole'     - text cannot be further completed but
+                  completion is not finished
+     `exact'    - text is a valid completion but may be further
+                  completed.")
 
 (defvar completion-annotate-function
   nil