From 42a99627948986bbaa7bb872bea19c164085c9cb Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 22 Jul 2023 09:34:15 +0300
Subject: [PATCH] ; 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'.
---
doc/lispref/commands.texi | 4 +++-
doc/lispref/text.texi | 19 +++++++++++--------
src/cmds.c | 3 ++-
3 files changed, 16 insertions(+), 10 deletions(-)
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);
--
2.39.5