Subject: 29.0.91; Doc of minibuffer histories and completing-read - automatic addition of completions to DEFAULT list

From: Drew Adams <[email-masked]>
Date: Sat, 15 Jul 2023 23:35:20 +0000

It seems to me that the doc, including in the Elisp manual, doesn't make
clear that, by default, `completing-read' automatically adds the list of
all completions provided by the completion table to the list of
defaults, just after the default value.  That is, by default, it calls
`minibuffer-default-add-completions'.

This is not obvious from reading the docs.  For example, it's not
obvious that if you use `C-h v' and then `M-p', repeating `M-p, you get
the symbols that are variables, one by one, inserted into the
minibuffer.

How so?  Because by default variable `minibuffer-default-add-function'
is `minibuffer-default-add-completions'.  Again, none of this is
obvious.  To find it out, a user needs to check what `M-p' is bound to,
then check the source code for that function, and then the source code
or the doc string of function `goto-history-element', which it calls.

In sum, important user-visible behavior isn't described in the manual or
the "top-level", most-relevant doc strings (e.g. `completing-read').
This is a request to, somehow, make this default behavior more apparent
in the doc.  Thx.

In GNU Emacs 29.0.91 (build 2, x86_64-w64-mingw32) of 2023-05-14 built
 on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3086)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install --with-tree-sitter CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)