From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 23 Feb 2019 13:31:15 +0000 (+0200)
Subject: Minor improvement for docs of completion
X-Git-Tag: emacs-26.2~55
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=dee3cdc;p=emacs.git

Minor improvement for docs of completion

* doc/lispref/minibuf.texi (Completion Commands)
(Completion in Buffers, Programmed Completion): Add to text
that references completion tables a cross-reference to where
"completion table" is described.
(Programmed Completion): Fix the description of
'completion-table-dynamic'.  Add more cross-references.
---

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 0c0862160bf..796be07ef14 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1102,11 +1102,11 @@ different function to completely override the normal behavior of
 in the minibuffer to do completion.
 
 @defvar minibuffer-completion-table
-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}.
+The value of this variable is the completion table (@pxref{Basic
+Completion}) 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}.
 @end defvar
 
 @defvar minibuffer-completion-predicate
@@ -1764,7 +1764,8 @@ possible match, and ignore the match if the predicate returns
 @code{nil}.
 
 @item
-A flag specifying the type of completion operation to perform.  This
+A flag specifying the type of completion operation to perform; see
+@ref{Basic Completion}, for the details of those operations.  This
 flag may be one of the following values.
 
 @table @code
@@ -1835,17 +1836,26 @@ the same as for @code{display-sort-function}.
 
 @defun completion-table-dynamic function &optional switch-buffer
 This function is a convenient way to write a function that can act as
-a programmed completion function.  The argument @var{function} should be
-a function that takes one argument, a string, and returns an alist of
-possible completions of it.  It is allowed to ignore the argument and
-return a full list of all possible completions.  You can think of
-@code{completion-table-dynamic} as a transducer between that interface
+a programmed completion function.  The argument @var{function} should
+be a function that takes one argument, a string, and returns a
+completion table (@pxref{Basic Completion}) containing all the
+possible completions.  The table returned by @var{function} can also
+include elements that don't match the string argument; they are
+automatically filtered out by @code{completion-table-dynamic}.  In
+particular, @var{function} can ignore its argument and return a full
+list of all possible completions.  You can think of
+@code{completion-table-dynamic} as a transducer between @var{function}
 and the interface for programmed completion functions.
 
 If the optional argument @var{switch-buffer} is non-@code{nil}, and
 completion is performed in the minibuffer, @var{function} will be
 called with current buffer set to the buffer from which the minibuffer
 was entered.
+
+The return value of @code{completion-table-dynamic} is a function that
+can be used as the 2nd argument to @code{try-completion} and
+@code{all-completions}.  Note that this function will always return
+empty metadata and trivial boundaries (@pxref{Programmed Completion}).
 @end defun
 
 @defun completion-table-with-cache function &optional ignore-case
@@ -1870,9 +1880,10 @@ Emacs Manual}.  This command uses the abnormal hook variable
 
 @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}).
+are used to compute a completion table (@pxref{Basic Completion}) 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