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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 36206 in the body.
You can then email your comments to 36206 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Change `user-error' docstring from "pilot error" to "user
 error"
Date: Fri, 14 Jun 2019 13:09:06 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Clarify-error-and-user-error-docstrings.patch (text/x-patch, attachment)]

Message #8 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 15:25:21 +0200

Den fre 14 juni 2019 kl 15:13 skrev Michael Albinus <michael.albinus <at> 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

Message #11 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 15:13:00 +0200

Stefan Kangas <stefan <at> 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.

Message #14 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 15:35:45 +0200

Stefan Kangas <stefan <at> 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.

Message #17 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 15:51:14 +0200

Michael Albinus <michael.albinus <at> 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

Message #20 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 16:08:15 +0200

Stefan Kangas <stefan <at> 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.

Message #23 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Albinus <michael.albinus <at> gmx.de>, Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: RE: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 07:32:37 -0700 (PDT)

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

Message #26 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Michael Albinus <michael.albinus <at> gmx.de>, 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 16:40:10 +0200

On Fri, Jun 14, 2019 at 4:26 PM Stefan Kangas <stefan <at> 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>

Message #29 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Drew Adams <drew.adams <at> oracle.com>,
 Michael Albinus <michael.albinus <at> gmx.de>, Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 17:42:21 +0300

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.

Message #32 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Albinus <michael.albinus <at> gmx.de>, Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: RE: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 08:02:15 -0700 (PDT)

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

Message #35 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Michael Albinus <michael.albinus <at> gmx.de>, 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 22:15:27 +0300

>> 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 :)

Message #38 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Juanma Barranquero <lekktu <at> gmail.com>
Cc: michael.albinus <at> gmx.de, stefan <at> marxist.se, 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Fri, 14 Jun 2019 23:33:27 -0400

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

Message #41 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Michael Albinus <michael.albinus <at> gmx.de>, 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Sun, 16 Jun 2019 01:34:08 +0300

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

Message #44 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: [PATCH] Change `user-error' docstring from "pilot error" to "user
 error"
Date: Sat, 22 Jun 2019 17:39:23 -0700

[Message part 1 (text/plain, inline)]

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.

[0001-Tweak-error-and-user-error-doc-strings.txt (text/plain, attachment)]

Message #47 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: Stefan Kangas <stefan <at> marxist.se>, 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Sat, 22 Jun 2019 21:00:21 -0400

Paul Eggert <eggert <at> 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).

Message #50 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Paul Eggert <eggert <at> cs.ucla.edu>, Stefan Kangas <stefan <at> marxist.se>,
 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Sun, 23 Jun 2019 11:00:16 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:

> Paul Eggert <eggert <at> 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.

Message #53 received at 36206 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 36206 <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Sun, 23 Jun 2019 17:41:02 +0200

Paul Eggert <eggert <at> 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

Message #58 received at 36206-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Stefan Kangas <stefan <at> marxist.se>, 36206-done <at> debbugs.gnu.org
Subject: Re: bug#36206: [PATCH] Change `user-error' docstring from "pilot
 error" to "user error"
Date: Thu, 27 Jun 2019 02:37:20 -0700

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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.