use of `user-error'

[Drew Adams]

1. I see many places in the trunk source code where `error' is used instead of
`user-error' and where I would naively expect the latter to be used.

Is this because most occurrences of `error' have simply not yet been updated to
`user-error', or am I misunderstanding what `user-error' is for?

It seems to me that _most_ existing occurrences of `error' are in fact places
where `user-error' should be used, according to the doc.  They represent pilot
error and not source-code bug situations that should never arise.  Am I
mistaken?


2. When `user-error' is used, a user will not get a backtrace, even with non-nil
`debug-on-error'.

For a developer to request that a user obtain a backtrace in such a case, it
seems that s?he must now ask the user to also customize `debug-ignored-errors'
to remove `user-error' from the value, in addition to turning on
`debug-on-error'.

That is a bit of bother to explain and do.  Is there a simpler approach?  It
used to be enough to tell a user to turn on `debug-on-error'.  Now they must
fiddle a bit more, it seems.  Can this be remedied?


3. 3rd-party developers often look to the Emacs source code as a guideline for
new things like this.

If I see that `choose-completion' uses `(error "Destination buffer is dead")',
that should give me an idea of what is really meant by a user error and whether
that particular error is expected in the normal course of things (pilot error)
or might represent a source-code bug (shouldn't happen normally).

In this case, whether a dead buffer here represents an Emacs problem or a pilot
problem.  In the case of a dead buffer it's not so easy to tell, but in the case
of `(error "No completion here")' it seems a good guess that it is a pilot error
(i.e., it should be `user-error').

If Emacs Dev will in fact take a long time to switch to using `user-error' where
appropriate - at least for most of the core code, that will cause some
confusion, as others will look to that code for guidance and get the wrong
message here or there.

We've already seen a fair amount of confusion over the interpretation of
`user-error' on both emacs-devel and the bug list, based only on the doc.
Inappropriate core source code will only make this worse.

OT1H, perhaps it would be better NOT to introduce (advertise) `user-error' until
more (most?) of the existing source code has been converted to use it.  OTOH, it
should be documented fully when it is introduced.

Maybe the best solution is for Emacs 24.3 NOT to be released until more of the
code has been converted to properly reflect the introduction of `user-error'?

(I can guess that this is what RMS might have preferred to do: Get it right in
the first place - maybe not in all of the source code, but in most of it.)