GNU bug report logs - #62502
29.0.60; Docstring of `read-char-choice'

Previous Next

Package: emacs;

Reported by: Arash Esbati <arash <at> gnu.org>

Date: Tue, 28 Mar 2023 14:33:01 UTC

Severity: minor

Found in version 29.0.60

Done: Arash Esbati <arash <at> gnu.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 62502 in the body.
You can then email your comments to 62502 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#62502; Package emacs. (Tue, 28 Mar 2023 14:33:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Arash Esbati <arash <at> gnu.org>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Tue, 28 Mar 2023 14:33:02 GMT) Full text and rfc822 format available.

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

From: Arash Esbati <arash <at> gnu.org>
To: emacs-bugs <bug-gnu-emacs <at> gnu.org>
Subject: 29.0.60; Docstring of `read-char-choice'
Date: Tue, 28 Mar 2023 16:32:21 +0200
Hi all,

docstring of `read-char-choice' lacks any information about
INHIBIT-KEYBOARD-QUIT:

,----[ C-h f read-char-choice RET ]
| read-char-choice is a native-compiled Lisp function in ‘subr.el’.
| 
| (read-char-choice PROMPT CHARS &optional INHIBIT-KEYBOARD-QUIT)
| 
| Read and return one of CHARS, prompting for PROMPT.
| Any input that is not one of CHARS is ignored.
| 
| By default, the minibuffer is used to read the key
| non-modally (see ‘read-char-from-minibuffer’).  If
| ‘read-char-choice-use-read-key’ is non-nil, the modal ‘read-key’
| function is used instead (see ‘read-char-choice-with-read-key’).
| 
|   Probably introduced at or before Emacs version 24.1.
| 
`----

INHIBIT-KEYBOARD-QUIT is passed to `read-char-choice-with-read-key'; I'd
say it is sufficient to say something like:

  If ‘read-char-choice-use-read-key’ is non-nil, the modal ‘read-key’
  function is used instead (see ‘read-char-choice-with-read-key’) and
  the optional INHIBIT-KEYBOARD-QUIT is passed to it.

Best, Arash




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#62502; Package emacs. (Tue, 28 Mar 2023 17:30:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arash Esbati <arash <at> gnu.org>
Cc: 62502 <at> debbugs.gnu.org
Subject: Re: bug#62502: 29.0.60; Docstring of `read-char-choice'
Date: Tue, 28 Mar 2023 20:29:11 +0300
> From: Arash Esbati <arash <at> gnu.org>
> Date: Tue, 28 Mar 2023 16:32:21 +0200
> 
> docstring of `read-char-choice' lacks any information about
> INHIBIT-KEYBOARD-QUIT:

That's because by default that argument is ignored.

> INHIBIT-KEYBOARD-QUIT is passed to `read-char-choice-with-read-key'; I'd
> say it is sufficient to say something like:
> 
>   If ‘read-char-choice-use-read-key’ is non-nil, the modal ‘read-key’
>   function is used instead (see ‘read-char-choice-with-read-key’) and
>   the optional INHIBIT-KEYBOARD-QUIT is passed to it.

Is it really useful?  I believe read-char-choice-with-read-key is kept
for possible backward compatibility; new Lisp programs that want to
use read-char-choice-with-read-key should just call it directly, and
in its doc string this argument is documented.

So I'm not sure we should do anything about this issue.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#62502; Package emacs. (Tue, 28 Mar 2023 18:35:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: arash <at> gnu.org
Cc: 62502 <at> debbugs.gnu.org
Subject: Re: bug#62502: 29.0.60; Docstring of `read-char-choice'
Date: Tue, 28 Mar 2023 21:34:04 +0300
> Cc: 62502 <at> debbugs.gnu.org
> Date: Tue, 28 Mar 2023 20:29:11 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> 
> > From: Arash Esbati <arash <at> gnu.org>
> > Date: Tue, 28 Mar 2023 16:32:21 +0200
> > 
> > docstring of `read-char-choice' lacks any information about
> > INHIBIT-KEYBOARD-QUIT:
> 
> That's because by default that argument is ignored.
> 
> > INHIBIT-KEYBOARD-QUIT is passed to `read-char-choice-with-read-key'; I'd
> > say it is sufficient to say something like:
> > 
> >   If ‘read-char-choice-use-read-key’ is non-nil, the modal ‘read-key’
> >   function is used instead (see ‘read-char-choice-with-read-key’) and
> >   the optional INHIBIT-KEYBOARD-QUIT is passed to it.
> 
> Is it really useful?  I believe read-char-choice-with-read-key is kept
> for possible backward compatibility; new Lisp programs that want to
> use read-char-choice-with-read-key should just call it directly, and
> in its doc string this argument is documented.
> 
> So I'm not sure we should do anything about this issue.

Since the state of documentation of this and related
functions/variables was unsatisfactory, I ended up fixing it, and as
part of that also mentioned what happens with INHIBIT-KEYBOARD-QUIT.

Thanks.




Reply sent to Arash Esbati <arash <at> gnu.org>:
You have taken responsibility. (Wed, 29 Mar 2023 07:27:02 GMT) Full text and rfc822 format available.

Notification sent to Arash Esbati <arash <at> gnu.org>:
bug acknowledged by developer. (Wed, 29 Mar 2023 07:27:02 GMT) Full text and rfc822 format available.

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

From: Arash Esbati <arash <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 62502-done <at> debbugs.gnu.org
Subject: Re: bug#62502: 29.0.60; Docstring of `read-char-choice'
Date: Wed, 29 Mar 2023 09:26:36 +0200
Eli Zaretskii <eliz <at> gnu.org> writes:

> Since the state of documentation of this and related
> functions/variables was unsatisfactory, I ended up fixing it, and as
> part of that also mentioned what happens with INHIBIT-KEYBOARD-QUIT.

Yes, the documentation is in much better shape now.  Thanks for fixing
this.  I'm closing this report.

Best, Arash




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

This bug report was last modified 337 days ago.

Previous Next


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