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

[Drew Adams]

        The first item, "This...", lets you type a key sequence or
        click something (e.g. mode-line, minibuffer, Emacs-related
        name in a buffer, menu item), and it gives you information
        on that object. The info is that provided by
        `describe-*', plus apropos + Info doc, if appropriate.

    I don't see concretely how that differs from C-h k.
    Could you give details?

Something similar was discussed a while back, I believe. I'm not sure it's
worth people spending time considering now, but here's a description
(below). Take it as food for thought - some parts of it might be more useful
than others.

The basic idea is to let users discover features of Emacs by pointing to
them  (or their names) individually and saying "what's this?". It emulates
some UIs that provide a menu item that, when clicked, turns the mouse
pointer to a question mark. The user then clicks the pointer on some object,
and some info is provided on that object. In MS Windows, this is called
"What's This". The emacs-devel discussion a while back turned around the
question of whether or not Windows still has this feature etc. This is not
something that started with Windows, BTW - it was available in applications
long before Windows existed.

The "What's This" feature on Windows was often poorly implemented, providing
little help. However, Emacs already has online help about all of its
features - this would simply help users get to that help on a
feature-by-feature basis: just point and ask.

In my case, I didn't change the mouse pointer to a question mark, but that
would probably be a good thing to do. Also, I wanted to give a maximum of
info on the object, whereas Windows "What's This" tends to give minimal,
one-liner info (similar to tool-tip info). So, I combined info from the
various help commands (e.g. `describe-key', `apropos') with info from the
manual.

I simply let the various component help sources open their own windows
(frames in my case), so the user could decide which to read and which to
ignore (that was also the easiest implementation for me). That is, I made no
attempt to integrate the various help sources that I tapped. Emacs help is
more or less detailed, depending, for example, on whether it is provided by
`describe-variable', `apropos', `apropos-documentation', or `info'. Each of
these (if available and appropriate) was displayed in a separate frame - the
user could choose which to examine, depending on the context and the user's
background.

Any feature that you can designate through the UI is a candidate for
explaining this way, BTW, not just UI features. For example, you can point
to an Emacs name (wherever you see it) and get info about it.

This was also the case for Windows' "What's This", to some extent, though
often it was not clear if you were asking for help about a UI feature or
about the underlying functionality. Obviously, there needs to be some
hierarchy in the implementation, to guess whether the user wants info on
some name or the buffer where it occurs, and so on.

Anyway, here's the description (from the doc string of command
`help-on-click/key':

 "(help-on-click/key KEY)

 Give help on a key/menu sequence or object clicked with the mouse.
 The object can be any part of an Emacs window or a name appearing in a
 buffer.  You can do any of the following:

    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

 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.

 For example, the KEY `C-g' is not in the index (for some reason), so
 the manual is searched.  (Once an occurrence is found, you can
 repeatedly type `s' in *Info* to search for additional occurrences.)

 If you click on a name in a buffer, then `apropos-documentation' and
 `apropos' are used to find information on the name.  These functions
 are not used when you do something besides click on a name.

 If you click elsewhere in a buffer other than the minibuffer, then
 `describe-mode' is used to describe the buffer's current mode(s)."

Again, this was for Emacs 20, so this description would not be complete for
Emacs 22 (there are a lot more things to point to now: fringe etc.).

And the comment about `C-g' not being in the Emacs-manual index is no longer
true. Nevertheless, that functionality might still be useful: search the
manual text if the term to find is not in the index.

The expectation, BTW, was not that users would learn about this by reading
the above help - that would be confusing for someone who didn't know what a
minibuffer was etc. The idea was that users would just try it (click
"Describe > This..." in the menu) and find out what it is by using it.

If such a feature were considered for Emacs (for after the release), these
aspects could be discussed:

 - What info should be provided (e.g. what info sources, how much detail)?

 - For what objects?

 - How would a user designate each of those objects?

This command is intended to help people to discover Emacs features. The
general idea is, I think, a good one, regardless of what design might be
used. Emacs is feature-rich, and its UI offers a lot that many newbies have
never experienced elsewhere (it is unusual). And many of the UI features are
not obvious (not to mention the non-UI features).

HTH.