[Emacs-diffs] /srv/bzr/emacs/trunk r107296: Docstring and manual updates for completion-at-point-functions.

[Chong Yidong]

------------------------------------------------------------
revno: 107296
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-15 21:45:02 +0800
message:
  Docstring and manual updates for completion-at-point-functions.
  
  * doc/lispref/minibuf.texi (Basic Completion): Define "completion table".
  Move completion-in-region to Completion in Buffers node.
  (Completion Commands): Use "completion table" terminology.
  (Completion in Buffers): New node.
  
  * doc/lispref/modes.texi (Hooks): add-hook can be used for abnormal hooks too.
  (Setting Hooks): Update minor mode usage example.
  (Major Mode Conventions): Note that completion-at-point-functions
  should be altered locally.  Add xref to Completion in Buffers.
  
  * lisp/minibuffer.el (completion-at-point-functions): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/minibuf.texi
  doc/lispref/modes.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  lisp/ChangeLog
  lisp/minibuffer.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-15 08:48:45 +0000
+++ b/doc/lispref/ChangeLog     2012-02-15 13:45:02 +0000
@@ -1,3 +1,15 @@
+2012-02-15  Chong Yidong  <address@hidden>
+
+       * minibuf.texi (Basic Completion): Define "completion table".
+       Move completion-in-region to Completion in Buffers node.
+       (Completion Commands): Use "completion table" terminology.
+       (Completion in Buffers): New node.
+
+       * modes.texi (Hooks): add-hook can be used for abnormal hooks too.
+       (Setting Hooks): Update minor mode usage example.
+       (Major Mode Conventions): Note that completion-at-point-functions
+       should be altered locally.  Add xref to Completion in Buffers.
+
 2012-02-15  Glenn Morris  <address@hidden>
 
        * processes.texi (Network): Document open-network-stream :parameters.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-02-11 06:17:22 +0000
+++ b/doc/lispref/elisp.texi    2012-02-15 13:45:02 +0000
@@ -654,6 +654,7 @@
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * 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-04 01:23:09 +0000
+++ b/doc/lispref/minibuf.texi  2012-02-15 13:45:02 +0000
@@ -633,6 +633,7 @@
                              shell commands.
 * Completion Styles::      Specifying rules for performing completion.
 * Programmed Completion::  Writing your own completion-function.
+* Completion in Buffers::  Completing text in ordinary buffers.
 @end menu
 
 @node Basic Completion
@@ -644,10 +645,12 @@
 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
-completions of @var{string} in @var{collection}.  The value of
address@hidden must be a list of strings, an alist whose keys are
-strings or symbols, an obarray, a hash table, or a completion function
-(@pxref{Programmed Completion}).
+completions of @var{string} in @var{collection}.
+
address@hidden completion table
+The @var{collection} argument is called the @dfn{completion table}.
+Its value must be a list of strings, an alist whose keys are strings
+or symbols, an obarray, a hash table, or a completion function.
 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}.  If no permissible
@@ -678,13 +681,13 @@
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
 
-You can also use a function as @var{collection}.
-Then the function is solely responsible for performing completion;
address@hidden returns whatever this function returns.  The
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil} (the reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case).  @xref{Programmed Completion}.
+You can also use a function as @var{collection}.  Then the function is
+solely responsible for performing completion; @code{try-completion}
+returns whatever this function returns.  The function is called with
+three arguments: @var{string}, @var{predicate} and @code{nil} (the
+reason for the third argument is so that the same function can be used
+in @code{all-completions} and do the appropriate thing in either
+case).  @xref{Programmed Completion}.
 
 If the argument @var{predicate} is address@hidden, then it must be a
 function of one argument, unless @var{collection} is a hash table, in
@@ -862,30 +865,13 @@
 It is done by calling @var{fun} with no arguments.  The
 value @var{fun} returns becomes the permanent value of @var{var}.
 
-Here is an example of use:
+Here is a usage example:
 
 @smallexample
 (defvar foo (lazy-completion-table foo make-my-alist))
 @end smallexample
 @end defmac
 
-The function @code{completion-in-region} provides a convenient way to
-perform completion on an arbitrary stretch of text in an Emacs buffer:
-
address@hidden completion-in-region start end collection &optional predicate
-This function completes the text in the current buffer between the
-positions @var{start} and @var{end}, using @var{collection}.  The
-argument @var{collection} has the same meaning as in
address@hidden (@pxref{Basic Completion}).
-
-This function inserts the completion text directly into the current
-buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
-Completion}), it does not activate the minibuffer.
-
-For this function to work, point must be somewhere between @var{start}
-and @var{end}.
address@hidden defun
-
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion
@@ -899,13 +885,14 @@
 providing completion.  It activates the minibuffer with prompt
 @var{prompt}, which must be a string.
 
-The actual completion is done by passing @var{collection} and
address@hidden to the function @code{try-completion} (@pxref{Basic
-Completion}).  This happens in certain commands bound in the local
-keymaps used for completion.  Some of these commands also call
address@hidden  Thus, if @var{predicate} is address@hidden,
-it should be compatible with @var{collection} and
address@hidden  @xref{Definition of test-completion}.
+The actual completion is done by passing the completion table
address@hidden and the completion predicate @var{predicate} to the
+function @code{try-completion} (@pxref{Basic Completion}).  This
+happens in certain commands bound in the local keymaps used for
+completion.  Some of these commands also call @code{test-completion}.
+Thus, if @var{predicate} is address@hidden, it should be compatible
+with @var{collection} and @code{completion-ignore-case}.
address@hidden of test-completion}.
 
 The value of the optional argument @var{require-match} determines how
 the user may exit the minibuffer:
@@ -1005,10 +992,11 @@
 in the minibuffer to do completion.
 
 @defvar minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer.  This is the global variable that contains what
+The value of this variable is the completion table used for completion
+in the minibuffer.  This is the global variable that contains what
 @code{completing-read} passes to @code{try-completion}.  It is used by
-minibuffer completion commands such as @code{minibuffer-complete-word}.
+minibuffer completion commands such as
address@hidden
 @end defvar
 
 @defvar minibuffer-completion-predicate
@@ -1717,6 +1705,87 @@
 (@pxref{Completion Commands}).
 @end defvar
 
address@hidden Completion in Buffers
address@hidden Completion in Ordinary Buffers
address@hidden inline completion
+
address@hidden completion-at-point
+  Although completion is usually done in the minibuffer, the
+completion facility can also be used on the text in ordinary Emacs
+buffers.  In many major modes, in-buffer completion is performed by
+the @kbd{C-M-i} or @address@hidden command, bound to
address@hidden  @xref{Symbol Completion,,, emacs, The GNU
+Emacs Manual}.  This command uses the abnormal hook variable
address@hidden:
+
address@hidden completion-at-point-functions
+The value of this abnormal hook should be a list of functions, which
+are used to compute a completion table for completing the text at
+point.  It can be used by major modes to provide mode-specific
+completion tables (@pxref{Major Mode Conventions}).
+
+When the command @code{completion-at-point} runs, it calls the
+functions in the list one by one, without any argument.  Each function
+should return @code{nil} if it is unable to produce a completion table
+for the text at point.  Otherwise it should return a list of the form
+
address@hidden
+(@var{start} @var{end} @var{collection} . @var{props})
address@hidden example
+
address@hidden
address@hidden and @var{end} delimit the text to complete (which should
+enclose point).  @var{collection} is a completion table for completing
+that text, in a form suitable for passing as the second argument to
address@hidden (@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
+additional information; the following optional properties are
+recognized:
+
address@hidden @code
address@hidden :predicate
+The value should be a predicate that completion candidates need to
+satisfy.
+
address@hidden :exclusive
+If the value is @code{no}, then if the completion table fails to match
+the text at point, then @code{completion-at-point} moves on to the
+next function in @code{completion-at-point-functions} instead of
+reporting a completion failure.
address@hidden table
+
+A function in @code{completion-at-point-functions} may also return a
+function.  In that case, that returned function is called, with no
+argument, and it is entirely responsible for performing the
+completion.  We discourage this usage; it is intended to help convert
+old code to using @code{completion-at-point}.
+
+The first function in @code{completion-at-point-functions} to return a
address@hidden value is used by @code{completion-at-point}.  The
+remaining functions are not called.  The exception to this is when
+there is a @code{:exclusive} specification, as described above.
address@hidden defvar
+
+  The following function provides a convenient way to perform
+completion on an arbitrary stretch of text in an Emacs buffer:
+
address@hidden completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}.  The
+argument @var{collection} has the same meaning as in
address@hidden (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
address@hidden defun
+
+
 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-02-10 02:33:01 +0000
+++ b/doc/lispref/modes.texi    2012-02-15 13:45:02 +0000
@@ -48,17 +48,16 @@
 possible, so that you can use them in a uniform way.
 
   Every major mode command is supposed to run a normal hook called the
address@hidden hook} as the one of the last steps of initialization.  This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the buffer-local variable assignments already made by the
-mode.  Most minor mode functions also run a mode hook at the end.  But
-hooks are used in other contexts too.  For example, the hook
address@hidden runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
address@hidden hook} as one of the last steps of initialization.  This makes
+it easy for a user to customize the behavior of the mode, by overriding
+the buffer-local variable assignments already made by the mode.  Most
+minor mode functions also run a mode hook at the end.  But hooks are
+used in other contexts too.  For example, the hook @code{suspend-hook}
+runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
 
-  The recommended way to add a hook function to a normal hook is by
-calling @code{add-hook} (see below).  The hook functions may be any of
-the valid kinds of functions that @code{funcall} accepts (@pxref{What
+  The recommended way to add a hook function to a hook is by calling
address@hidden (@pxref{Setting Hooks}).  The hook functions may be any
+of the valid kinds of functions that @code{funcall} accepts (@pxref{What
 Is a Function}).  Most normal hook variables are initially void;
 @code{add-hook} knows how to deal with this.  You can add hooks either
 globally or buffer-locally with @code{add-hook}.
@@ -178,7 +177,7 @@
 in Lisp Interaction mode:
 
 @example
-(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
 @end example
 
 @defun add-hook hook function &optional append local
@@ -202,13 +201,13 @@
 changing major modes) won't delete it from the hook variable's local
 value.
 
-It is best to design your hook functions so that the order in which
-they are executed does not matter.  Any dependence on the order is
-asking for trouble.  However, the order is predictable: normally,
address@hidden goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call).  If the
-optional argument @var{append} is address@hidden, the new hook
-function goes at the end of the hook list and will be executed last.
+For a normal hook, hook functions should be designed so that the order
+in which they are executed does not matter.  Any dependence on the order
+is asking for trouble.  However, the order is predictable: normally,
address@hidden goes at the front of the hook list, so it is executed
+first (barring another @code{add-hook} call).  If the optional argument
address@hidden is address@hidden, the new hook function goes at the end of
+the hook list and is executed last.
 
 @code{add-hook} can handle the cases where @var{hook} is void or its
 value is a single function; it sets or changes the value to a list of
@@ -302,8 +301,8 @@
 
   If you use the @code{define-derived-mode} macro, it will take care of
 many of these conventions automatically.  @xref{Derived Modes}.  Note
-also that fundamental mode is an exception to many of these conventions,
-because its definition is to present the global state of Emacs.
+also that Fundamental mode is an exception to many of these conventions,
+because it represents the default state of Emacs.
 
   The following list of conventions is only partial.  Each major mode
 should aim for consistency in general with other Emacs major modes, as
@@ -460,8 +459,9 @@
 this mode.
 
 @item
-The mode can specify how to complete various keywords by adding
-to the special hook @code{completion-at-point-functions}.
+The mode can specify how to complete various keywords by adding one or
+more buffer-local entries to the special hook
address@hidden  @xref{Completion in Buffers}.
 
 @item
 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
@@ -555,16 +555,15 @@
 @cindex mode loading
 The top-level forms in the file defining the mode should be written so
 that they may be evaluated more than once without adverse consequences.
-Even if you never load the file more than once, someone else will.
 @end itemize
 
 @node Auto Major Mode
 @subsection How Emacs Chooses a Major Mode
 @cindex major mode, automatic selection
 
-  Based on information in the file name or in the file itself, Emacs
-automatically selects a major mode for the new buffer when a file is
-visited.  It also processes local variables specified in the file text.
+  When Emacs visits a file, it automatically selects a major mode for
+the buffer based on information in the file name or in the file itself.
+It also processes local variables specified in the file text.
 
 @deffn Command normal-mode &optional find-file
 This function establishes the proper major mode and buffer-local variable

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-02-11 06:17:22 +0000
+++ b/doc/lispref/vol1.texi     2012-02-15 13:45:02 +0000
@@ -675,6 +675,7 @@
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * 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-02-11 06:17:22 +0000
+++ b/doc/lispref/vol2.texi     2012-02-15 13:45:02 +0000
@@ -674,6 +674,7 @@
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * Programmed Completion::   Writing your own completion-function.
+* Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-15 08:00:23 +0000
+++ b/lisp/ChangeLog    2012-02-15 13:45:02 +0000
@@ -5,6 +5,8 @@
 
 2012-02-15  Chong Yidong  <address@hidden>
 
+       * minibuffer.el (completion-at-point-functions): Doc fix.
+
        * custom.el (defcustom): Doc fix; note use of defvar.
 
 2012-02-15  Glenn Morris  <address@hidden>

=== modified file 'lisp/minibuffer.el'
--- a/lisp/minibuffer.el        2012-02-13 22:49:16 +0000
+++ b/lisp/minibuffer.el        2012-02-15 13:45:02 +0000
@@ -1550,16 +1550,16 @@
 Each function on this hook is called in turns without any argument and should
 return either nil to mean that it is not applicable at point,
 or a function of no argument to perform completion (discouraged),
-or a list of the form (START END COLLECTION &rest PROPS) where
+or a list of the form (START END COLLECTION . PROPS) where
  START and END delimit the entity to complete and should include point,
  COLLECTION is the completion table to use to complete it, and
  PROPS is a property list for additional information.
 Currently supported properties are all the properties that can appear in
 `completion-extra-properties' plus:
  `:predicate'  a predicate that completion candidates need to satisfy.
- `:exclusive'  If `no', means that if the completion data does not match the
-   text at point failure, then instead of reporting a completion failure,
-   the completion should try the next completion function.")
+ `:exclusive'  If `no', means that if the completion table fails to
+   match the text at point, then instead of reporting a completion
+   failure, the completion should try the next completion function.")
 
 (defvar completion--capf-misbehave-funs nil
   "List of functions found on `completion-at-point-functions' that misbehave.