diff doc/lispref/commands.texi @ 108355:7da3761e3cdf

Document Emacs 23.2 changes. * functions.texi (Obsolete Functions): Document set-advertised-calling-convention. * minibuf.texi (Basic Completion): Document completion-in-region. (Programmed Completion): Document completion-annotate-function. * commands.texi (Reading One Event): Document read-key. (Distinguish Interactive): Document KIND arg to called-interactively-p. Delete obsolete interactive-p. * elisp.texi (Top): Update node description. * misc.texi (Printing): Document htmlfontify-buffer.

--- a/doc/lispref/commands.texi	Sun Apr 25 08:34:03 2010 +0200
+++ b/doc/lispref/commands.texi	Sun Apr 25 17:21:51 2010 -0400
@@ -696,71 +696,67 @@
 because it allows callers to say ``treat this call as interactive.''
 But you can also do the job by testing @code{called-interactively-p}.
 
-@defun called-interactively-p
+@defun called-interactively-p kind
 This function returns @code{t} when the calling function was called
 using @code{call-interactively}.
 
-If the containing function was called by Lisp evaluation (or with
-@code{apply} or @code{funcall}), then it was not called interactively.
+The argument @var{kind} should be either the symbol @code{interactive}
+or the symbol @code{any}.  If it is @code{interactive}, then
+@code{called-interactively-p} returns @code{t} only if the call was
+made directly by the user---e.g., if the user typed a key sequence
+bound to the calling function, but @emph{not} if the user ran a
+keyboard macro that called the function (@pxref{Keyboard Macros}).  If
+@var{kind} is @code{any}, @code{called-interactively-p} returns
+@code{t} for any kind of interactive call, including keyboard macros.
+
+If in doubt, use @code{any}; the only known proper use of
+@code{interactive} is if you need to decide whether to display a
+helpful message while a function is running.
+
+A function is never considered to be called interactively if it was
+called via Lisp evaluation (or with @code{apply} or @code{funcall}).
 @end defun
 
-   Here's an example of using @code{called-interactively-p}:
+@noindent
+Here is an example of using @code{called-interactively-p}:
 
 @example
 @group
 (defun foo ()
   (interactive)
-  (when (called-interactively-p)
-    (message "foo"))
-  'haha)
-     @result{} foo
+  (when (called-interactively-p 'any)
+    (message "Interactive!")
+    'foo-called-interactively))
 @end group
 
 @group
 ;; @r{Type @kbd{M-x foo}.}
-     @print{} foo
+     @print{} Interactive!
 @end group
 
 @group
 (foo)
-     @result{} haha
+     @result{} nil
 @end group
 @end example
 
-  Here is another example that contrasts direct and indirect
-calls to @code{called-interactively-p}.
+@noindent
+Here is another example that contrasts direct and indirect calls to
+@code{called-interactively-p}.
 
 @example
 @group
 (defun bar ()
   (interactive)
-  (setq foobar (list (foo) (called-interactively-p))))
-     @result{} bar
+  (message "%s" (list (foo) (called-interactively-p 'any))))
 @end group
 
 @group
 ;; @r{Type @kbd{M-x bar}.}
-;; @r{This does not display a message.}
-@end group
-
-@group
-foobar
-     @result{} (nil t)
+     @print{} (nil t)
 @end group
 @end example
 
-  If you want to treat commands run in keyboard macros just like calls
-from Lisp programs, test @code{interactive-p} instead of
-@code{called-interactively-p}.
-
-@defun interactive-p
-This function returns @code{t} if the containing function (the one
-whose code includes the call to @code{interactive-p}) was called in
-direct response to user input.  This means that it was called with the
-function @code{call-interactively}, and that a keyboard macro is
-not running, and that Emacs is not running in batch mode.
-@end defun
-
 @node Command Loop Info
 @comment  node-name,  next,  previous,  up
 @section Information from the Command Loop
@@ -2309,10 +2305,8 @@
 @cindex reading a single event
 @cindex event, reading only one
 
-  The lowest level functions for command input are those that read a
-single event.
-
-None of the three functions below suppresses quitting.
+  The lowest level functions for command input are @code{read-event},
+@code{read-char}, and @code{read-char-exclusive}.
 
 @defun read-event &optional prompt inherit-input-method seconds
 This function reads and returns the next event of command input, waiting
@@ -2409,11 +2403,31 @@
 gets a character.  The arguments work as in @code{read-event}.
 @end defun
 
+  None of the above functions suppress quitting.
+
 @defvar num-nonmacro-input-events
 This variable holds the total number of input events received so far
 from the terminal---not counting those generated by keyboard macros.
 @end defvar
 
+  We emphasize that, unlike @code{read-key-sequence}, the functions
+@code{read-event}, @code{read-char}, and @code{read-char-exclusive} do
+not perform the translations described in @ref{Translation Keymaps}.
+If you wish to read a single key taking these translations into
+account, use the function @code{read-key}:
+
+@defun read-key &optional prompt
+This function reads a single key.  It is ``intermediate'' between
+@code{read-key-sequence} and @code{read-event}.  Unlike the former, it
+reads a single key, not a key sequence.  Unlike the latter, it does
+not return a raw event, but decodes and translates the user input
+according to @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} (@pxref{Translation Keymaps}).
+
+The argument @var{prompt} is either a string to be displayed in the
+echo area as a prompt, or @code{nil}, meaning not to display a prompt.
+@end defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events