[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 1d9bb2f 2/2: Tweak ‘error’ and ‘user-error’ doc st
From: |
Paul Eggert |
Subject: |
[Emacs-diffs] master 1d9bb2f 2/2: Tweak ‘error’ and ‘user-error’ doc strings |
Date: |
Thu, 27 Jun 2019 05:37:14 -0400 (EDT) |
branch: master
commit 1d9bb2ff70ca65dbfdd2ec904b8f6d9e07a6e9c5
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>
Tweak ‘error’ and ‘user-error’ doc strings
* lisp/net/tramp.el (tramp-user-error):
* lisp/subr.el (user-error):
Say that user errors are sometimes called pilot errors.
* lisp/subr.el (error, user-error):
Reorder wording to discuss mechanism first, then formatting advice,
rather than going back and forth between the two topics.
Tighten up the wording a bit.
---
lisp/net/tramp.el | 2 +-
lisp/subr.el | 27 +++++++++++++--------------
2 files changed, 14 insertions(+), 15 deletions(-)
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 1abed4e..3efac8d 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -1860,7 +1860,7 @@ an input event arrives. The other arguments are passed
to `tramp-error'."
;; We must make it a defun, because it is used earlier already.
(defun tramp-user-error (vec-or-proc fmt-string &rest arguments)
- "Signal a user error."
+ "Signal a user error (or \"pilot error\")."
(unwind-protect
(apply
#'tramp-error vec-or-proc
diff --git a/lisp/subr.el b/lisp/subr.el
index fcad2cc..4a1649f 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -325,31 +325,30 @@ This function accepts any number of arguments, but
ignores them."
;; Signal a compile-error if the first arg is missing.
(defun error (&rest args)
"Signal an error, making a message by passing ARGS to `format-message'.
+Errors cause entry to the debugger when `debug-on-error' is non-nil.
+This can be overridden by `debug-ignored-errors'.
+
+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.
-Errors cause entry to the debugger when `debug-on-error' is
-non-nil. This can be overridden by `debug-ignored-errors'.
-
-Note: (error \"%s\" VALUE) makes the message VALUE without
-interpreting format characters like `%', `\\=`', and `\\=''."
+for the sake of consistency."
(declare (advertised-calling-convention (string &rest args) "23.1"))
(signal 'error (list (apply #'format-message args))))
(defun user-error (format &rest args)
"Signal a user error, making a message by passing ARGS to `format-message'.
-This is just like `error' except that `user-error's are expected to be the
-result of an incorrect manipulation on the part of the user, rather than the
-result of an actual problem.
-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.
+This is like `error' except that a user error (or \"pilot error\") comes
+from an incorrect manipulation by the user, not from an actual problem.
In contrast with other errors, user errors normally do not cause
entry to the debugger, even when `debug-on-error' is non-nil.
This can be overridden by `debug-ignored-errors'.
-Note: (user-error \"%s\" VALUE) makes the message VALUE without
-interpreting format characters like `%', `\\=`', and `\\=''."
+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."
(signal 'user-error (list (apply #'format-message format args))))
(defun define-error (name message &optional parent)