RE: How to make Emacs popular again.

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

> > I see it generally.  What do you see when you use `C-h f defcustom' or
> > `C-h v print-circle? Don't you see links for each of the quoted (`...')
> > functions and vars?
> 
> Yes, but not for the most important one: the function/variable/face...
> being described, defcustom or print-circle in your examples.

That one should be covered by an explicit sentence with
a link to the manual.  I already mentioned that (and
said I do that in help-fns+.el).

But even that one could be handled instead, or also,
the same way.  It's not quoted (`...'), but it's easy
to find where it is and give it go-to-manual behavior.

> >> Wouldn't a "See also chapter N ZZZZ in the Emacs manual." and/or "For
> >> programmers, see also chapter N ZZZZ in the Emacs Lisp manual." (with
> >> hyperlinks) at the end of ordinary help buffers be much more useful?
> >
> > For which symbols?  Are you going to add such a see-also for each quoted
> > name in a `*Help*' buffer?
> 
> No, only for the main symbol, the symbol whose docstring is being
> displayed in the help buffer.  At least that was the meaning of the
> proposal I sent a few hours ago: to add one (or more) link(s) at the end
> of the docstring pointing to the chapter(s) of the manual(s) in which they
> are documented.

I already addressed that.

> > I've long said that we need that for the thing that is the subject of
> > the `*Help*' buffer.
> 
> Then I agree with you :-)
> 
> > And we do have it for some `*Help*' buffers - e.g., `C-h f defcustom'.
> 
> Thank you, this is an excellent example, it is exactly what I meant: a
> link to the chapter of the manual.
> 
> > Inline (i.e., in-context) links are better, in general, than a pile of
> > see-also's at the end of the buffer.
> 
> Not a pile, one or two.  The point is to make manuals more accessible.

Both would be useful:

1. Link(s) to manual(s) for the name that is the
   subject of the help.  This can be in an explicit
   sentence that makes clear what it does - as
   mentioned earlier.

2. Links to manuals for each quoted, linked name in
   the buffer (or each known to be doc'd in a manual,
   if that's known when the buffer is created).

For #2, such names already have inline links where they
occur.  It suffices to (1) give users an easy way to
get to the manual(s) from that location, preferably by
both mouse and key, and (2) let users know about this
possibility.

The usual way to let users know about possible actions
at the mouse-pointer location is `help-echo': a tooltip
or message in the echo area (depending on
`tooltip-use-echo-area').