master 250b728284: Improve command-error-function discoverability

[Lars Ingebrigtsen]

branch: master
commit 250b728284ecfb7eeb477020e631e183908992d0
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Improve command-error-function discoverability
    
    * lisp/subr.el (error, user-error): Point to command-error-function.
    
    * src/keyboard.c (syms_of_keyboard): Add an example (bug#40750).
---
 lisp/subr.el   | 10 ++++++++--
 src/keyboard.c |  8 ++++++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/lisp/subr.el b/lisp/subr.el
index 0fc1156d40..137e298cd8 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -441,7 +441,10 @@ To signal with MESSAGE without interpreting format 
characters
 like `%', `\\=`' and `\\='', use (error \"%s\" MESSAGE).
 In Emacs, the convention is that error messages start with a capital
 letter but *do not* end with a period.  Please follow this convention
-for the sake of consistency."
+for the sake of consistency.
+
+To alter the look of the displayed error messages, you can use
+the `command-error-function' variable."
   (declare (advertised-calling-convention (string &rest args) "23.1"))
   (signal 'error (list (apply #'format-message args))))
 
@@ -457,7 +460,10 @@ To signal with MESSAGE without interpreting format 
characters
 like `%', `\\=`' and `\\='', use (user-error \"%s\" MESSAGE).
 In Emacs, the convention is that error messages start with a capital
 letter but *do not* end with a period.  Please follow this convention
-for the sake of consistency."
+for the sake of consistency.
+
+To alter the look of the displayed error messages, you can use
+the `command-error-function' variable."
   (signal 'user-error (list (apply #'format-message format args))))
 
 (defun define-error (name message &optional parent)
diff --git a/src/keyboard.c b/src/keyboard.c
index a2322f1b49..274c7b3fa8 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -12863,6 +12863,14 @@ Called with three arguments:
 - the context (a string which normally goes at the start of the message),
 - the Lisp function within which the error was signaled.
 
+For instance, to make error messages stand out more in the echo area,
+you could say something like:
+
+    (setq command-error-function
+          (lambda (data _ _)
+            (message "%s" (propertize (error-message-string data)
+                                      \\='face \\='error))))
+
 Also see `set-message-function' (which controls how non-error messages
 are displayed).  */);
   Vcommand_error_function = intern ("command-error-default-function");