[Emacs-diffs] /srv/bzr/emacs/trunk r105021: Clarify the `call-interactively' doc string, and add an example.

[Lars Magne Ingebrigtsen]

------------------------------------------------------------
revno: 105021
committer: Lars Magne Ingebrigtsen <address@hidden>
branch nick: trunk
timestamp: Thu 2011-07-07 18:59:26 +0200
message:
  Clarify the `call-interactively' doc string, and add an example.
modified:
  doc/lispref/ChangeLog
  doc/lispref/commands.texi
  src/ChangeLog
  src/callint.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-07-06 18:34:55 +0000
+++ b/doc/lispref/ChangeLog     2011-07-07 16:59:26 +0000
@@ -1,3 +1,8 @@
+2011-07-07  Lars Magne Ingebrigtsen  <address@hidden>
+
+       * commands.texi (Interactive Call): Add a `call-interactively'
+       example (bug#1010).
+
 2011-07-06  Lars Magne Ingebrigtsen  <address@hidden>
 
        * functions.texi (Calling Functions): Link to the "Interactive

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2011-03-28 20:26:35 +0000
+++ b/doc/lispref/commands.texi 2011-07-07 16:59:26 +0000
@@ -597,13 +597,32 @@
 
 @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
address@hidden 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:
+
address@hidden
+(defun foo (begin end)
+  (interactive "r")
+  ...)
address@hidden example
+
+then saying
+
address@hidden
+(call-interactively 'foo)
address@hidden 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
address@hidden is a symbol, then @code{call-interactively} uses its
+function definition.
 
 @cindex record command history
 If @var{record-flag} is address@hidden, then this command and its

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2011-07-07 16:18:25 +0000
+++ b/src/ChangeLog     2011-07-07 16:59:26 +0000
@@ -1,3 +1,8 @@
+2011-07-07  Lars Magne Ingebrigtsen  <address@hidden>
+
+       * callint.c (Fcall_interactively): Change "reading args" to
+       "providing args" to try to clarify what it does (bug#1010).
+
 2011-07-07  Kenichi Handa  <address@hidden>
 
        * composite.c (composition_compute_stop_pos): Ignore a static

=== modified file 'src/callint.c'
--- a/src/callint.c     2011-07-03 23:21:45 +0000
+++ b/src/callint.c     2011-07-07 16:59:26 +0000
@@ -234,7 +234,7 @@
 }
 
 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