Clarify the `call-interactively' doc string, and add an example.

2 files changed, 31 insertions, 7 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  <larsi@gnus.org>
+
+        * commands.texi (Interactive Call): Add a `call-interactively'
+        example (bug#1010).
+
 2011-07-06  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * 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