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

[Tim Landscheidt]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> I'm not perplexed :-).  What I find confusing is:

>> a) The solution for this "very usual" use case is not men-
>>    tioned anywhere in the documentation.  Instead, the doc-
>>    string (for completing-read) suggests a different work-
>>    flow.

> The documentation probably needs to be improved in this respect,
> admittedly, but I can't see where the docstring suggests a different
> workflow (or more specifically, I suspect that it only does so if you
> have a particular workflow in mind to start with).

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.

>> b) With this solution, if the user needs to change the de-
>>    fault/initial value, he has to use one more keystroke
>>    (M-n) than if INITIAL-INPUT had been used.

> But with your solution, the users that want not just to modify the
> default but to enter a different value need to first delete the initial
> value, (e.g. `C-a C-k`).
> You win some, you lose some.

For example, when I use M-x compile RET, I typically do not
want to enter a different value, but amend the existing one
by adding/changing the target or setting an option.  But
even in the basic case of C-x C-f, if I want to find a file
upwards of default-directory, the two extra keystrokes har-
monize well with wanting to do something different, so it
never occured to me that Emacs should protect me from them.

Tim