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

[Stefan Kangas <stefan@marxist.se>]

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

The documentation of `user-error' says that it will "Signal a pilot
error", which I personally find confusing.  For starters, "pilot"
could also mean "done as an experiment or test before being introduced
more widely".

It's more clear to say "user error".  I don't have any data on this,
but in my experience this is also more in line with how other
programming languages names this class of errors.

See the attached patch for my suggested improvements.

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-Clarify-error-and-user-error-docstrings.patch --]
[-- Type: text/x-patch, Size: 2838 bytes --]

From 7c9cebb4fc732455e763db21576f62787788d63a Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 14 Jun 2019 12:23:38 +0200
Subject: [PATCH] Clarify error and user-error docstrings

* lisp/subr.el (error, user-error)
* lisp/net/tramp.el (tramp-user-error): Change "pilot error" to "user
error" and improve documentation.
---
 lisp/net/tramp.el |  2 +-
 lisp/subr.el      | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 76eb03b89e..23e2065788 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 pilot error."
+  "Signal a user error."
   (unwind-protect
       (apply
        #'tramp-error vec-or-proc
diff --git a/lisp/subr.el b/lisp/subr.el
index 93a98a4bdb..f20c865d27 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -326,10 +326,12 @@ 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'.
+  "Signal an error, making a message by passing ARGS to `format-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 `\\=''."
@@ -337,13 +339,16 @@ error
   (signal 'error (list (apply #'format-message args))))
 
 (defun user-error (format &rest args)
-  "Signal a pilot error, making a message by passing args to `format-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 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.
+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 `\\=''."
-- 
2.11.0