GNU bug report logs - #50390
Improve documentation of 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'

Previous Next

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

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

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

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Improve documentation of 'read-char-choice-use-read-key' and
 'y-or-n-p-use-read-key'
Date: Sun, 5 Sep 2021 04:56:18 +0200

Severity: wishlist
X-Debbugs-CC: Juri Linkov <juri <at> linkov.net>

I read in NEWS for Emacs 28:

    New variables 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'.

When I look into the documentation of those variables, I do not get
any explanation of why I would want to use them.  I also can't find
any explanation in the manual.

Even just one or two sentences that indicates its typical use would be
very helpful here.

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

From: Juri Linkov <juri <at> linkov.net>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50390 <at> debbugs.gnu.org
Subject: Re: bug#50390: Improve documentation of
 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'
Date: Sun, 05 Sep 2021 11:08:13 +0300

> I read in NEWS for Emacs 28:
>
>     New variables 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'.
>
> When I look into the documentation of those variables, I do not get
> any explanation of why I would want to use them.  I also can't find
> any explanation in the manual.
>
> Even just one or two sentences that indicates its typical use would be
> very helpful here.

The problem is that read-char-choice still has no docstring.
After adding it, the docstring of read-char-choice should
refer to read-char-choice-use-read-key and explain it.

y-or-n-p already has docstring and should mention y-or-n-p-use-read-key.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: Stefan Kangas <stefan <at> marxist.se>, 50390 <at> debbugs.gnu.org
Subject: Re: bug#50390: Improve documentation of
 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'
Date: Sun, 05 Sep 2021 12:03:28 +0200

Juri Linkov <juri <at> linkov.net> writes:

>> When I look into the documentation of those variables, I do not get
>> any explanation of why I would want to use them.  I also can't find
>> any explanation in the manual.
>>
>> Even just one or two sentences that indicates its typical use would be
>> very helpful here.
>
> The problem is that read-char-choice still has no docstring.
> After adding it, the docstring of read-char-choice should
> refer to read-char-choice-use-read-key and explain it.
>
> y-or-n-p already has docstring and should mention y-or-n-p-use-read-key.

I've now added some text to the doc strings of the variables and
functions to try to explain what the difference here is, which isn't
obvious.  Feel free to improve more -- it's kinda hard to succinctly
explain the user interface difference here.

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: stefan <at> marxist.se, 50390 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#50390: Improve documentation of
 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'
Date: Sun, 05 Sep 2021 13:11:42 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Sun, 05 Sep 2021 12:03:28 +0200
> Cc: Stefan Kangas <stefan <at> marxist.se>, 50390 <at> debbugs.gnu.org
> 
> I've now added some text to the doc strings of the variables and
> functions to try to explain what the difference here is, which isn't
> obvious.  Feel free to improve more -- it's kinda hard to succinctly
> explain the user interface difference here.

What is the non-succinct explanation?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stefan <at> marxist.se, 50390 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#50390: Improve documentation of
 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'
Date: Sun, 05 Sep 2021 12:13:23 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> I've now added some text to the doc strings of the variables and
>> functions to try to explain what the difference here is, which isn't
>> obvious.  Feel free to improve more -- it's kinda hard to succinctly
>> explain the user interface difference here.
>
> What is the non-succinct explanation?

It's in the patch.  :-)

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: stefan <at> marxist.se, 50390 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#50390: Improve documentation of
 'read-char-choice-use-read-key' and 'y-or-n-p-use-read-key'
Date: Sun, 05 Sep 2021 13:32:26 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: stefan <at> marxist.se,  50390 <at> debbugs.gnu.org,  juri <at> linkov.net
> Date: Sun, 05 Sep 2021 12:13:23 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> I've now added some text to the doc strings of the variables and
> >> functions to try to explain what the difference here is, which isn't
> >> obvious.  Feel free to improve more -- it's kinda hard to succinctly
> >> explain the user interface difference here.
> >
> > What is the non-succinct explanation?
> 
> It's in the patch.  :-)

LGTM.

Previous Next

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