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

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

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

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.

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.

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

Previous Next

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