GNU bug report logs - #50811
28.0.50; Misleading Docstring for read-string function

Previous Next

Package: emacs;

Reported by: Codruț Constantin Gușoi <mail <at> codrut.pro>

Date: Sun, 26 Sep 2021 08:29:01 UTC

Severity: minor

Tags: moreinfo, notabug

Found in version 28.0.50

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50811 in the body.
You can then email your comments to 50811 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Sun, 26 Sep 2021 08:29:01 GMT) Full text and rfc822 format available.

Acknowledgement sent to Codruț Constantin Gușoi <mail <at> codrut.pro>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 26 Sep 2021 08:29:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Codruț Constantin Gușoi <mail <at> codrut.pro>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 28.0.50; Misleading Docstring for read-string function
Date: Sun, 26 Sep 2021 08:28:05 +0000
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




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 04:23:02 GMT) Full text and rfc822 format available.

Message #8 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Codruț Constantin Gușoi <mail <at> codrut.pro>
Cc: 50811 <at> debbugs.gnu.org
Subject: Re: bug#50811: 28.0.50; Misleading Docstring for read-string function
Date: Mon, 27 Sep 2021 06:22:21 +0200
Codruț Constantin Gușoi <mail <at> 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




Added tag(s) moreinfo. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Mon, 27 Sep 2021 04:23:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 04:36:01 GMT) Full text and rfc822 format available.

Message #13 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Codruț Constantin Gușoi <mail <at> codrut.pro>
To: larsi <at> gnus.org
Cc: 50811 <at> debbugs.gnu.org
Subject: Re: bug#50811: 28.0.50; Misleading Docstring for read-string function
Date: Mon, 27 Sep 2021 04:35:17 +0000
[Message part 1 (text/plain, inline)]
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 <at> 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
[Message part 2 (text/html, inline)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 04:41:02 GMT) Full text and rfc822 format available.

Message #16 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Codruț Constantin Gușoi <mail <at> codrut.pro>
Cc: 50811 <at> debbugs.gnu.org
Subject: Re: bug#50811: 28.0.50; Misleading Docstring for read-string function
Date: Mon, 27 Sep 2021 06:40:31 +0200
Codruț Constantin Gușoi <mail <at> 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




Added tag(s) notabug. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Mon, 27 Sep 2021 04:41:02 GMT) Full text and rfc822 format available.

bug closed, send any further explanations to 50811 <at> debbugs.gnu.org and Codruț Constantin Gușoi <mail <at> codrut.pro> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Mon, 27 Sep 2021 04:41:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 04:58:02 GMT) Full text and rfc822 format available.

Message #23 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Codruț Constantin Gușoi <mail <at> codrut.pro>
To: larsi <at> gnus.org
Cc: 50811 <at> debbugs.gnu.org
Subject: Re: bug#50811: 28.0.50; Misleading Docstring for read-string function
Date: Mon, 27 Sep 2021 04:56:55 +0000
[Message part 1 (text/plain, inline)]
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 <at> 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
[Message part 2 (text/html, inline)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 05:03:02 GMT) Full text and rfc822 format available.

Message #26 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Codruț Constantin Gușoi <mail <at> codrut.pro>
Cc: 50811 <at> debbugs.gnu.org
Subject: Re: bug#50811: 28.0.50; Misleading Docstring for read-string function
Date: Mon, 27 Sep 2021 07:02:19 +0200
Codruț Constantin Gușoi <mail <at> 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




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 15:18:02 GMT) Full text and rfc822 format available.

Message #29 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>,
 Codruț Constantin Gușoi <mail <at> codrut.pro>
Cc: "50811 <at> debbugs.gnu.org" <50811 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#50811: 28.0.50; Misleading Docstring for
 read-string function
Date: Mon, 27 Sep 2021 15:17:27 +0000
> 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.)

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#50811; Package emacs. (Mon, 27 Sep 2021 15:23:02 GMT) Full text and rfc822 format available.

Message #32 received at 50811 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>,
 Codruț Constantin Gușoi <mail <at> codrut.pro>
Cc: "50811 <at> debbugs.gnu.org" <50811 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#50811: 28.0.50; Misleading Docstring for
 read-string function
Date: Mon, 27 Sep 2021 15:22:18 +0000
> 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.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Tue, 26 Oct 2021 11:24:04 GMT) Full text and rfc822 format available.

This bug report was last modified 2 years and 155 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.