RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

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

    	type a key sequence (e.g. `C-M-s')
    	choose a menu item (e.g. [menu-bar files open-file])
    	click on a scroll bar
    	click on the mode line
    	click in the minibuffer
    	click on an Emacs-related name in a buffer: apropos is called
    	click anywhere else in a buffer: its modes are described

    It sounds like this does everything that C-x k does
    except in the case of clicking on the buffer contents.
    Is that right?

I'm not that familiar with the current C-x k. If it gives help on the
mode-line, minibuffer, and scroll-bar, then yes.

However, this gives a lot more info than what `describe-key' provides. It
tries to give a maximum of info, by using apropos, apropos-documentation
(both with apropos-do-all=t), and `Info-goto-emacs-key-command-node', in
addition to `describe-key'. The idea is essentially, "Find me all
information about ____".

         Help is generally provided using `describe-key' and the
         Emacs online manual (via `Info-goto-emacs-key-command-node').
         If no entry is found in the index of the Emacs manual, then
         the manual is searched from the
         beginning for literal occurrences of KEY.

    I don't quite understand.  How does it decide which one of these to do?
    Does it always try each of them?

The important thing is the general idea of providing something like this;
it's not important what my implementation does. Anyway, it does this:

The type of the object is tested and used to determine what help to gather.
If `describe-key' makes sense for the object (key, mode-line, menu-bar menu
item, mouse-menu menu item, etc.), then that is called. If
`Info-goto-emacs-key-command-node' also makes sense, then that is called
too. (The first info is in *Help*; the second in *Info*.) Specific objects
such as mode-line and minibuffer open the appropriate Info node directly.

If the object is a mouse click on text, then apropos-documentation is called
on symbol-at-point (with apropos-do-all bound to t). Next, apropos is called
on the symbol. (If apropos-documentation produced something, then buffer
*Apropos* is renamed to *Apropos Doc*.)

If a buffer is clicked, but not on text, then `describe-mode' is called.

A message tells you where to look for the help, depending on which sources
produced it:

 "`%s': summary in *Help* buffer; doc in *info* buffer."

 "`%s': summary in *Help* buffer."

 "`%s': doc in *info* buffer."

 "`%s' is undefined."

 "See *Apropos* and *Apropos Doc* buffers."

 "See information on `%s' in the *Apropos* buffer."

 "See information on `%s' in the *Apropos Doc* buffer."

 "No information found regarding `%s'."

 "Mode(s) of buffer `%s' are described in *Help* buffer."

Note: Some basic functions, such as `Info-goto-emacs-key-command-node', were
tweaked to return non-nil if Info doc is found. These are in library
info+.el, not help+.el.

`Info-goto-emacs-key-command-node' was also tweaked to call `Info-search' if
not found. That is, if the term can't be found in the index, then a literal
search for it is made.

The source code is here:
 http://www.emacswiki.org/cgi-bin/wiki/help%2b.el

 http://www.emacswiki.org/cgi-bin/wiki/info%2b.el

help+.el is only for Emacs 20. info+.el works with Emacs 22 too.

HTH.