From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 22 Jul 2023 06:34:15 +0000 (+0300)
Subject: ; Improve documentation of 'last-command-event'
X-Git-Tag: emacs-29.1-rc1~10
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=42a99627948;p=emacs.git

; 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 cd1745614eb..f84afcf52bd 100644
--- 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 82e79e2bc14..0b0328d0252 100644
--- 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 15caa4a6972..840d5881b59 100644
--- 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);