Re: completing-read depricated initial-input

[Arash Esbati <arash@gnu.org>]

Drew Adams <drew.adams@oracle.com> writes:

>> > `completing-read' is extremely general, allowing for many different
>> > interactions for many different kinds of use cases.
>> 
>> True, unfortunately.
>
> Why "unfortunately"?

Because extremely general tools give one many ways to do things.  It is
just hard if you find out afterwards that things went in the wrong
direction and you try to clean up.  No other reason.

> And there's `read-from-minibuffer', which is
> even more general.

Therefore we have `read-string'.

> I'd rather have Emacs implement, test, and maintain it than do so
> myself, if possible. ;-)

Good strategy ;-)

>> but you're still free to use the old feature if you
>> think it has a added value from a user perspective.
>
> Sure.  With the risk that what's deprecated might be
> desupported at some point.
>
> (At which point you can always choose to copy the old
> code and continue to use it.  With the bother of
> dealing with incompatibilities, inconsistencies, and
> having to keep some bits synchronized...)

I don't think this will happen for `completing-read'.  Looking at other
places than the docstring of `completing-read', you find:

 • Emacs Lisp Ref:

   21.5 Initial Input[1]

   Several of the functions for minibuffer input have an argument called
   initial. This is a mostly-deprecated feature for specifying that the
   minibuffer should start out with certain text, instead of empty as
   usual. [...]

   We discourage use of a non-nil value for initial, because initial
   input is an intrusive interface. History lists and default values
   provide a much more convenient method to offer useful default inputs
   to the user.

   There is just one situation where you should specify a string for an
   initial argument. This is when you specify a cons cell for the
   history argument. See Minibuffer History.

   21.6.2 Completion and the Minibuffer[2]

   Function: completing-read [...]
   The argument initial is mostly deprecated; we recommend using a
   non-nil value only in conjunction with specifying a cons cell for
   history. See Initial Input. For default input, use default instead.

  • `read-string' docstring:

    Read a string from the minibuffer, prompting with string PROMPT.
    If non-nil, second arg INITIAL-INPUT is a string to insert before reading.
      This argument has been superseded by DEFAULT-VALUE and should
      normally be nil in new code.  It behaves as INITIAL-CONTENTS in
      ‘read-from-minibuffer’ (which see).

Note the terms "mostly-deprecated", "discourage", "recommend",
"superseded".  So maybe the docstring of `completing-read' should be
adjusted to the statements above in order to avoid confusion?

Best, Arash

Footnotes:
[1]  https://www.gnu.org/software/emacs/manual/html_node/elisp/Initial-Input.html
[2]  https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html