bug#11999: 24.1.50; New Info file suffix ".info" breaks `Info-find-node-2'

["Drew Adams" <drew.adams@oracle.com>]

> > My bad.  The difference turned out to be the use now of 
> > `user-error' instead of `error'.  Where I previously just saw
> > a message saying there was no such node, now Emacs puts me in
> > the debugger, because I have non-nil `debug-on-error'.
> 
> So how is one supposed to avoid entering the debugger on user-error,
> when debug-on-error is non-nil?

No idea.

And I am not saying that the debugger should or should be entered here (dunno).
I am saying:

1. In Emacs 24.1, 23,..., the debugger is not entered in this case, even though
I have non-nil debug-on-error.  Perhaps there was an `ignore-errors' or
something. Dunno.

2. The point of the bug report (after realizing what is really happening -
apologies for the mistaken initial description, including Subject line) is that
this particular use case (and perhaps others? it seems that `error' was nearly
systematically replaced with `user-error' in info.el) is inappropriate.  At
least according to the stated purpose of `user-error' - this is not at all
"pilot error".

> > Going only by the doc string of `user-error', it seems that 
> > at least some of the many changes from `error' to `user-error' in
> > info.el (and beyond?) are inappropriate.
> 
> The doc string IMO does not tell enough, and there's no other
> documentation about user-error, neither in the ELisp manual nor in
> NEWS (which only mentions its existence).
> 
> Stefan, could you perhaps provide some insight?  What is a "pilot
> error" in this context, and how should Lisp programs use this new
> facility to (supposedly) provide better diagnostics and/or better
> error handling?

And specifically in the context of this bug report, what do you think is the
correct way to signal to a user that the term s?he tried to look up is not in
the index?  Is it `message'?  `message' + `ding'?  `error' (as always,
previously)?  `user-error'?  something else?

If it is `user-error' then I think the doc needs to be changed to correct the
stated aim of `user-error'.  If it is not `user-error' then maybe the code needs
to be checked generally for additional places where the purpose of `user-error'
might not have been respected.

> > An index lookup of a term that is not in the index is in general
> > NOT a "pilot error".  It is normal behavior on the part of users
> > to look up terms in the index, whether they happen to be there or not.
> 
> I agree.  But then it's unclear to me whether using 'error' in this
> case would be better.  If you think it is, please tell why.

See above.  What `error' or `user-error' does is not so much the problem.  Or
rather, the previous behavior here, where the debugger was not entered, was not
a problem (for me).  Whether that behavior actually corresponds to what `error'
or `user-error' is meant to be used for, I don't know.  In the past, `error' has
been used for many different purposes.

(Most (>99%) uses of `error' have had nothing to do with trying to signal a
problem of the code itself.  IOW, `error' is not used often just for
this-should-never-happen errors (debugging).  But that's the impression I get
from the `user-error' doc: that `user-error' is not intended to signal a
programming problem, which suggests that `error' might be intended for that.)

Two things matter: (1) what the actual behavior is in a given context, and
whether it is useful/appropriate, (2) what the stated use of `user-error' is,
and whether actual uses correspond to it.  To me, #1 is generally more
important.

In this particular case, and some others that I've noticed recently (but do not
remember), what is appropriate is some signal to the user, preferably a signal
that s?he will notice.

`message' messages sometimes get overlooked or lost.  And very often in such a
situation we do also want to return control to top level, i.e., stop the
execution.  So what `error' does is usually pretty much what we want.  But in
some cases we do not want to stop the dialog/execution and just want to point
something out to the user.  In that case, `message' + `ding', or perhaps a
message that requires confirmation (e.g. message box) could be in order.

Wrt this particular case again, I'd suggest mabye returning to the _behavior_
(or similar) of Emacs 24.1 and prior: `error' was used, I believe, but the
debugger was not entered, even with non-nil `debug-on-error'.  IOW, the
execution & user interaction was interrupted with a message stating that the
sought term is not in the index.

How we get that behavior again is less important (to me).  And I do not insist
that it was better to ignore `debug-on-error'.  To be clear, it's OK by me if
you end up keeping the behavior of entering the debugger.  Mostly I was
surprised (and clearly confused, as shown by my initial bug description).

> > An index lookup that finds no hit is NOT "expected to be 
> > the result of an incorrect manipulation on the part of the user,
> > rather than the result of an actual problem." 
> 
> Agree again, but again unsure how 'error' would be better.  Maybe we
> need yet a 3rd kind of errors?

There are two different things: (1) the behavior (what is best here) and (2)
whether such a use of `user-error' fits its description.

As for the behavior, IMO the previous behavior was OK.  But no doubt there
should also be some simple way for a programmer to enter the debugger here.  So
maybe the current behavior is better - dunno.

As for #2, let's please try to first characterize just what the purpose of
`user-error' is, and then let's try to be sure it is used that way.  Otherwise,
the purpose will end up being flouted generally, and it will have no distinct
meaning.

It _looks_ (with just a glance) like someone blanket-replaced `error' with
`user-error' in info.el (and elsewhere?).  That cannot be right, _if_ the stated
purpose of `user-error' is correct.