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

[Drew Adams <drew.adams@oracle.com>]

> >> > Try this:
> >> > `C-h v org TAB'
> >> > `M-n'
> >> > `M-n'
> >> > ...
> >>
> >> Why candidates are inserted in a random order?
> >> It would make sense to insert them in the same
> >> order as they are sorted in the *Completions* buffer.
> >
> > That's one reasonable possibility.
> > It's not the only one.

> So currently there are three different sorting orders
> used by default:
> 1. 'TAB' uses the alphabetical order;
> 1. 'M-p' uses the historical order;
> 2. 'M-n' is unsorted and follows the order of the caller.

No, `M-n' is just like `M-p' for previous
inputs.  And for DEFAULTS it's in the order
of DEFAULTS - which has nothing to do with
the set of initial completion candidates or
their order.

The misfeature that introduced all of the
problems you're considering now was to
stuff all of the _completion_ candidates
(the completion domain) into the `M-n'
(and thus `M-p') queue.  That was a huge
mistake, IMHO.

> > The fact is that the candidates are in
> > a useless order, particularly when the
> > completion table is just obarray or an
> > unsorted, filtered subset of obarray.
> 
> This means that the caller should take care about
> sorting completions is a meaningful order.
> But then a new metadata type similar to
> 'display-sort-function' should be added
> such as 'minibuffer-default-sort-function'
> that might be a hassle.

No, just revert the misfeature of adding
the completion domain to the `M-n' queue.
End of story - no problem.

> (defun minibuffer-default-add-completions ()
>   "Return a list of all completions without the default value.
> This function is used to add all elements of the completion table to
> the end of the list of defaults just after the default value."

Just get rid of that function altogether.
Pull this misfeature out of Emacs; it
never should have been added (and IIRC
that was done without any discussion?).

> > Why are all candidates inserted into the
> > `M-n' queue at all?  And why no ability
> > to filter them or sort them - during
> > completion (i.e., taking the current
> > completion state into account).
> 
> Because 'M-n' is not completion.

Precisely!

Minibuffer input, and its history and its
defaults, is not related to the COLLECTION
used for completing.  Lax completion doesn't
even require that your minibuffer input be
any COLLECTION element.

Completion candidates have no business being
automatically injected into the `M-n'/`M-p'
queue.  That's for DEFAULTS and HISTORY.

Arg DEFAULTS has a raison d'etre; it's not
the same as arg COLLECTION.

You're going farther down that dead-end
rabbit hole now.  Back out and plug that
misdirected hole.