From 54e101844312f87d5283db5fd078d0756264caa2 Mon Sep 17 00:00:00 2001 From: Lars Magne Ingebrigtsen Date: Thu, 7 Jul 2011 18:59:26 +0200 Subject: [PATCH] Clarify the `call-interactively' doc string, and add an example. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/commands.texi | 33 ++++++++++++++++++++++++++------- src/ChangeLog | 5 +++++ src/callint.c | 2 +- 4 files changed, 37 insertions(+), 8 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 23ddf0c5ad1..773321f3c67 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2011-07-07 Lars Magne Ingebrigtsen + + * commands.texi (Interactive Call): Add a `call-interactively' + example (bug#1010). + 2011-07-06 Lars Magne Ingebrigtsen * functions.texi (Calling Functions): Link to the "Interactive diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index eb42ddb11a4..dccc2fa571c 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -597,13 +597,32 @@ realistic example of using @code{commandp}. @defun call-interactively command &optional record-flag keys This function calls the interactively callable function @var{command}, -reading arguments according to its interactive calling specifications. -It returns whatever @var{command} returns. An error is signaled if -@var{command} is not a function or if it cannot be called -interactively (i.e., is not a command). Note that keyboard macros -(strings and vectors) are not accepted, even though they are -considered commands, because they are not functions. If @var{command} -is a symbol, then @code{call-interactively} uses its function definition. +providing arguments according to its interactive calling specifications. +It returns whatever @var{command} returns. + +If, for instance, you have a function with the following signature: + +@example +(defun foo (begin end) + (interactive "r") + ...) +@end example + +then saying + +@example +(call-interactively 'foo) +@end example + +will call @code{foo} with the region (@code{point} and @code{mark}) as +the arguments. + +An error is signaled if @var{command} is not a function or if it +cannot be called interactively (i.e., is not a command). Note that +keyboard macros (strings and vectors) are not accepted, even though +they are considered commands, because they are not functions. If +@var{command} is a symbol, then @code{call-interactively} uses its +function definition. @cindex record command history If @var{record-flag} is non-@code{nil}, then this command and its diff --git a/src/ChangeLog b/src/ChangeLog index 9186061530e..8c1af2a27ce 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,8 @@ +2011-07-07 Lars Magne Ingebrigtsen + + * callint.c (Fcall_interactively): Change "reading args" to + "providing args" to try to clarify what it does (bug#1010). + 2011-07-07 Kenichi Handa * composite.c (composition_compute_stop_pos): Ignore a static diff --git a/src/callint.c b/src/callint.c index 1371b403e4b..26b161a25b3 100644 --- a/src/callint.c +++ b/src/callint.c @@ -234,7 +234,7 @@ fix_command (Lisp_Object input, Lisp_Object values) } DEFUN ("call-interactively", Fcall_interactively, Scall_interactively, 1, 3, 0, - doc: /* Call FUNCTION, reading args according to its interactive calling specs. + doc: /* Call FUNCTION, providing args according to its interactive calling specs. Return the value FUNCTION returns. The function contains a specification of how to do the argument reading. In the case of user-defined functions, this is specified by placing a call -- 2.39.5