bug#11297: 24.1.50; `report-emacs-bug': help, TAB

[Drew Adams]

1. Since Emacs 23, TAB in the bug-reporting buffer is bound to
`message-tab'.  Before that it was bound to `indent-for-tab-command'.
 
The doc string of `message-tab' really should say what `TAB' does in the
typical case where it is pressed in such a buffer.
 
Instead, it says what TAB does when in a message header (but without
ever saying clearly that that is what it is describing).  And then it
sends readers packing for info about what it does in the actual message
body they are writing.
 
The last sentence is all readers have in this regard: "Execute
function specified by `message-tab-body-function' when not in those
headers."
 
There is no indication of what "those headers" refers to, but with a
little guessing, especially if you follow the links to look up
`message-completion-alist' and `message-tab-body-function', you can
perhaps figure out that (a) the first part of the doc string only
describes TAB in message headers and (b) in the body, TAB does what it
does in the `text-mode-map' or the `global-map'.
 
That's a lot of runaround and not very helpful.  Those two bits of info
should at the very least be reversed: Say first what TAB does in the
body of the message, which is 99% of what users write.  Then say that
TAB in a header completes a header field.
 
Better would be to just start out by saying that by default TAB in the
body does `indent-for-tab-command' for regular text.  Details about the
actual command coming from `text-mode-map' or `global-map' can follow
that.
 
It is important for users to realize that (a) TAB generally does what it
does for regular text and (b) they can change the buffer mode
temporarily to make it act differently.  E.g., to edit a Lisp snippet
they can use `M-x emacs-lisp-mode'.  For (b), they must be made aware
that to actually send the message (`C-c C-c') they must return to
`message-mode' or use `M-x message-send-and-exit'.
 

2. All of the information we provide to users about writing a bug report
should be consolidated in the same place.  Some is now in the separate
little `*Bug Help*' buffer that is popped up (why?), and some is in the
message buffer itself (why?), even though it does not get included in
the message that is sent.
 
That separation makes little sense, unless I'm missing something.  Users
should have all of the help in the same place, and it should include
help about writing a bug report and help about sending that report as a
mail message.
 
One possibility would be to have a single sentence telling you to hit
some key, or providing a link, which would show all of the help.  But if
you really want to fill the buffer with the help text for some reason,
that will work too.
 
And as mentioned above, the help info we provide should also mention
that you can change the mode but that you must return to `message-mode'
to use `C-c C-c'.  (Too bad about that, BTW.)  Bug reports often include
snippets of Emacs Lisp or code from other modes.  It might not be
obvious to some users that they can do this, that they need not edit the
code somewhere else and then yank the final, edited snippet to the
message buffer.

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-04-19 on MARVIN
Bzr revision: 107968 monnier@iro.umontreal.ca-20120419220225-gijdcbfxuiqy5dhb
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'