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

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

[Stefan Kangas]

[-- 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

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

[Michael Albinus]

Stefan Kangas <stefan@marxist.se> writes:

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

Please don't change. "Pilot error" is a known term, see
<http://www.hacker-dictionary.com/terms/pilot-error>.

> Thanks,
> Stefan Kangas

Best regards, Michael.

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

[Stefan Kangas]

Den fre 14 juni 2019 kl 15:13 skrev Michael Albinus <michael.albinus@gmx.de>:
> Please don't change. "Pilot error" is a known term, see
> <http://www.hacker-dictionary.com/terms/pilot-error>.

That is unfortunately not what Wikipedia or Google will show a
confused user, not even when searching e.g. "pilot error software".
So besides hacker lore, which only a subset of our users will be very
familiar with, what is the benefit of using this term?

Thanks,
Stefan Kangas

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

[Michael Albinus]

Stefan Kangas <stefan@marxist.se> writes:

> That is unfortunately not what Wikipedia or Google will show a
> confused user, not even when searching e.g. "pilot error software".
> So besides hacker lore, which only a subset of our users will be very
> familiar with, what is the benefit of using this term?

There are many terms Emacs uses, and which are not documented in Wikipedia.

For what is worth, I object such a change. If needed, we could give a
general guidance in the documentation, where to search for.

> Thanks,
> Stefan Kangas

Best regards, Michael.

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

[Stefan Kangas]

Michael Albinus <michael.albinus@gmx.de> writes:
> There are many terms Emacs uses, and which are not documented in Wikipedia.

Right, but we are now discussing the term "pilot error".  Do you think
that it is better than "user error"?  If yes, why?

Thanks,
Stefan Kangas

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

[Michael Albinus]

Stefan Kangas <stefan@marxist.se> writes:

> Right, but we are now discussing the term "pilot error".  Do you think
> that it is better than "user error"?  If yes, why?

History. Community. Cultural background.

I understand, that new users might not know such terms. But we shouldn't
give them up just because of this. We must explain somewhere, at least
with a reference to the hacker's dictionary or emacswiki or whatever.

If something is not explained in Wikipedia, it cannot be regarded as non
existing. It would be a poor world then.

> Thanks,
> Stefan Kangas

Best regards, Michael.

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

[Drew Adams]

> > That is unfortunately not what Wikipedia or Google will show a
> > confused user, not even when searching e.g. "pilot error software".
> > So besides hacker lore, which only a subset of our users will be very
> > familiar with, what is the benefit of using this term?
> 
> There are many terms Emacs uses, and which are not documented in
> Wikipedia.
> 
> For what is worth, I object such a change. If needed, we could give a
> general guidance in the documentation, where to search for.

FWIW, I agree with Stefan K. about this, but I
don't think it's a big deal either way.

There's nothing special or noteworthy about the
"hackerness" or the "Emacsness" of the phrase
"pilot error", and it's clearer in general to use
"user error".  We lose nothing important by doing
that.

I agree that "pilot error" describes perfectly
what's involved: the cause of the mishap (e.g.
airplane crash) was a human operator, not the
tool/equipment being operated.

But I don't think it helps to use the phrase in
the doc.  There's no need to invite confusion by
users unfamiliar with the phrase.  Just use the
perfectly clear, if less explanatory and poetic,
"user error".

(Just one opinion.)

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

[Juanma Barranquero]

On Fri, Jun 14, 2019 at 4:26 PM Stefan Kangas <stefan@marxist.se> wrote:

> Right, but we are now discussing the term "pilot error".  Do you think
> that it is better than "user error"?  If yes, why?

<delurking>

I think "pilot error" is too jargony. We don't want to force people to
look for unusual idioms in nerdy dictionaries while they're reading
documentation. At least, not on purpose. And certainly looking for
"pilot error" in Google will only add to their confusion.

There's a place for clever. Documentation is not that place, IMHO.

<relurking>

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

[Dmitry Gutov]

On 14.06.2019 17:32, Drew Adams wrote:
> FWIW, I agree with Stefan K. about this, but I
> don't think it's a big deal either way.

Same.

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

[Drew Adams]

> > Right, but we are now discussing the term "pilot error".
> > Do you think that it is better than "user error"?  If
> > yes, why?
> 
> History. Community. Cultural background.

"Pilot error" is better not for those reasons
but because it more precisely (exactly) says
what the cause of the problem is (as I said).
But that's not important enough in this
context to allow confusion by readers
unacquainted with it.

As for history, community, and culture -

This is not much (if at all) about _Emacs_
history, community, and culture, IMO.

The history, community, and culture where the
phrase was born, nurtured, and raised is mainly
a U.S. military-industrial one.

There may have been a time long ago when coders
as a social group (of men) were fairly close
culturally to the military, the aerospace, and
naval industries (the infamous m-i complex).
(For decades more code was in Cobol than any
other language, and not just because it is
verbose.  That may still be the case!)

But that's less true now.  Coders as a group
are not so close to that world.

It's still the case that inquiry into a plane
crash will mention "pilot error", and the phrase
is definitely known widely.  But it's not a loss
if we drop it in favor of the clear-enough "user
error".

Emacs will lose nothing, IMO, in terms of its
history, community, or culture.  It will gain
by being more welcoming to users coming from
different histories, communities, and cultures.

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

[Juri Linkov]

>> Please don't change. "Pilot error" is a known term, see
>> <http://www.hacker-dictionary.com/terms/pilot-error>.
>
> That is unfortunately not what Wikipedia or Google will show a
> confused user, not even when searching e.g. "pilot error software".
> So besides hacker lore, which only a subset of our users will be very
> familiar with, what is the benefit of using this term?

Better to rename it to PMAC error (Problem exists between Monitor And Chair :)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I think "pilot error" is too jargony. We don't want to force people to
  > look for unusual idioms in nerdy dictionaries while they're reading
  > documentation. At least, not on purpose. And certainly looking for
  > "pilot error" in Google will only add to their confusion.

  > There's a place for clever. Documentation is not that place, IMHO.

I agree.
-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Juri Linkov]

>>> Please don't change. "Pilot error" is a known term, see
>>> <http://www.hacker-dictionary.com/terms/pilot-error>.
>>
>> That is unfortunately not what Wikipedia or Google will show a
>> confused user, not even when searching e.g. "pilot error software".
>> So besides hacker lore, which only a subset of our users will be very
>> familiar with, what is the benefit of using this term?
>
> Better to rename it to PMAC error (Problem exists between Monitor And Chair :)

Or more Emacs specific - EMAC (Error between Monitor And Chair)

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

[Paul Eggert]

[-- 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

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

[Noam Postavsky]

Paul Eggert <eggert@cs.ucla.edu> writes:

> +  "Signal a user error (or “pilot error”)."

> +This is like `error' except that a user error (or “pilot error”) comes

s/[“”]/"/ (I hope this doesn't set off another round of bike-shedding).

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

[Michael Albinus]

Noam Postavsky <npostavs@gmail.com> writes:

> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> +  "Signal a user error (or “pilot error”)."
>
>> +This is like `error' except that a user error (or “pilot error”) comes
>
> s/[“”]/"/ (I hope this doesn't set off another round of bike-shedding).

One of the patches is in Tramp. I'm in favor of Noam's change.

Best regards, Michael.

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

[Stefan Kangas]

Paul Eggert <eggert@cs.ucla.edu> writes:
> 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".

Thank you.  This is a good compromise and in my opinion fully
sufficient to remove any confusion.

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

This also looks like an improvement to me.

Best regards,
Stefan Kangas

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

[Paul Eggert]

Noam Postavsky wrote:
> s/[“”]/"/ (I hope this doesn't set off another round of bike-shedding).

OK, thanks, I installed the patches with that further change, and am closing the 
bug report.