; Improve documentation of 'last-command-event'

* doc/lispref/text.texi (Commands for Insertion):
* doc/lispref/commands.texi (Command Loop Info):
* src/cmds.c (syms_of_cmds) <post-self-insert-hook>: Improve the
documentation of 'last-command-event' and 'post-self-insert-hook'.

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index cd1745614ebfd3beaa514107cbb507d35947f1c3..f84afcf52bdbaede175a79e7301a8eeca9947264 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1132,7 +1132,9 @@ up a menu.  It is also used internally by @code{y-or-n-p}
 This variable is set to the last input event that was read by the
 command loop as part of a command.  The principal use of this variable
 is in @code{self-insert-command}, which uses it to decide which
-character to insert.
+character to insert, and in @code{post-self-insert-hook}
+(@pxref{Commands for Insertion}), which uses it to access the
+character that was just inserted.
 
 @example
 @group

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 82e79e2bc143f94917d80e410962cd88d5714a58..0b0328d0252f6bade8399bf36a3ff68d9b388e0e 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -551,14 +551,17 @@ character has close parenthesis syntax (@pxref{Blinking}).
 @vindex self-insert-uses-region-functions
 The final thing this command does is to run the hook
 @code{post-self-insert-hook}.  You could use this to automatically
-reindent text as it is typed, for example.  If any function on this
-hook needs to act on the region (@pxref{The Region}), it should make
-sure Delete Selection mode (@pxref{Using Region, Delete Selection, ,
-emacs, The GNU Emacs Manual}) doesn't delete the region before
-@code{post-self-insert-hook} functions are invoked.  The way to do so
-is to add a function that returns @code{nil} to
-@code{self-insert-uses-region-functions}, a special hook that tells
-Delete Selection mode it should not delete the region.
+reindent text as it is typed, for example.  The functions on this hook
+can use @code{last-command-event} (@pxref{Command Loop Info}) to
+access the character just inserted.
+
+If any function on this hook needs to act on the region (@pxref{The
+Region}), it should make sure Delete Selection mode (@pxref{Using
+Region, Delete Selection, , emacs, The GNU Emacs Manual}) doesn't
+delete the region before @code{post-self-insert-hook} functions are
+invoked.  The way to do so is to add a function that returns
+@code{nil} to @code{self-insert-uses-region-functions}, a special hook
+that tells Delete Selection mode it should not delete the region.
 
 Do not try substituting your own definition of
 @code{self-insert-command} for the standard one.  The editor command

diff --git a/src/cmds.c b/src/cmds.c
index 15caa4a6972b0184941609b87e05c6ccdb15ed7f..840d5881b59c3eb6a79d53e4164364849431739d 100644 (file)
--- a/src/cmds.c
+++ b/src/cmds.c
@@ -518,7 +518,8 @@ syms_of_cmds (void)
 
   DEFVAR_LISP ("post-self-insert-hook", Vpost_self_insert_hook,
               doc: /* Hook run at the end of `self-insert-command'.
-This is run after inserting the character.  */);
+This is run after inserting a character.
+The hook can access the inserted character via `last-command-event'.  */);
   Vpost_self_insert_hook = Qnil;
 
   defsubr (&Sforward_char);