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

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "64656@debbugs.gnu.org" <64656@debbugs.gnu.org>
> Date: Tue, 18 Jul 2023 20:27:32 +0000
> 
> > > Hope this clarifies the request/bug report.
> > 
> > It doesn't.  Sorry, I guess I'm too stupid
> > to understand what you are asking.
> 
> Don't be silly or sarcastic, please.

This isn't sarcasm, this is frustration.

And please avoid ad-hominem if you can, especially when you yourself
use language that can easily be interpreted as sarcasm:

> A user cares what's available from `M-n'.
> (I don't expect another "Why?" for that,
> but it comes, I'll try to answer that too.)

Isn't that sarcasm?

So let's try to drop the attitude and discuss the real problems, okay?

(Adding Stefan, because I think he could have insights in this area
that is nowadays complicated enough to blow my mind.)

> Why does it matter that all initial (i.e.,
> prior to any user input in the minibuffer)
> completions are put into the `M-n' queue?
> 
> Because that set of candidates is often
> huge.  And because its order isn't designed
> for `M-n' or (especially) for the particular
> act of input reading.  Often its order has
> no special reason.
> 
> And the case given as an example, `C-h v',
> illustrates that well: (1) zillions of vars, 
> (2) in no user-expectable/understandable/
> useful order - the order of obarray!

This part of your report seems to be a separate issue -- you seem to
be saying that "C-h v" and similar commands should not add all the
variables to the "future history".  It's possible that you are right,
although it could be useful if M-s and M-r in the minibuffer would
actually search that list -- which they don't currently, due to how
this "add to future history" feature is implemented to add elements
lazily (see goto-history-element).

But that is a separate issue, almost unrelated to the Subject of your
report, which is about documentation.  Whatever problems we have in
this area with "C-h v", they cannot be solved by documentation in the
ELisp manual.

So what is the documentation issue?  You say:

> What an Elisp user (not an end user of a
> command) really needs to care about is var
> `minibuffer-default-add-function', not the
> particular function that's its default value.
> 
> Forget for a moment about what various
> function values for that variable might do.
> The most important thing about that var is
> that if nil then the domain of completions
> isn't added to the `M-n' queue at all.  IOW,
> that _turns off_ the automatic filling of
> the `M-n' queue.
> 
> An Elisp user needs to know that fact, if
> s?he uses `completing-read' and s?he wants
> to prevent the kind of confusing overkill
> exhibited by `C-h v'.  (She then needs to
> bind the var to nil around the call to
> `completing-read').
> [...]
> Elisp users thus need to know that to define
> the subset and its order for `M-n' they can
> bind var `minibuffer-default-add-function'
> to a function that returns such a list.
> This isn't obvious.  You won't find it by
> reading the `completing-read' doc, at least,
> though it's just as important to controlling
> the behavior as the args to that function. 

First, M-n is not about completion, it is about minibuffer history.
Completion functions use the minibuffer, so the minibuffer history
affects them, but they are not the only ones affected.  The
documentation of completing-read and of read-from-minibuffer already
state that DEFAULT is added to the "future history":

     The argument DEFAULT specifies default values to make available
     through the history commands.  It should be a string, a list of
     strings, or ‘nil’.  The string or strings become the minibuffer’s
     “future history”, available to the user with ‘M-n’.

What is missing here, it seems, is the hint that this addition can be
controlled, among other measures, via minibuffer-default-add-function,
and the documentation of that variable where the minibuffer history is
documented.  Is that what you are asking for, or is there anything
else?

> I mentioned that I think it would help to
> make some changes to both the Elisp doc and
> the user doc.

Why would Emacs users need to know about this?  The mechanism to
control what and how is added to minibuffer history is not user-level
information; users cannot use it to their benefit.

> In effect, the heads-up tells a user that
> when prompted for input with completion,
> in some cases the "future history" of
> defaults is effectively useless.  And it
> doesn't hurt to tell users why: _all_
> possible domain completions are included,
> possibly in a meaningless order.

If we think that future history in some case is useless, TRT is to
change the code so that it ceases to be useless, not to document that
it is useless.  IOW, we don't document our own bugs, we prefer to fix
them.

So no, we won't be telling this in user documentation.  If we decide
that this behavior of "C-h v" and similar commands is not useful, we
should change it to be more useful.