RE: How to make Emacs popular again.

[Gregory Heytings]

> 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.

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.

> 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).

> > 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.

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.  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?

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")?