bug#50811: 28.0.50; Misleading Docstring for read-string function

bug#50811: 28.0.50; Misleading Docstring for read-string function

[mail--- via Bug reports for GNU Emacs, the Swiss army knife of text editors]

While trying to solve and issue in an emacs pacage: https://github.com/Alexander-Miller/cfrs/pull/6 I encountered the following docstring entry for the read-string function:


```

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).
```


This is misleading since INITIAL-INPUT behaves differently from DEFAULT-VALUE:


```

;; No pre-completed value, returns "" when empty.
(read-string "PROMPT ")

;; Pre-completed with "A", returns "" when empty.
(read-string "PROMPT " "A")

;; Pre-completed with "A", returns "B" when empty.
(read-string "PROMPT " "A" nil "B")

;; No pre-completed value, returns "B" when empty.
(read-string "PROMPT " nil nil "B")

```


Not sure what should be done here, either remove that note, since both arguments do a different job, or change the code to pass around DEFAULT-VALUE instead of INITIAL-INPUT internally when INITIAL-INPUT is nil, as the docstring suggests. But the latter feels weird to me as getting rid of INITIAL-INPUT would be a breaking change so it's probably never going to be removed from the arguments list. Also I am not sure what the initial intention of superseding INITIAL-INPUT was.


Let me know what you think works best and I can submit patches.

Cheers,
Codruț

www.codrut.pro

bug#50811: 28.0.50; Misleading Docstring for read-string function

[Lars Ingebrigtsen]

Codruț Constantin Gușoi <mail@codrut.pro> writes:

> 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).
> ```
>
> This is misleading since INITIAL-INPUT behaves differently from DEFAULT-VALUE:

The doc string isn't claiming that INITIAL-INPUT behaves like
DEFAULT-VALUE -- it says that you shouldn't use INITIAL-INPUT.

The point is that we want to move away from pre-filled prompts in Emacs,
and instead put the default in the "future history", i.e., say

(read-string "PROMPT " nil nil "B")

and then the user should `M-n' to edit the default.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#50811: 28.0.50; Misleading Docstring for read-string function

[mail--- via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1464 bytes --]

Hello Larsi

But why, I don't see the benefit?

That's exactly the behaviour I need for renaming a file, for example; a prompt pre-filled with the current filename. It's the same UX as in every other program that does this sort of functionality and the extra keypress makes it harder to use.

This is more like a styleguide for emacs lips development what you're describing, I hope you won't change the function behaviour in the future, it's working well as it is right now.

Cheers,
Codruț

www.codrut.pro

-------- Original Message --------
On 27 Sep 2021, 07:22, Lars Ingebrigtsen wrote:

> Codruț Constantin Gușoi <mail@codrut.pro> writes:
>
>> 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).
>> ```
>>
>> This is misleading since INITIAL-INPUT behaves differently from DEFAULT-VALUE:
>
> The doc string isn't claiming that INITIAL-INPUT behaves like
> DEFAULT-VALUE -- it says that you shouldn't use INITIAL-INPUT.
>
> The point is that we want to move away from pre-filled prompts in Emacs,
> and instead put the default in the "future history", i.e., say
>
> (read-string "PROMPT " nil nil "B")
>
> and then the user should `M-n' to edit the default.
>
> --
> (domestic pets only, the antidote for overdose, milk.)
> bloggy blog: http://lars.ingebrigtsen.no

[-- Attachment #2: Type: text/html, Size: 1836 bytes --]

bug#50811: 28.0.50; Misleading Docstring for read-string function

[Lars Ingebrigtsen]

Codruț Constantin Gușoi <mail@codrut.pro> writes:

> That's exactly the behaviour I need for renaming a file, for example; a
> prompt pre-filled with the current filename. It's the same UX as in every
> other program that does this sort of functionality and the extra keypress
> makes it harder to use.

I wasn't part of the discussions when this happened (I think it was more
than a decade ago), but I think the idea was that users were annoyed
that (in many cases) they had to remove the default completely before
being able to type stuff in.

That is, with

(read-string "PROMPT " "This is the very long default")

you have to delete all that before you can type in "foo", which is what
you wanted to say.  (Or `C-a C-k' is you're an expert.)

Putting the default in the "future history" means that the user can type
"foo" immediately (if they want that), or RET if they want the default,
or `M-n' if they want to edit the default.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#50811: 28.0.50; Misleading Docstring for read-string function

[mail--- via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1496 bytes --]

Bash has `C-u` for this, but that obviously can't be used in emacs. May I suggest a variable that controls the behaviour instead of changing it completely in the future? Just don't take my INITIAL-VALUE away :)

Anyway, there does not seem to be any action to take right now. Thank you for clarifying.

Cheers,
Codruț

www.codrut.pro

-------- Original Message --------
On 27 Sep 2021, 07:40, Lars Ingebrigtsen wrote:

> Codruț Constantin Gușoi <mail@codrut.pro> writes:
>
>> That's exactly the behaviour I need for renaming a file, for example; a
>> prompt pre-filled with the current filename. It's the same UX as in every
>> other program that does this sort of functionality and the extra keypress
>> makes it harder to use.
>
> I wasn't part of the discussions when this happened (I think it was more
> than a decade ago), but I think the idea was that users were annoyed
> that (in many cases) they had to remove the default completely before
> being able to type stuff in.
>
> That is, with
>
> (read-string "PROMPT " "This is the very long default")
>
> you have to delete all that before you can type in "foo", which is what
> you wanted to say. (Or `C-a C-k' is you're an expert.)
>
> Putting the default in the "future history" means that the user can type
> "foo" immediately (if they want that), or RET if they want the default,
> or `M-n' if they want to edit the default.
>
> --
> (domestic pets only, the antidote for overdose, milk.)
> bloggy blog: http://lars.ingebrigtsen.no

[-- Attachment #2: Type: text/html, Size: 1859 bytes --]

bug#50811: 28.0.50; Misleading Docstring for read-string function

[Lars Ingebrigtsen]

Codruț Constantin Gușoi <mail@codrut.pro> writes:

> Bash has `C-u` for this, but that obviously can't be used in emacs. May I
> suggest a variable that controls the behaviour instead of changing it
> completely in the future? Just don't take my INITIAL-VALUE away :)

It's not going anywhere, it's just discouraged.  :-)  People writing
third-party code are free to follow the UI guidance or not, of course.
It's free software after all.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#50811: [External] : bug#50811: 28.0.50; Misleading Docstring for read-string function

[Drew Adams]

> The point is that we want to move away from pre-filled prompts in
> Emacs, and instead put the default in the "future history", i.e., say
> (read-string "PROMPT " nil nil "B")
> and then the user should `M-n' to edit the default.

Yes, and that "moving away" is misguided, IMHO.
There was never any reason to call INITIAL-INPUT
obsolete.

It's not either-or.

Just because `M-n' and DEFAULTS are useful, that's
never been a logical reason to make INITIAL-INPUT
obsolete.

(Oh, and that misguided deprecation was proclaimed
long before we allowed DEFAULTS to be a list and
not just a single value.)

bug#50811: [External] : bug#50811: 28.0.50; Misleading Docstring for read-string function

[Drew Adams]

> I wasn't part of the discussions when this happened (I think it was
> more than a decade ago), but I think the idea was that users were annoyed
> that (in many cases) they had to remove the default completely before
> being able to type stuff in.

Which is misguided.  It's not because someone
designs a particular call to `read-*' poorly
that the function shouldn't allow use of
INITIAL-INPUT.  Use it only when that makes
sense.  And let users know what the behavior
(interaction) is for the given command.

> That is, with
> (read-string "PROMPT " "This is the very long default")
> you have to delete all that before you can type in "foo", which is what
> you wanted to say.  (Or `C-a C-k' is you're an expert.)

As the doctor said, "Just don't do that!"
You can misuse anything.  That's not a reason
to have nothing.