bug#36206: [PATCH] Change `user-error' docstring from "pilot error" to "user error"

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 500 bytes --]

Thanks for the proposed fix. Although it appears that the proposal has 
substantial support, some reviewers like the phrase "pilot error". So I propose 
the attached additional patch, which keeps the phrase "pilot error" and says 
that it means the same thing as "user error" - a point that will help people 
unfamiliar with the term "pilot error".

This patch also takes the bikeshedding opportunity to improve the doc strings 
further by ordering them more logically and tightening up the wording.

[-- Attachment #2: 0001-Tweak-error-and-user-error-doc-strings.txt --]
[-- Type: text/plain, Size: 3762 bytes --]

From 635e3175781aa70c047e709c678572a070b44a7e Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 22 Jun 2019 17:28:54 -0700
Subject: [PATCH] =?UTF-8?q?Tweak=20=E2=80=98error=E2=80=99=20and=20?=
 =?UTF-8?q?=E2=80=98user-error=E2=80=99=20doc=20strings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
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 7b6dccc990..653143dfc7 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -1859,7 +1859,7 @@ tramp-error-with-buffer
 
 ;; 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 3e84140fd8..acce822d7b 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -327,31 +327,30 @@ ignore
 ;; 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.17.1