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

[Drew Adams]

> > 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.  If
you don't understand it then I wasn't clear
enough or perhaps you haven't yet tried hard
enough.  Let's try one more time.

> I asked specific questions, and I don't see
> answers to those questions.
> 
> How about if you start from some specific
> behavior of completing-read when called in a
> specific way, and then point out which aspects of
> this behavior are not documented?

These are the only questions I find in your replies:

 > 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?
 >
 > Etc. etc.

I don't find those so specific.  And I
think my post provides answers to both
of them. But let me try again, keeping
those questions in mind.

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.)

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 makes `M-n` useless (beyond the first
variable, at most).  And confusing.  The
natural question is "What's this?  What's
it for?  What can I do with it?"  Answer:
It's for nothing (that I can see).  It's
useless.  It's an antifeature - at least
in the case of `C-h v'.  And in other cases
(but maybe not all).

Why does a user care about
`minibuffer-default-add-completions'?

She doesn't.  I didn't say she does.  (But
an _Elisp_ user _might_ care.)

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').

And an Elisp user needs to know about that
variable if s?he has a small completion
domain (unlike that of `describe-variable'),
and so s?he wants automatic inclusion of
completions, and s?he wants to control the
order in which they're presented by `M-n'.
`M-n' and `M-p' are inherently all about
_order_ - order matters.  Different contexts
can call for different orders.
        
The best subset of the completion domain for
a given command's `M-n' use, and the best
`M-n' order for it, is up to the definer of
that command (more precisely, of each use of
`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. 

I mentioned that I think it would help to
make some changes to both the Elisp doc and
the user doc.  Doc strings and manuals.  But
I also mentioned that I think it's the Lisp
doc that's most in need of some explanation
about this.

Because blind automatic inclusion of all
domain completions occurs, end users need,
unfortunately, to be made aware of the
behavior (at least how to inhibit it).

IMO it's a bug that something like `C-h v'
stuffs all variables into `M-n' - in a 
perceptibly random order, no less.  But
given that bug (is it by design?), a user
(yes, and end user) needs to be given a
heads-up as to what's happening.

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.

To be clear: There's a world of difference
between (1) a command that provides a list
of likely useful default values in arg DEF
and (2) a command that provides a single
such DEF value.

And that difference is felt harder when
the completion domain is large, and even
harder when it's large and in a useless
order.

By tacking - systematically - all domain
completions onto the end of the carefully
defined DEFaults, we now, in effect,
pollute `M-n', reducing or eliminating what
value it had.  And in particular, we've now
worked against the feature of letting DEF
provide multiple values ("future history").

The request mitigates some of the damage
done by the blind and systematic addition
to `M-n' of all completions in the domain.
If we fix that design bug in some way then
the need for the doc requested here might
be less critical.

If you still don't understand the problem,
let me ask you to simply try this:

`C-h v'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
...

What's happening?  What determines which
symbols get inserted in the minibuffer,
and in what order?  Answer: All symbols
in the obarray when `completing-read'
is called are filtered by a predicate
that tests for a defvar or a variable
that's buffer-local variable in the
buffer where you invoked `C-h v'.

There are thousands of variables in that
future history.  Good luck getting to
any of them that might be useful (after
the first one, the provided DEF) in any
given context.

And your minibuffer input can't help you.
Try this:

`C-h v org TAB'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
`M-n'
...

Of course the zillions of variables
stuffed into the `M-n' queue don't
reflect your minibuffer input ("org").
They don't reflect the state of
completion at all.  So this attempt
to guess at what's happening, and how
you might control it a bit, is a red
herring.

That's OK.  But what on earth do the
`M-n' values correspond to?  What's
their relevance/significance/use?
Answer: None - irrelevant, useless.
April fool!

The behavior is not useful, rational,
expected, or understandable.  With a
little aid from the doc it could at
least become expected and, to some
extent, understandable.  Let's at
least provide that bit of help.

HTH.