From 1d9bb2ff70ca65dbfdd2ec904b8f6d9e07a6e9c5 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 27 Jun 2019 02:33:36 -0700 Subject: [PATCH] =?utf8?q?Tweak=20=E2=80=98error=E2=80=99=20and=20?= =?utf8?q?=E2=80=98user-error=E2=80=99=20doc=20strings?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * 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 1abed4e717a..3efac8d74f9 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 fcad2ccf0a2..4a1649f6019 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) -- 2.39.2