Expand documentation on nontrivial completion boundaries.

The interplay between nontrivial completion boundaries and the other
completion functions is somewhat subtle, so it deserves a bit more
explanation.

* doc/lispref/minibuf.texi (Basic Completion)
(Programmed Completion): Add a few more remarks about nontrivial
completion boundaries.

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index f012bfef07e84ee291e11ab84041dac788306ff4..faee43b21a19030b85de39b8e98685d809ef3dd3 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -990,6 +990,9 @@ Also @code{all-completions} on @code{"/usr/sh"} will not include
 @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"}.
+@code{try-completion} is not affected by nontrivial boundaries; i.e.,
+@code{try-completion} on @code{"/usr/sh"} might still return
+@code{"/usr/share/"}, not @code{"share/"}.
 @end defun
 
 If you store a completion alist in a variable, you should mark the
@@ -1894,6 +1897,13 @@ should return @code{(boundaries @var{start} . @var{end})}, where
 string, and @var{end} is the position of the end boundary in
 @var{suffix}.
 
+If you return nontrivial boundaries, make sure that the
+@code{all-completions} operation is consistent with them.  The
+completions returned by @code{all-completions} should only pertain to
+the piece of the prefix and suffix covered by the completion
+boundaries.  @ref{Basic Completion} for the precise expected semantics
+of completion boundaries.
+
 @item metadata
 This specifies a request for information about the state of the
 current completion.  The return value should have the form