Subject: RE: bug#15101: 24.3.50; debugger-eval-expression broken

From: Drew Adams <[email-masked]>
Date: Thu, 15 Aug 2013 14:12:59 -0700 (PDT)

> > A user will still be tripped up by the undocumented and unguessable
> > behavior.
> 
> Check the doc before saying it's not documented.
> And yes, NEWS is part of the doc.

I mentioned clearly that I *did* check the doc:

  >> AFAICT, there is no mention of this in the doc yet.  I see that
  >> "lexical" is mentioned only briefly in (elisp) `Edebug Eval' - and
  >> nothing about this.  And it is not mentioned at all in the manual
  >> sections about the standard, non-edebug debugger (i.e., command
  >> `debug').

But yes, I had checked only in the most recent build I have (2013-08-08).
Mea culpa.

If you updated the doc as a result of this bug report (today), and your
update addresses all of the concerns I mentioned, great.  Pat on back.

But if you simply added a blurb to NEWS about this then no, that does not
handle the problem adequately for users.  If that's all you did then
please help users more than that.

Yes, NEWS is a part of the doc.  That doesn't make it the only place to
cover something like this.  (A change log is also doc.  As is a code
comment.)

NEWS is doc that users consult to find out about significant changes, but
it is not the doc they consult to find out about the product features and
how to use them.  You don't look only, or even mainly, in NEWS to find out
what `C-x C-f' does and how to use it.  Likewise, `e' in the debugger.

You expect the manuals and `C-h k C-x C-f' to tell you that.  And you
expect that information to be up-to-date and relatively complete.

Users should not need to consult NEWS to find out why something like `e',
which they have been using for decades, suddenly does not do what they
expect.  Each of the debugger commands/keys, of which `e' is one, is
described in the Elisp manual.  User-visible changes to the behavior
should result in an update of that doc.

FWIW, I have now checked the latest `debugging.texi' in BZR
(http://bzr.savannah.gnu.org/lh/emacs/trunk/annotate/head:/doc/lispref/debugging.texi).

Unfortunately, I see no change there from what has been there for the
description of `e' for a long time.  Nothing about any of the things
discussed in this thread.  No help for a user about cursor on first line;
which evaluation context is used when not on first line; differences
between lexical and dynamic; etc.  Nada.  Not a good thing for users.