C-h C-b to view "Reporting Bugs" section of the manual

C-h C-b to view "Reporting Bugs" section of the manual

[Glenn Morris]

Any objection to a new C-h C-b binding, to jump to the "Reporting Bugs"
section of the manual:


=== modified file 'BUGS'
*** BUGS	2012-05-21 19:32:04 +0000
--- BUGS	2012-05-21 19:35:11 +0000
***************
*** 4,13 ****
  (1) how to tell when to report a bug, and
  (2) how to write a useful bug report and what information it needs to have.
  
! You can read the read the Bugs section of the manual from inside Emacs.
! Start Emacs, do C-h i to enter Info, then m Emacs RET to get to the
! Emacs manual, then m Bugs RET to get to the section on bugs.
! Or you can use the standalone Info program in a like manner.
  (Standalone Info is part of the Texinfo distribution, not part of the
  Emacs distribution.)
  
--- 4,14 ----
  (1) how to tell when to report a bug, and
  (2) how to write a useful bug report and what information it needs to have.
  
! You can read the Bugs section of the manual from inside Emacs.
! Start Emacs, and press C-h C-b.
! Or you can use the standalone Info program:
!  info emacs
!  m Bugs RET
  (Standalone Info is part of the Texinfo distribution, not part of the
  Emacs distribution.)
  

=== modified file 'lisp/help.el'
*** lisp/help.el	2012-02-28 08:17:21 +0000
--- lisp/help.el	2012-05-21 19:24:45 +0000
***************
*** 54,59 ****
--- 54,60 ----
      (define-key map "?" 'help-for-help)
  
      (define-key map "\C-a" 'about-emacs)
+     (define-key map "\C-b" 'info-emacs-bug)
      (define-key map "\C-c" 'describe-copying)
      (define-key map "\C-d" 'view-emacs-debugging)
      (define-key map "\C-e" 'view-external-packages)

=== modified file 'lisp/info.el'
*** lisp/info.el	2012-05-04 23:16:47 +0000
--- lisp/info.el	2012-05-21 19:21:25 +0000
***************
*** 683,688 ****
--- 683,694 ----
    (info "emacs"))
  
  ;;;###autoload
+ (defun info-emacs-bug ()
+   "Display the \"Reporting Bugs\" section of the Emacs manual in Info mode."
+   (interactive)
+   (info "(emacs)Bugs"))
+ 
+ ;;;###autoload
  (defun info-standalone ()
    "Run Emacs as a standalone Info reader.
  Usage:  emacs -f info-standalone [filename]

=== modified file 'lisp/menu-bar.el'
*** lisp/menu-bar.el	2012-01-31 08:38:58 +0000
--- lisp/menu-bar.el	2012-05-21 19:24:05 +0000
***************
*** 1752,1757 ****
--- 1752,1760 ----
      (define-key menu [send-emacs-bug-report]
        `(menu-item ,(purecopy "Send Bug Report...") report-emacs-bug
                    :help ,(purecopy "Send e-mail to Emacs maintainers")))
+     (define-key menu [emacs-manual-bug]
+       `(menu-item ,(purecopy "How to Report a Bug") info-emacs-bug
+                   :help ,(purecopy "Read about how to report an Emacs bug")))
      (define-key menu [emacs-known-problems]
        `(menu-item ,(purecopy "Emacs Known Problems") view-emacs-problems
                    :help ,(purecopy "Read about known problems with Emacs")))

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Drew Adams]

> Any objection to a new C-h C-b binding, to jump to the 
> "Reporting Bugs" section of the manual:

No great objection, but I'd rather not use a help key up for that.  Will you
also want to bind a `C-h' key for (emacs) `Language Help'?  And for (emacs)
`Apropos'?  And for (emacs) `Coding Systems'?

A priori, I would prefer to keep most `C-h' keys for commands that describe
things.  Sooner or later we will have a "b" or "C-b" thingie worth describing
using `C-h C-b'.

Example: In my file `help-fns+.el' I added `C-h M-k' for my `describe-keymap'
command.


Instead of binding `C-h C-b' to take you to (emacs) `Bugs', I'd sooner see us
add a link to (emacs) `Bugs' in the doc string of `report-emacs-bug'.

But I've said that before - we should add info links to *Help* output.
There are patches to do that here:
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html.

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Stephen J. Turnbull]

Drew Adams writes:

 > > Any objection to a new C-h C-b binding, to jump to the 
 > > "Reporting Bugs" section of the manual:
 > 
 > No great objection, but I'd rather not use a help key up for that.  Will you
 > also want to bind a `C-h' key for (emacs) `Language Help'?  And for (emacs)
 > `Apropos'?  And for (emacs) `Coding Systems'?

Different issue.  Binding a key to Reporting Bugs is not for the user
who strokes it, but for the developer who reads the reports.

The problem is that this is not very discoverable; I would guess that
the people who know where to find it don't actually need it.
Furthermore, the need for a quick link will decay rapidly for most
users.

 > Example: In my file `help-fns+.el' I added `C-h M-k' for my `describe-keymap'
 > command.

Speaking of redundant bindings (C-h m ...)

 > Instead of binding `C-h C-b' to take you to (emacs) `Bugs', I'd sooner see us
 > add a link to (emacs) `Bugs' in the doc string of
 > `report-emacs-bug'.

Why there?  That has the same problems as above (except that links
aren't a scarce resource).  The link should be in the blurb that
appears when you invoke r-e-b, where it is obviously useful and
usefully obvious.

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Drew Adams]

>  > `C-h M-k' for `describe-keymap'
> 
> Speaking of redundant bindings (C-h m ...)

Not at all.  Have you tried it?  There is nothing similar anywhere, AFAIK.  It
is not like `C-x b' (current bindings, all maps) or `C-h m' (mode description -
variable and always incomplete wrt a keymap).  Try finding the keys bound in a
minibuffer keymap, in a human-readable form.

The closest thing you have is for a prefix key: `C-x C-h'.  The point with `C-h
M-k' is to "see" the bindings for a given keymap variable.  (Yes, that's
probably more useful for Emacs programmers than the average Emacs user.)

>  > Instead of binding `C-h C-b' to take you to (emacs) 
>  > `Bugs', I'd sooner see us add a link to (emacs) `Bugs' in
>  > the doc string of `report-emacs-bug'.
> 
> Why there?  That has the same problems as above (except that links
> aren't a scarce resource).  The link should be in the blurb that
> appears when you invoke r-e-b, where it is obviously useful and
> usefully obvious.

That could be useful too.  It's not either/or.

When you look for the doc about a command (including `r-e-b'), why not have
immediately a set of links to its doc in the manuals (with the manual names and
nodes in the links).

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Stephen J. Turnbull]

Drew Adams writes:

 > When you look for the doc about a command (including `r-e-b'), why not have
 > immediately a set of links to its doc in the manuals (with the manual names and
 > nodes in the links).

Well, isn't that basic functionality already available as
`Info-elisp-ref' (aka C-h C-f in my emacs)?  Again (in my emacs) when
I use C-h f to get the docstring (which defaults to using the symbol
at point already), point ends up on the name of the function in the
help buffer, so C-h C-f RET takes me to the manual.  Links are more
discoverable, I suppose, but they're also annoying because they're
always in your face.  They also require moving the mouse, which direct
invocation of Info-elisp-ref won't (because if you invoked
`describe-function' via the mouse, the pointer is most likely on the
function in the source buffer).

It's not clear to me that adding links to the original function's
documentation (as opposed to links to docs for other symbols that are
referenced in the help buffer) is doing anybody any favors.

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Drew Adams]

>  > When you look for the doc about a command (including 
>  > `r-e-b'), why not have immediately a set of links to its
>  > doc in the manuals (with the manual names and nodes in the links).
> 
> Well, isn't that basic functionality already available as
> `Info-elisp-ref' (aka C-h C-f in my emacs)?  Again (in my emacs) when
> I use C-h f to get the docstring (which defaults to using the symbol
> at point already), point ends up on the name of the function in the
> help buffer, so C-h C-f RET takes me to the manual.

In GNU Emacs -Q, `C-h C-f' is `view-emacs-FAQ'.  Gnu Emacs has no command
`Info-elisp-ref'.  That's XEmacs, and it apparently looks only in the Elisp
manual.

GNU Emacs has `Info-goto-emacs-command-node', which is bound to `C-h F'.  But it
looks only in the Emacs manual, and it looks only for commands.  (There is also
`Info-goto-emacs-key-command-node' (`C-h K'), which looks up a key in the Emacs
manual.)

What I'm talking about can cover anything you want - by default: functions,
variables, keymaps, modes, faces, and packages.

Anyway, as you say:

> Links are more discoverable

Discoverable?  Well, that's one way of putting it!  If you're _looking_ at a
link there's not a whole lot of "discovery" needed.  (And if you're not looking
at it then good luck discovering it!)  But whatever.

> I suppose, but they're also annoying because they're
> always in your face.

Why don't you look at the thread I cited, or even at the patches?

There is only one link (or none, if the user so chooses) - hardly in-your-face.
Clicking it takes you to a virtual Info index of links to the relevant manual
nodes.

And not just one manual, but a user-configurable list of manuals (by default:
Emacs and Elisp).  It works for the Org Mode manual and the Gnus manual and the
Semantic manual and the Widget manual and ... whatever manuals you want.

It is likewise a user choice whether to check the manuals ahead of time (so not
show any link if there is no manual coverage) or to check them only if you click
the link (costs nothing until you click).

> They also require moving the mouse, 

No.  TAB RET works just as well for following links.  Links are not just for
mice.  (Nothing new.)

> which direct invocation of Info-elisp-ref won't (because if you invoked
> `describe-function' via the mouse, the pointer is most likely on the
> function in the source buffer).
> 
> It's not clear to me that adding links to the original function's
> documentation (as opposed to links to docs for other symbols that are
> referenced in the help buffer) is doing anybody any favors.

I suggest you read the thread.  Only one link is added:

  For more information check the _manuals_.

where _manuals_ is a link to an Info index for the sought thingie.  That index
lists manuals and nodes, with links.

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Stephen J. Turnbull]

Drew Adams writes:

 > In GNU Emacs -Q, `C-h C-f' is `view-emacs-FAQ'.

Now there's a wasted keystroke IMHO.  YMMV.

 > Gnu Emacs has no command `Info-elisp-ref'.

Ah, the beauty of "technical differences"!

 > That's XEmacs, and it apparently looks only in the Elisp
 > manual.

True.  That would not be hard to generalize (in fact, it would seem
you have already done the work), but it could be expensive (eg, if you
generalize it to the point of checking all available Info files' nodes
and indexes, which apparently some user configurations might do).

 > GNU Emacs has `Info-goto-emacs-command-node', which is bound to `C-h F'.

Ah, XEmacs reverses those bindings (a choice I think is marginally
better since Info-elisp-ref is more frequently useful and should be
easier to invoke).

 > But it looks only in the Emacs manual, and it looks only for commands.

As I say, not hard to generalize (technically; there might be
substantial opposition on grounds of taste since Emacs seems to prefer
narrowly-targeted commands here, also in C-h a).

 > Anyway, as you say:
 > 
 > > Links are more discoverable
 > 
 > Discoverable?  Well, that's one way of putting it!

No, that is the technical term for it in usability work.  You know
that.

 > Why don't you look at the thread I cited, or even at the patches?

Because I'm not interested in the patch, I'm interested in improved
bug reporting.  If you want to advocate a general patch, fine -- but
don't trash me for hewing to the topic (see subject, preserved
unchanged from your post).

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Stephen J. Turnbull]

Drew Adams writes:

 > >  > `C-h M-k' for `describe-keymap'
 > > 
 > > Speaking of redundant bindings (C-h m ...)
 > 
 > Not at all.  Have you tried it?  There is nothing similar anywhere, AFAIK.  It
 > is not like `C-x b' (current bindings, all maps) or `C-h m' (mode description -
 > variable and always incomplete wrt a keymap).  Try finding the keys bound in a
 > minibuffer keymap, in a human-readable form.

*shrug*  For me, it's a YAGNI; I've never wanted that, so M-x
describe-keymap would be good enough in case I ever want it in the
future.

Maybe other people would like it to be on key though, and I grant that
bindable keys are now a scarce resource.

 > When you look for the doc about a command (including `r-e-b'), why
 > not have immediately a set of links to its doc in the manuals (with
 > the manual names and nodes in the links).

Well, my answer is "that's ugly and harder to invoke (gotta goose the
rat) than C-h C-f RET which already works" (at least in XEmacs, C-h f
foo RET gives you the docstring for foo and leaves point on `foo' so
that C-h C-f defaults to the right thing).  IMO YMMV FWIW etc.

Furthermore, here the purpose of putting the Bugs node on a key is to
make it immediately available to bug reporters.  This isn't about
documenting the use of r-e-b, it's about good style in bug reports.
So it would need to be special-cased somehow (I guess you could have a
generic function that would apropos the obarray and/or the known Info
nodes, but that might be expensive since it would probably have to hit
the disk a lot, possibly including decompressing compressed Info
files).

The proposal to special-case it as a help key is going in the right
direction by making it very inexpensive to get to the Bugs node, but I
question its usefulness because of discoverability concerns.

RE: C-h C-b to view "Reporting Bugs" section of the manual

[Drew Adams]

> here the purpose of putting the Bugs node on a key is to
> make it immediately available to bug reporters.

Well, sure.  Put anything on a key and it is immediately available - via the
key.

In this case, the info is immediately available to bug reporters ... [drumroll]
... who know about that key. ;-)

> This isn't about documenting the use of r-e-b, it's about good
> style in bug reports.

The information about good bug reporting already exists.  This is only about how
to access it.  Do we need a key for that?  Is a key even very helpful for that?
How to find the key?

Or is it enough (and better) to put a link to the info in the bug-reporting
instructions - which you suggested, and which I agreed was a good idea.

My point was that if we added such links to help descriptions _anyway_ then a
direct link would be available for someone looking to find out more about
reporting bugs by checking the command `report-emacs-bug'.  That's all.

> So it would need to be special-cased somehow (I guess you could have a
> generic function that would apropos the obarray and/or the known Info
> nodes, but that might be expensive since it would probably have to hit
> the disk a lot, possibly including decompressing compressed Info
> files).

No idea what that's all about.  Passons...

> The proposal to special-case it as a help key is going in the right
> direction by making it very inexpensive to get to the Bugs node, but I
> question its usefulness because of discoverability concerns.

Me too.  I like your idea of adding a link to the reporting instructions.
That's clearly the best place for discovery.

The point about a link in the help for `report-emacs-bug' was only that that
comes for free if we already provide such a feature for `describe-*' output
generally (which I do, and which is easily done).

No, such a link is not as immediately available as a link in the reporting
instructions.  But it is more discoverable than `C-h C-b' - at least someone who
looks up what `C-h f `report-emacs-bug' is all about will come across it.  (And
it doesn't cost a key binding, which was the original question.)

Re: C-h C-b to view "Reporting Bugs" section of the manual

[Glenn Morris]

Never mind, I changed my mind, it doesn't need a key binding.