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.

8 files changed, 155 insertions, 70 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 296b4e90b4b..1e369f3b627 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,15 @@
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * 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  <rgm@gnu.org>
 
         * processes.texi (Network): Document open-network-stream :parameters.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 42c3613dd0b..5dd8994f439 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -654,6 +654,7 @@ Completion
                               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
 
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index a71138f5268..1224d80fdf8 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -633,6 +633,7 @@ for reading certain kinds of names with completion.
                              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 @@ higher-level completion features that do use the minibuffer.
 
 @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
-@var{collection} 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}.
+
+@cindex 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 @@ Also, you cannot intern a given symbol in more than one obarray.
 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;
-@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}.
+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 non-@code{nil}, then it must be a
 function of one argument, unless @var{collection} is a hash table, in
@@ -862,30 +865,13 @@ proper value is done the first time you do completion using @var{var}.
 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:
-
-@defun 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
-@code{try-completion} (@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}.
-@end defun
-
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion
@@ -899,13 +885,14 @@ This function reads a string in the minibuffer, assisting the user by
 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
-@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 non-@code{nil},
-it should be compatible with @var{collection} and
-@code{completion-ignore-case}.  @xref{Definition of test-completion}.
+The actual completion is done by passing the completion table
+@var{collection} 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 non-@code{nil}, it should be compatible
+with @var{collection} and @code{completion-ignore-case}.
+@xref{Definition of test-completion}.
 
 The value of the optional argument @var{require-match} determines how
 the user may exit the minibuffer:
@@ -1005,10 +992,11 @@ They are described in the following section.
 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
+@code{minibuffer-complete-word}.
 @end defvar
 
 @defvar minibuffer-completion-predicate
@@ -1717,6 +1705,87 @@ 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
+
+@findex 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 @kbd{M-@key{TAB}} command, bound to
+@code{completion-at-point}.  @xref{Symbol Completion,,, emacs, The GNU
+Emacs Manual}.  This command uses the abnormal hook variable
+@code{completion-at-point-functions}:
+
+@defvar 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
+
+@example
+(@var{start} @var{end} @var{collection} . @var{props})
+@end example
+
+@noindent
+@var{start} 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
+@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
+additional information; the following optional properties are
+recognized:
+
+@table @code
+@item :predicate
+The value should be a predicate that completion candidates need to
+satisfy.
+
+@item :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.
+@end 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
+non-@code{nil} 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.
+@end defvar
+
+  The following function provides a convenient way to perform
+completion on an arbitrary stretch of text in an Emacs buffer:
+
+@defun 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
+@code{try-completion} (@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}.
+@end defun
+
+
 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 0b020bee0b0..94ae767586b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -48,17 +48,16 @@ you it is normal.  We try to make all hooks normal, as much as
 possible, so that you can use them in a uniform way.
 
   Every major mode command is supposed to run a normal hook called the
-@dfn{mode 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
-@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
+@dfn{mode 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 hook is by calling
+@code{add-hook} (@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 @@ calls @code{wrap-function} with arguments @code{fun} and @code{args}.
 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 @@ If @var{function} has a non-@code{nil} property
 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,
-@var{function} 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 non-@code{nil}, 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,
+@var{function} goes at the front of the hook list, so it is executed
+first (barring another @code{add-hook} call).  If the optional argument
+@var{append} is non-@code{nil}, 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 @@ initialization, function and variable names, and hooks.
 
   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 @@ The mode can specify a local value for
 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
+@code{completion-at-point-functions}.  @xref{Completion in Buffers}.
 
 @item
 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
@@ -555,16 +555,15 @@ In the comments that document the file, you should provide a sample
 @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
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index cc96726745f..dbab287b273 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -675,6 +675,7 @@ Completion
                               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
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 33246cb567d..38e2f1dc5e9 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -674,6 +674,7 @@ Completion
                               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
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index ccb1394e3d5..bdbe99d5452 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -5,6 +5,8 @@
 
 2012-02-15  Chong Yidong  <cyd@gnu.org>
 
+        * minibuffer.el (completion-at-point-functions): Doc fix.
+
         * custom.el (defcustom): Doc fix; note use of defvar.
 
 2012-02-15  Glenn Morris  <rgm@gnu.org>
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 611df1eb6d9..8564cc2009b 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1550,16 +1550,16 @@ the mode if ARG is omitted or nil."
 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.