RE: master 2a7488d: Add support for displaying short documentation for function groups

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

> >> I think the manual gives superior information in most cases, so I'd
> >> really like this to link to the manual and not the doc strings.  This
> >> is also a way to guide users into the manual and read more in-depth
> >> about not just the functions described, but the machinery surrounding
> >> them, giving them more context.
> >
> > *Help* should have a link to the relevant manual node. See thread "How
> > to make Emacs popular again."  That's not hard to do, and it's been done
> > (e.g. in `help-fns+.el').
> >
> 
> As I already explained repeatedly, this is _not_ the meaning of my
> proposal in that thread.

The thread is not only about your posts to it.

> My proposal is to _manually_ add pointers to the
> relevant manual _chapters_ in docstrings.

Yes, and I've voiced no objection to that.  I was the
one who pointed you to an example where we do that
already.

But you also said that you think we cannot provide
such links automatically.  And my response to that
is that we can.  And I have.  (And so have others.)
We can use that code, or we can use different code.

We can do both: we can have manual fiddling to add
links override/replace/augment any programmatically
provided links, when that's helpful.

So far, we have _VERY_ few manually provided links.
Nothing is stopping someone from proposing adding
this or that link manually.  Still, we have very
few, so far.

Today, you can use `C-h k C-h m' to get the *Help*
for `describe-mode', then click its `manuals' link:

  For more information see the manuals.

That gives you an Info Index buffer with two links:

  Index Matches
  *************

  Index entries that match `describe-mode':

  * Menu:

  * describe-mode [elisp]:   (elisp)Mode Help. (line 11)
  * describe-mode [emacs]:   (emacs)Misc Help. (line 36)

And those take you to these nodes, which provide the
doc for `describe-mode':

1. (emacs) Top > Help > Misc Help
2. (elisp) Top > Modes > Major Modes > Mode Help

> For example, the docstring of kill-buffer would
> have two links, one to (info "(emacs)Buffers") and another one to (info
> "(elisp)Buffers"), with some explanation.  For example:
> 
> See also the following manual chapters: for interactive use, see `(emacs)
> Buffers'; for Emacs Lisp programming use, see `(elisp) Buffers'.

And for `kill-buffer' the `manuals' link gives you
an Info Index buffer with these two links:

 * kill-buffer [elisp]:   (elisp)Killing Buffers. (line 31)
 * kill-buffer [emacs]:   (emacs)Kill Buffer. (line 22)

I think those are more appropriate targets than your
`Buffers' nodes.  But nothing prevents us from using
code that does what you prefer, if that's agreed upon.
It's not hard to get to the "chapter" node for a node
that the Index takes us to.

But there's a good reason why the Index entries for
`kill-buffer' take us to the nodes they do: they're
specifically about _that command_.

> Your proposal is to merge a feature of help-fns+.el in help-fns.el.  This
> feature adds a link in *Help* buffers, and when the user clicks on that
> link the indexes of a (user chosen) list of manuals are checked to see if
> they contain pointers to the subject of the *Help* buffer.  Doing this is,
> as you said yourself, inefficient.  The result of this scan is presented
> in another buffer as a list of links, and when the user clicks on these
> links the place where the subject of the *Help* buffer is documented in
> the manual is displayed.
> 
> These are two very different proposals.

They're different, yes, but not profoundly different.

And the inefficiency I referred to is likely from my
insufficient knowledge of using `info-lookup'.

With my code EITHER you can quickly get a direct link
to one of the manuals (that's what `info-lookup-symbols'
gives you), OR you can get a link that when clicked
looks up the symbol in each of the manuals and gives
you an Index list of links, as described above.  It's
a user choice.

The former is immediate, but it doesn't give you
links to each of the relevant manuals.  The latter
takes the time to perform index lookups.

But I'm sure that someone more familiar with the
`info-lookup' code can do better than I, providing
links to multiple manuals quickly.  And if that
possibility isn't yet available from info-lookup,
it can likely be coded.

My point is not that we need to use the `help-fns+.el'
code.  And it's not to exclude the addition of links
manually.

My point is that we can and should provide links to
the manuals from *Help*, and we can start doing that
today.  Improvements are always possible.