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).

diff --git a/lisp/subr.el b/lisp/subr.el
index 0fc1156d40ccea8adfd8bf533d5a2b2fcb115f72..137e298cd84ab6f0f3a962df53ed647738cf89b7 100644 (file)
--- 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 a2322f1b49d21769b13e91dea38b5986413c63dc..274c7b3fa84bcfb2dc73c9c94e5ee6e152b44c81 100644 (file)
--- 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");