bug#57937: 29.0.50; Improve doc of (interactive current-prefix-arg ...)

bug#57937: 29.0.50; Improve doc of (interactive current-prefix-arg ...)

[Stefan Kangas]

Severity: wishlist

I think the explanation in (info "(elisp) Using Interactive") could
include a pointer to `current-prefix-arg', which AFAICT is only
documented much later in (info "(elisp) Prefix Command Arguments").

Perhaps something could be added also to
(info "(elisp) Interactive Examples")?

bug#57937: 29.0.50; Improve doc of (interactive current-prefix-arg ...)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Mon, 19 Sep 2022 12:12:52 -0400
> 
> Severity: wishlist
> 
> I think the explanation in (info "(elisp) Using Interactive") could
> include a pointer to `current-prefix-arg', which AFAICT is only
> documented much later in (info "(elisp) Prefix Command Arguments").

There is already such a pointer there:

   There are three possibilities for the argument ARG-DESCRIPTOR:

   • It may be omitted or ‘nil’; then the command is called with no
     arguments.  This leads quickly to an error if the command requires
     one or more arguments.

   • It may be a string; its contents are a sequence of elements
     separated by newlines, one for each argument(1).  Each element
     consists of a code character (*note Interactive Codes::) optionally
     followed by a prompt (which some code characters use and some
     ignore).  Here is an example:

          (interactive "P\nbFrobnicate buffer: ")

     The code letter ‘P’ sets the command’s first argument to the raw
     command prefix (*note Prefix Command Arguments::).

bug#57937: 29.0.50; Improve doc of (interactive current-prefix-arg ...)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> There is already such a pointer there:
>
>    There are three possibilities for the argument ARG-DESCRIPTOR:
>
>    • It may be omitted or ‘nil’; ...
>    • It may be a string; ...

I was thinking of this item:

   • It may be a Lisp expression that is not a string; ...

Here, I'd like to see an example like:

          (interactive current-prefix-arg)

and a brief pointer to `(elisp) Prefix Command Arguments'.

bug#57937: 29.0.50; Improve doc of (interactive current-prefix-arg ...)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Mon, 19 Sep 2022 15:35:12 -0400
> Cc: 57937@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > There is already such a pointer there:
> >
> >    There are three possibilities for the argument ARG-DESCRIPTOR:
> >
> >    • It may be omitted or ‘nil’; ...
> >    • It may be a string; ...
> 
> I was thinking of this item:
> 
>    • It may be a Lisp expression that is not a string; ...
> 
> Here, I'd like to see an example like:
> 
>           (interactive current-prefix-arg)
> 
> and a brief pointer to `(elisp) Prefix Command Arguments'.

That comes _after_ the above-mention place, which already points to
that node, so what would be the point and the importance of repeating
the reference?  Using current-prefix-arg in a Lisp expression is not
different from using any other Lisp variable.