RE: How to make Emacs popular again.

[Drew Adams]

> > 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).
> 
> Sorry, I did not know you already do that in help-fns+.el when I answered
> RMS' email a few hours ago.
> 
> As I mentioned earlier, there are however two important difference between
> what you do in help-fns+ (which I just tried) and what I proposed:
> 
> 1. I do not think this can be done programmatically, the meaning of the
> proposal was to do this by adding information in docstrings manually.

I don't know what "this" is.  Programmatically adding
a link to the manuals for the symbol that's the subject
of the *Help* is already done (with `help-fns+.el').
Just what do you think can't be done programmatically?

> 2. I do think that a link to the place where the function/variable/... is
> being defined in the manual is the best solution, a link to the chapter
> would be better.  I just tried it with "kill-buffer", the additional
> information (additional wrt to the docstring) I get by entering the two
> manual sections is nil.

I don't understand.  If I click the `manuals' link
in the *Help* output (from `help-fns+.el') for
`C-h f kill-buffer' I go to the manual for that command.

By default you go to the manual per `info-lookup-symbol'.
But you can optionally instead have the link search the
indexes of any set of manuals and show you an Info Index
buffer with links to a hit in each relevant manual.

> > 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.
> 
> IMO this would not be optimal.  I think an explicit link (like the one at
> the end of the docstring of defcustom) makes it clear that if you follow
> it you leave the "built-in" documentation and open a "manual" (in another
> window).

It need not be only an either/or.  Links at `...'
naturally go to `*Help*' for their symbols.  But it
doesn't hurt to have `help-echo' tell you that, in
addition, `C-h S' takes you to the relevant part of
the Emacs or Elisp manual.

> > 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.
> 
> Yes.
> 
> > 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.
> 
> Perhaps I don't understand what you mean, but I don't see why this would
> be useful.

It would be useful for the same reason that `C-h S'
is useful anywhere.  All this is, is reminding users
(and telling those who would be unaware) that `C-h S'
takes you to the coverage of a symbol in the manual.
As someone else said earlier in this thread, that's
maybe not known widely enough.

It's like the question of why we quote and highlight
defined symbols: `...'.  We do so to let you recognize
that they're defined symbols.  This is so, independent
of the fact that we might also put a link on the symbol
(and we don't always succeed in putting a link on every
relevant occurrence, unfortunately).

> The current system (docstrings with links to other docstrings)
> works well.  If links to manual chapters are added at the end of each
> docstring, why would it be necessary to duplicate that information after
> the docstrings that refer to a given docstring?

See above.

> For example, why would it be useful to add a link (info
> "(elisp)Processes") in kill-buffer because it mentions 'process-buffer',
> when following the link on 'process-buffer' already opens (or rather,
> would open) a help buffer with a link to (info "(elisp)Processes")?

It's useful for the reason given above.

The fact that you can instead, or in addition, visit the
*Help* for that symbol, and then click its "...manual"
link to get to its doc in the manual, doesn't preclude
the usefulness of getting there directly while keeping
the same *Help* open.  The two are orthogonal, even if
they both give you a way to get to the manual.
___

What's still missing, AFAIK:

1. Ability for `info-lookup-symbol' to use an arbitrary
   set of manuals.  Eli has said this is possible, but
   it's not clear to me how.  (I haven't looked for it,
   though.)

2. Ability to get access to matches in multiple manuals.
   `help-fns+.el' lets you do that: you can be shown an
   Info Index buffer with a link for each manual with a
   match.  However:

   a. Only one match is used per manual.
   b. It's not performant: the indexes of a manual are
      searched when you click the link.  Still useful,
      but not very handy.

If `info-lookup-symbol' (or some other function) could
do both of those things in a performant way, that would
be great.