[Emacs-diffs] emacs-26 dee3cdc: Minor improvement for docs of completion

[Eli Zaretskii]

branch: emacs-26
commit dee3cdc50415a3fa45c6b043590d99adf47c7c69
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/minibuf.texi | 39 +++++++++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 0c08621..796be07 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
address@hidden passes to @code{try-completion}.  It is used by
-minibuffer completion commands such as
address@hidden
+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
address@hidden  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
address@hidden 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
address@hidden 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
address@hidden as a transducer between @var{function}
 and the interface for programmed completion functions.
 
 If the optional argument @var{switch-buffer} is address@hidden, 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
address@hidden  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