[Emacs-diffs] /srv/bzr/emacs/emacs-23 r99819: * doc/lispref/minibuf.texi (Basic Completion): Document completion-boundaries.

[Stefan Monnier]

------------------------------------------------------------
revno: 99819
committer: Stefan Monnier <address@hidden>
branch nick: emacs-23
timestamp: Sun 2010-05-30 17:18:35 -0400
message:
  * doc/lispref/minibuf.texi (Basic Completion): Document completion-boundaries.
  (Programmed Completion): Document the new fourth method for boundaries.
  * .bzrignore: Ignore new files from trunk, which appear if you use
  colocated branches (i.e. "bzr switch").
modified:
  .bzrignore
  ChangeLog
  doc/lispref/ChangeLog
  doc/lispref/minibuf.texi

=== modified file '.bzrignore'
--- a/.bzrignore        2010-05-24 21:01:10 +0000
+++ b/.bzrignore        2010-05-30 21:18:35 +0000
@@ -67,3 +67,4 @@
 configure.lineno
 src/core
 core
+lib-src/stamp-*

=== modified file 'ChangeLog'
--- a/ChangeLog 2010-05-10 00:37:59 +0000
+++ b/ChangeLog 2010-05-30 21:18:35 +0000
@@ -1,3 +1,8 @@
+2010-05-30  Stefan Monnier  <address@hidden>
+
+       * .bzrignore: Ignore new files from trunk, which appear if you use
+       colocated branches (i.e. "bzr switch").
+
 2010-05-10  Miles Bader  <address@hidden>
 
        * configure.in: Get rid of "unix" pre-defined macro when

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2010-05-08 03:28:26 +0000
+++ b/doc/lispref/ChangeLog     2010-05-30 21:18:35 +0000
@@ -1,3 +1,8 @@
+2010-05-30  Stefan Monnier  <address@hidden>
+
+       * minibuf.texi (Basic Completion): Document completion-boundaries.
+       (Programmed Completion): Document the new fourth method for boundaries.
+
 2010-05-07  Chong Yidong  <address@hidden>
 
        * Version 23.2 released.

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2010-05-03 22:01:23 +0000
+++ b/doc/lispref/minibuf.texi  2010-05-30 21:18:35 +0000
@@ -812,6 +812,24 @@
 If @var{collection} is a function, it is called with three arguments,
 the values @var{string}, @var{predicate} and @code{lambda}; whatever
 it returns, @code{test-completion} returns in turn.
+
address@hidden 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
address@hidden))}.  But more complex completion such as completion on
+files is done one field at a time.  For example, completion of
address@hidden"/usr/sh"} will include @code{"/usr/share/"} but not
address@hidden"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
+Also @code{all-completions} on @code{"/usr/sh"} will not include
address@hidden"/usr/share/"} but only @code{"share/"}.  So if @var{string} is
address@hidden"/usr/sh"} and @var{suffix} is @code{"e/doc"},
address@hidden 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
@@ -1618,13 +1636,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
address@hidden 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 +1657,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 +1686,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.
+
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
+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