bug#62502: 29.0.60; Docstring of `read-char-choice'

bug#62502: 29.0.60; Docstring of `read-char-choice'

[Arash Esbati]

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

bug#62502: 29.0.60; Docstring of `read-char-choice'

[Eli Zaretskii]

> From: Arash Esbati <arash@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.

bug#62502: 29.0.60; Docstring of `read-char-choice'

[Eli Zaretskii]

> Cc: 62502@debbugs.gnu.org
> Date: Tue, 28 Mar 2023 20:29:11 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Arash Esbati <arash@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.

bug#62502: 29.0.60; Docstring of `read-char-choice'

[Arash Esbati]

Eli Zaretskii <eliz@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