diff doc/lispref/minibuf.texi @ 109689:ffde65bb1dd2

merge emacs-23

--- a/doc/lispref/minibuf.texi	Tue May 11 20:15:29 2010 +0900
+++ b/doc/lispref/minibuf.texi	Tue Jul 27 16:01:48 2010 +0900
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/minibuf
 @node Minibuffers, Command Loop, Read and Print, Top
@@ -22,13 +23,13 @@
 * Intro to Minibuffers::      Basic information about minibuffers.
 * Text from Minibuffer::      How to read a straight text string.
 * Object from Minibuffer::    How to read a Lisp object or expression.
-* Minibuffer History::	      Recording previous minibuffer inputs
-				so the user can reuse them.
+* Minibuffer History::        Recording previous minibuffer inputs
+                                so the user can reuse them.
 * Initial Input::             Specifying initial contents for the minibuffer.
 * Completion::                How to invoke and customize completion.
 * Yes-or-No Queries::         Asking a question with a simple answer.
-* Multiple Queries::	      Asking a series of similar questions.
-* Reading a Password::	      Reading a password from the terminal.
+* Multiple Queries::          Asking a series of similar questions.
+* Reading a Password::        Reading a password from the terminal.
 * Minibuffer Commands::       Commands used as key bindings in minibuffers.
 * Minibuffer Contents::       How such commands access the minibuffer text.
 * Minibuffer Windows::        Operating on the special minibuffer windows.
@@ -814,6 +815,25 @@
 it returns, @code{test-completion} returns in turn.
 @end defun
 
+@defun completion-boundaries string collection predicate suffix
+This function returns the boundaries of the field on which @var{collection}
+will operate, assuming that @var{string} holds the text before point
+and @var{suffix} holds the text after point.
+
+Normally completion operates on the whole string, so for all normal
+collections, this will always return @code{(0 . (length
+@var{suffix}))}.  But more complex completion such as completion on
+files is done one field at a time.  For example, completion of
+@code{"/usr/sh"} will include @code{"/usr/share/"} but not
+@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
+Also @code{all-completions} on @code{"/usr/sh"} will not include
+@code{"/usr/share/"} but only @code{"share/"}.  So if @var{string} is
+@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
+@code{completion-boundaries} will return @code{(5 . 1)} which tells us
+that the @var{collection} will only return completion information that
+pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
+@end defun
+
 If you store a completion alist in a variable, you should mark the
 variable as ``risky'' with a non-@code{nil}
 @code{risky-local-variable} property.  @xref{File Local Variables}.
@@ -1618,13 +1638,14 @@
 can supply your own function to compute the completion of a given
 string.  This is called @dfn{programmed completion}.  Emacs uses
 programmed completion when completing file names (@pxref{File Name
-Completion}).
+Completion}), among many other cases.
 
-  To use this feature, pass a symbol with a function definition as the
-@var{collection} argument to @code{completing-read}.  The function
+  To use this feature, pass a function as the @var{collection}
+argument to @code{completing-read}.  The function
 @code{completing-read} arranges to pass your completion function along
-to @code{try-completion} and @code{all-completions}, which will then let
-your function do all the work.
+to @code{try-completion}, @code{all-completions}, and other basic
+completion functions, which will then let your function do all
+the work.
 
   The completion function should accept three arguments:
 
@@ -1638,10 +1659,14 @@
 and ignore the possible match if the predicate returns @code{nil}.
 
 @item
-A flag specifying the type of operation.
+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
 
-  There are three flag values for three operations:
+  There are currently four methods, i.e. four flag values, one for
+  each of the four different basic operations:
 
 @itemize @bullet
 @item
@@ -1663,6 +1688,13 @@
 @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
+@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
+in the string to complete, and END is the position of the end boundary
+in SUFFIX.
 @end itemize
 
   It would be consistent and clean for completion functions to allow