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

[Drew Adams]

> > In sum, important user-visible behavior isn't described in the manual or
> > the "top-level", most-relevant doc strings (e.g. `completing-read').
> 
> You have described various aspects of the implementation, but no
> "user-visible behavior" and no reason why it would be interesting, let
> alone important, to have that in the manual.  Please consider changing
> the POV of your description so that it will be clear what important
> information is missing and why.  The main purpose of API descriptions
> in the ELisp manual is to explain to Lisp programmers how to achieve
> this or that behavior, and I cannot bridge the gap between that goal
> and what you wrote.

There are two kinds of doc changes I'd like to see:

1. Elisp manual and Lisp description in doc strings
   (e.g. `completing-read', `*-history-element').
   The behavior isn't documented, AFAICT.  It would
   also make sense, I think, to say something about
   the "future history" in node (elisp) `Minibuffer
   History' - how it gets filled automatically with
   all of the initial completion candidates, unless
   you bind `minibuffer-default-add-function' to
   nil (or another non-function value).

2. Emacs manual and user/interactive description
   in doc strings.

I guess I'd like to at least see #1.  It isn't at
all obvious what's going on.

Functions such as `completing-read' give you a way
to control the default or defaults provided for
`M-n', but they DON'T give you a way to prevent
the automatic addition of ALL of the initial
completion candidates.  To me that doesn't make
much sense, but Lispers should at least be told
this up front.  Let's at least tell them they can
prevent this automatic addition by binding
`minibuffer-default-add-function' to nil _around_
a function such as `completing-read'.

#2 is presumably less important, as long as we don't
expose variable `minibuffer-default-add-function'
(or similar) as a user option.  E.g., currently
there's no way for a user to turn off this automatic
addition to the `M-n' defaults.

The user visible behavior is that `M-n' inserts a
default value specific to the command, OR, if var
`minibuffer-default-add-function' is non-nil, a
"default" value which can be ANY value from the
initial completion "domain".

E.g., for `C-h v' that means the name of ANY variable
(source is obarray filtered for vars).  And there's
no user or Lisp control over the order of those
additional defaults.  E.g., `C-h v' adds at most a
single "real" default for `M-n', and it adds ALL vars
(from obarray).

For the Emacs manual, node `Minibuffer History' is
a good place to mention this automatic behavior
that's governed by a variable.  That's where "future
history" is introduced for `M-n'.  (FWIW, I'm not a
fan of the name "future history", instead of what
it used to be called: just "defaults".)

There we mention where the defaults added to "future 
history" come from, but only for file-name input.
And in that case we go into detail, mentioning how
to turn off this automatic addition (the variable
for this is even a user option, unlike the general
case, with `minibuffer-default-add-function').

> it talks about what the code does.  After
> reading this, I have no idea why I would need to know these details.
> Why do I care that the list of all completions is added to the list of
> defaults? why do I care that the code calls
> minibuffer-default-add-completions?

If you want to understand the Lisp code then you
need this info.  I guess that's my main concern.

If, as a user, you want to get an idea what the
`M-n' values are with, e.g., `C-h v', after seeing
them present themselves in a seemingly random order,
then you'd maybe like to know something about what
they are and where they come from.  You might just
wonder if you can turn off their inclusion, since
they kinda represent noise (zillions of variables
in obarray, presented in no order understandable to
users).

Hope this clarifies the request/bug report.
___

Beyond this doc concern, I'll maybe also request
(separately, in an enhancement request) that
Lispers have some way to control at least the order
of these "defaults" that get automatically added
for `M-n'.  E.g., be able to sort the obarray or
list.