RE: [External] : Doc of deprecated INITIAL-INPUT arg of completing-read

[Drew Adams]

> there was a long discussion in emacs-help about the INITIAL-INPUT
> argument of `completing-read'.  Among other things people complained
> about the argument being deprecated.
> 
> I agree that it's not good to use it in nearly all cases, but there ARE
> a few cases where it hardly can be avoided - we have over 30 uses in
> Emacs itself.  So I want to suggest to change the docstring to warn
> strongly about the usage of that argument, but stop saying it would be
> deprecated.
> 
> This is to make the current state of the code more consistent - I don't
> plan to work on changes that had been suggested in that discussion.
> 
> So would this patch be ok to install for now?

FWIW, for my part I disagree that any "warning"
is warranted.  There's nothing dangerous to warn
about.

I disagree with this (as I also disagree with the
deprecation):

  Using this argument is strongly discouraged--it is
                         ^^^^^^^^^^^^^^^^^^^^
  normally best to pass nil for INITIAL-INPUT and
  ^^^^^^^^^^^^^
  supply the default value DEF except in few special
                               ^^^^^^^^^^^^^^^^^^^^^
  cases like inserting a prefix common to all
  completions or an initial part of a file name.

There's zero reason to discourage its use in any
blanket way, let alone "strongly" discourage.

INIT and DEF are different in behavior, and thus
in use cases.  Telling users to use one of them
_instead of_ the other is misguided, IMO.

All that's needed is to make clear that INIT
isn't intended as a _substitute_ for a default
value - and vice versa.  That's really the point
(IMO).  The use cases of INIT are different from
those of DEF.  That's what should be made clear.
Then leave it up to coders to use each as they
see fit.
___

But the confusion over their different uses is
related to a missing feature, IMO, which is the
ability for users to automatically insert the
DEF value (not INIT) into the minibuffer, as an
alternative to using `M-n' to insert it.

Neither alternative is absolutely "better" than
the other - this is naturally a user preference.

The mistakes made in deciding to deprecate (or
discourage) INIT-INPUT are two: (1) confusing
it with a default value - DEF is no substitute
for INIT, and (2) thinking that it's never a
good UI to insert default values (DEF) in the
minibuffer.

#1 should be fixed by removing the deprecation
and explaining the difference between the two
(not by warning not to use INIT).

#2 should be fixed by letting _users_ decide
which DEF-inserting behavior they prefer: (1)
automatic or (2) manual (`M-n').

The choice of whether DEF should be inserted in
the minibuffer should be up to users.  It's not
for Emacs to decide for all and always which UI
behavior (auto or `M-n') is better for everyone.

If a user often wants to use (edit or choose)
the default value then s?he might well want it
to be inserted in the minibuffer.  If a user
rarely uses the default value then s?he might
want to insert it only manually, with `M-n'.

That's really what it comes down to: having to
delete DEF manually, if you don't want it, or
having to insert it manually, if you do.

(This is somewhat akin to the choice of whether
to use `delete-selection-mode'.)

In the help-gnu-emacs discussion you cited, I
detailed what I would propose for #2 - I won't
repeat details here.  I'll just say that users
should have some way to choose whether DEF is
to be automatically inserted in the minibuffer.

(I also said there that they should have a way
to choose whether it's inserted in the prompt.
With my proposal, when DEF's auto-inserted in
the minibuffer it's not inserted in the prompt,
but users can also choose to never insert it
in the prompt.)

In any case, a missing insert-DEF-in-minibuffer
behavior is 100% _independent_ of INIT-INPUT,
which, yes, shouldn't be deprecated.