emacs-31 4f1af6fa6ec: ; * doc/lispref/commands.texi (Interactive Codes): Clarify '*' (bug#81236).

branch: emacs-31
commit 4f1af6fa6ec4452532e84b641512255f65c7d507
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    ; * doc/lispref/commands.texi (Interactive Codes): Clarify '*' (bug#81236).
---
 doc/lispref/commands.texi | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 76a3db1947b..8614ee53f87 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -388,7 +388,16 @@ It is a single, isolated character.
 
 @table @samp
 @item *
-Signal an error if the current buffer is read-only.  Special.
+Signal an error if the current buffer is read-only.  Special.  Note that
+many Emacs primitives will signal an error if a command attempts to
+modify text of a read-only buffer, even if the command's interactive
+spec does not include @samp{*}.  So this character is for when you want
+to forcibly signal an error even if the command's implementation doesn't
+invoke any primitives which modify the buffer.  For example, a command
+that binds @code{inhibit-read-only} non-@code{nil} (because it affects
+more than just read-only buffers), or a command which, depending on the
+conditions, might end up not modifying the buffer, but you want it to
+signal this error anyway.
 
 @item @@
 Select the window mentioned in the first mouse event in the key