Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

>>> The docstring for completing-read (GNU Emacs 28.3) says re-
>>> garding INITIAL-INPUT:
>
>>> | If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
>>> |   with point positioned at the end.  If it is (STRING . POSITION), the
>>> |   initial input is STRING, but point is placed at _zero-indexed_
>>> |   position POSITION in STRING.  (*Note* that this is different from
>>> |   ‘read-from-minibuffer’ and related functions, which use one-indexing
>>> |   for POSITION.)  This feature is deprecated--it is best to pass nil
>>> |   for INITIAL-INPUT and supply the default value DEF instead.  The
>>> |   user can yank the default value into the minibuffer easily using
>>> |   M-n.
>
>>> If one follows this recommendation (setting INITIAL-INPUT to
>>> nil and passing the original value as DEF), the user is not
>>> made aware of the original INITIAL-INPUT value until he
>>> presses M-n.
>
>> Oh, you mean we should add that the default should be passed to
>> `format-prompt`?  I guess that would help, indeed.
>
> Yes.  (I doubt, though, that my brain can ever be trained to
> find it convenient that pressing RET at position B will make
> Emacs use the text displayed at position A, and this text at
> position B will not go away if I tell Emacs that I want to
> enter something different so that I can remember that if I
> delete all text and press RET, it will use the text at posi-
> tion A again.)

But that's a UI issue.  Whereas we're discussing an API issue.
The API's design should allow for several UI choices.

> I wasn't aware of the latter two until now, and I can't say
> that the display of "~//etc/passwd" leading to visit
> "/etc/passwd", but (find-file "~//etc/passwd") not working
> is intuitive to me.

That's been a feature of `C-x C-f` since for ever :-)
At some point the (find-file "~//etc/passwd") also worked.  I think this
was changed around Emacs-21 or maybe even Emacs-19.  Then in Emacs-22 we
added the `file-name-shadow-mode` to give some visual feedback about
the feature.


        Stefan