bug#1010: 23.0.60; call-interactively doc

bug#1010: 23.0.60; call-interactively doc

[Drew Adams]

The doc for `call-interactively', both Elisp manual and doc string,
could perhaps be improved slightly by changing "reading args" to
"providing args".
 
It's still good to say, in a separate sentence, that this might entail
reading, depending on the `interactive' spec for the individual
arguments. The point is that "calling interactively" does not
necessarily involve anything interactive (input from the user). It
just calls the command providing arguments as determined by the
`interactive' spec, which _might_ require reading user input.
 
In the Elisp manual, a simple example might illustrate what
`call-interactively' is typically used for.
 
This report is prompted by a question on help-gnu-emacs from someone
whose English skills were limited. People helped by suggesting that
the OP read node Interactive Call in the Elisp manual and use
`call-interactively' in his code, but the OP still misunderstood. 
 
His impression was that that would require him to input arguments
interactively, which was not necessarily the case: (interactive
"p\nd\nd"). He was looking, he said, for a way to call a command so
that the command itself figured out the argument values it
needed. What he meant was exactly what `call-interactively' does, but
he didn't grasp the connection even after the suggestion and reading
the doc.
 
I think changing "reading args" to "providing args" would go a long
way toward removing some of this confusion. `interactive' does not
just read args input by the user.
 
 
 
In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-09-03 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

bug#1010: 23.0.60; call-interactively doc

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc for `call-interactively', both Elisp manual and doc string,
> could perhaps be improved slightly by changing "reading args" to
> "providing args".

Yes, I think you're right.  In case of the "r" spec, for instance,
there's little "reading" going on, but it does provide the point/mark to
the function.

I'm guessing the intention was to say that it would prompt the user for
stuff, if the interactive spec is a prompting one.

I've now made the change.

> It's still good to say, in a separate sentence, that this might entail
> reading, depending on the `interactive' spec for the individual
> arguments. The point is that "calling interactively" does not
> necessarily involve anything interactive (input from the user). It
> just calls the command providing arguments as determined by the
> `interactive' spec, which _might_ require reading user input.
>
> In the Elisp manual, a simple example might illustrate what
> `call-interactively' is typically used for.

I've added an example to the manual.

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