Changes in revision 114466

Changes in revision 114466

[Eli Zaretskii]

> --- a/doc/lispref/sequences.texi	2013-01-01 09:11:05 +0000
> +++ b/doc/lispref/sequences.texi	2013-09-28 01:48:06 +0000
> @@ -713,6 +713,16 @@
>  and @code{nil} otherwise.
>  @end defun
>  
> +@c FIXME: Document these functions:
> +@c `bool-vector-exclusive-or'
> +@c `bool-vector-union'
> +@c `bool-vector-intersection'
> +@c `bool-vector-set-difference'
> +@c `bool-vector-not'
> +@c `bool-vector-subset'
> +@c `bool-vector-count-matches'
> +@c `bool-vector-count-matches-at'
> +

There's no need for this kind of FIXMEs: the NEWS entries serve that
duty.  Specifically, any NEWS entry that isn't marked with "+++" or
"---" needs to be documented before the release.

The FIXMEs you added just increase the maintenance burden, since
someone needs to remember to remove them (what if the docs is in a
place different from where you put the FIXME?).

Re: Changes in revision 114466

[Xue Fuqiao]

On Sat, Sep 28, 2013 at 3:46 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> --- a/doc/lispref/sequences.texi      2013-01-01 09:11:05 +0000
>> +++ b/doc/lispref/sequences.texi      2013-09-28 01:48:06 +0000
>> @@ -713,6 +713,16 @@
>>  and @code{nil} otherwise.
>>  @end defun
>>
>> +@c FIXME: Document these functions:
>> +@c `bool-vector-exclusive-or'
>> +@c `bool-vector-union'
>> +@c `bool-vector-intersection'
>> +@c `bool-vector-set-difference'
>> +@c `bool-vector-not'
>> +@c `bool-vector-subset'
>> +@c `bool-vector-count-matches'
>> +@c `bool-vector-count-matches-at'
>> +
>
> There's no need for this kind of FIXMEs: the NEWS entries serve that
> duty.  Specifically, any NEWS entry that isn't marked with "+++" or
> "---" needs to be documented before the release.
>
> The FIXMEs you added just increase the maintenance burden, since
> someone needs to remember to remove them (what if the docs is in a
> place different from where you put the FIXME?).

OK, I'm sorry.  I've removed them in Bzr-114475.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: Changes in revision 114466

[Eli Zaretskii]

> Date: Sun, 29 Sep 2013 06:30:46 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> On Sat, Sep 28, 2013 at 3:46 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> --- a/doc/lispref/sequences.texi      2013-01-01 09:11:05 +0000
> >> +++ b/doc/lispref/sequences.texi      2013-09-28 01:48:06 +0000
> >> @@ -713,6 +713,16 @@
> >>  and @code{nil} otherwise.
> >>  @end defun
> >>
> >> +@c FIXME: Document these functions:
> >> +@c `bool-vector-exclusive-or'
> >> +@c `bool-vector-union'
> >> +@c `bool-vector-intersection'
> >> +@c `bool-vector-set-difference'
> >> +@c `bool-vector-not'
> >> +@c `bool-vector-subset'
> >> +@c `bool-vector-count-matches'
> >> +@c `bool-vector-count-matches-at'
> >> +
> >
> > There's no need for this kind of FIXMEs: the NEWS entries serve that
> > duty.  Specifically, any NEWS entry that isn't marked with "+++" or
> > "---" needs to be documented before the release.
> >
> > The FIXMEs you added just increase the maintenance burden, since
> > someone needs to remember to remove them (what if the docs is in a
> > place different from where you put the FIXME?).
> 
> OK, I'm sorry.  I've removed them in Bzr-114475.

Nothing to be sorry about, and thank you.

Re: Changes in revision 114466

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 1384 bytes --]

() Eli Zaretskii <eliz@gnu.org>
() Sun, 29 Sep 2013 05:36:08 +0300

   > >> +@c FIXME: Document these functions:
   > >> +@c `bool-vector-exclusive-or'
   > >> +@c `bool-vector-union'
   > >> +@c `bool-vector-intersection'
   > >> +@c `bool-vector-set-difference'
   > >> +@c `bool-vector-not'
   > >> +@c `bool-vector-subset'
   > >> +@c `bool-vector-count-matches'
   > >> +@c `bool-vector-count-matches-at'

   Nothing to be sorry about, and thank you.

If the names of these functions were produced by some scanning program,
this is a good opportunity to add that code to the repo (under admin/).

If they were produced by hand, then i guess the zeroth step would be to
write a program that likewise produces them.

The overall meta-goals are to make doc coverage easy to determine for
everyone, and to render the selection criteria (for surely, some things
do not warrant "full" documentation) explicit and consequently subject
to refinement.

With this in place, the overall goal of improving the doc coverage is
most easily realizable, not just once, but also as an ongoing basis, as
Emacs gains new features over time.

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Changes in revision 114466

[Xue Fuqiao]

On Sun, Sep 29, 2013 at 3:24 PM, Thien-Thi Nguyen <ttn@gnu.org> wrote:
> () Eli Zaretskii <eliz@gnu.org>
> () Sun, 29 Sep 2013 05:36:08 +0300
>
>    > >> +@c FIXME: Document these functions:
>    > >> +@c `bool-vector-exclusive-or'
>    > >> +@c `bool-vector-union'
>    > >> +@c `bool-vector-intersection'
>    > >> +@c `bool-vector-set-difference'
>    > >> +@c `bool-vector-not'
>    > >> +@c `bool-vector-subset'
>    > >> +@c `bool-vector-count-matches'
>    > >> +@c `bool-vector-count-matches-at'
>
>    Nothing to be sorry about, and thank you.
>
> If the names of these functions were produced by some scanning program,
> this is a good opportunity to add that code to the repo (under admin/).
>
> If they were produced by hand, then i guess the zeroth step would be to
> write a program that likewise produces them.
>
> The overall meta-goals are to make doc coverage easy to determine for
> everyone, and to render the selection criteria (for surely, some things
> do not warrant "full" documentation) explicit and consequently subject
> to refinement.
>
> With this in place, the overall goal of improving the doc coverage is
> most easily realizable, not just once, but also as an ongoing basis, as
> Emacs gains new features over time.

Agreed.  The name of these functions were produced by hand.  To make doc
coverage, the only solution that I see is scanning the Emacs repo for
keywords like these:

  (def\\(var\\|const\\|custom\\)
  (def\\(un\\|subst\\|macro\\|advice\\)
  (def\\(type\\|struct\\|class\\|ine-condition\\)
  DEFUN ("
  maybe also for defgroup, defmath, defalias, cl-{defun, defmacro,
defsubst}, ...

although `defadvice' should not be used for Lisp code in Emacs proper.
But I see one problem: not every {functions, variables, ...} needs
documenting.  E.g., some functions/variables use two hyphens to separate
prefix.  These functions/variables usually don't needs documenting.

IMO every user option and every command needs documentation.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

RE: Changes in revision 114466

[Drew Adams]

> But I see one problem: not every {functions, variables, ...} needs
> documenting.  E.g., some functions/variables use two hyphens to separate
> prefix.  These functions/variables usually don't needs documenting.

Why not?  Do you think developers do not need documentation?

> IMO every user option and every command needs documentation.

IMO also.  And pretty much every function, variable, face, widget,...
Why not?

Re: Changes in revision 114466

[Stephen Berman]

On Sun, 29 Sep 2013 22:21:18 -0700 (PDT) Drew Adams <drew.adams@oracle.com> wrote:

>> But I see one problem: not every {functions, variables, ...} needs
>> documenting.  E.g., some functions/variables use two hyphens to separate
>> prefix.  These functions/variables usually don't needs documenting.
>
> Why not?  Do you think developers do not need documentation?

According to Stefan Monnier (see
http://lists.gnu.org/archive/html/emacs-devel/2013-06/msg01129.html):

   [These functions/variables are] not meant to be used by other
   packages [, which] means that something defined with "--" can
   completely change (or disappear) from one release to the other.

This suggests that developers who use them should be working on the
package they are in, hence reading and using the code and commentary of
that package.  In contrast, documentation for developers is, I think,
aimed at explaining the code's public interface to use in developing
other packages, not its private, internal only interface (at least the
documentation in the manual; such functions/variables could have doc
strings).

Steve Berman

RE: Changes in revision 114466

[Drew Adams]

> This suggests that developers who use them should be working on the
> package they are in, hence reading and using the code and commentary of
> that package.

Yes, so?  Having code does not preclude having comments.  Having comments
does not preclude having documentation.

> In contrast, documentation for developers is, I think,
> aimed at explaining the code's public interface to use in developing
> other packages, not its private, internal only interface

Not in Emacs source code, IMHO - it should not be limited to that.
Not in dynamic, accessible code that users and developers of all sorts
are invited to customize, develop, extend, or do whatever they want with.

But anyone can make code as unclear as you like, and likewise to skip
commenting or skip documenting code...

From my point of view: add a doc string at the outset. You can then
take extra time later to ponder carefully whether it might be OK to
remove the doc string, if you really want to do that.

As opposed to lazily skipping doc strings to begin with and - maybe -
thinking later whether it might not be helpful to add a doc string.

Think first of others who might use the code, and that includes
"internal" maintainers.  It can even include yourself at a later date.

> (at least the documentation in the manual; such functions/variables
> could have doc strings).

We agree.  Most functions, variables, widgets, faces,... are *not*
documented explicitly in the manuals.  And that's as it should be.

My (likely lone) opinion remains that there is rarely a good reason
to skip adding a doc string.  And when there is, pondering whether to
do that should come afterward - careful reflection, as opposed to
immediately skipping it, as a knee-jerk reaction, just because
something has `--' in its name or whatever.

It is a false economy to skip adding a doc string.  Among other things,
trying to describe succinctly what something is or does can sometimes
lead one to see that it is in fact not well designed/defined, and
could benefit from, e.g, split up, etc.  If you cannot describe it
simply, that can be a sign that there is room for improvement in the
code/design.

Just one opinion.  

Re: Changes in revision 114466

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 2266 bytes --]

() Drew Adams <drew.adams@oracle.com>
() Mon, 30 Sep 2013 08:05:04 -0700 (PDT)

   Having code does not preclude having comments.
   Having comments does not preclude having documentation.

What precludes most results is the right combination of awareness
and effort, which is in YMMV territory.  Which is obvious by:

   [...] From my point of view: [...]

   My (likely lone) opinion remains [...]

It sounds like the scanning program would do well to take options
to control its selectivity, something like:

 -i, --inclusiveness N   -- control what to include in the output;
                            N is an integer from 1 (default) to 5:
                              1 -- "public" funcs, vars
                              2 -- 1 + faces
                              3 -- 2 + properties
                              4 -- 3 + private stuff
                              5 -- everything 

Alternatively, something like:

 -f, --flag ASPECTS      -- include only ASPECTS in output;
                            ASPECTS is a comma-separated list,
                            with elements from:
                              function
                              variable
                              face
                              property
                              ...
                              ALL (same as all of the above)
 -p, --private           -- also include "private" elements
                            (those with "--" in their name)

The latter gives more control, which i like, but anyway the point
is to enable those who want to take a bite out of the doc coverage
pie to specify their appetite.  Then, ttn the lazy bum can run it
w/ ‘-f function’ and j.r.motivated-hacker can use ‘-f ALL -p’.

(Of course, what the Official Policy will be is another question.
I think for this effort (increasing doc coverage), if we focus on
clean mechanism, the need for lots of policy discussion will be
reduced -- less need to leave /home, so to speak. :-D)

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

RE: Changes in revision 114466

[Stephen J. Turnbull]

Drew Adams writes:

 > My (likely lone) opinion remains that there is rarely a good reason
 > to skip adding a doc string.

In this wide world you're not alone.  XEmacs policy has historically
been to put docstrings in everything that's "def'd" except for one-
line defsubsts and the like.  We also systematically convert leading
comments (and often comments where a docstring would go) to docstrings
more or less systematically.

On the other hand, many people (and the Emacs project, I believe) have
a policy of "docstrings document the API, if you want to know what
it's for or how it works, read the manual".  With good naming of
functions and parameters, often there is no need for a separate
description of the API.  Then the argument is that if you're going to
critically read the code anyway, the docstring means less lines of
code on screen.

I think you lose here on the basis that this is, pretty much, Emacs
policy.

Re: Changes in revision 114466

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Date: Mon, 30 Sep 2013 12:29:26 +0200
> Cc: Xue Fuqiao <xfq.free@gmail.com>, Thien-Thi Nguyen <ttn@gnu.org>,
> 	emacs-devel <emacs-devel@gnu.org>
> 
>    [These functions/variables are] not meant to be used by other
>    packages [, which] means that something defined with "--" can
>    completely change (or disappear) from one release to the other.
> 
> This suggests that developers who use them should be working on the
> package they are in, hence reading and using the code and commentary of
> that package.  In contrast, documentation for developers is, I think,
> aimed at explaining the code's public interface to use in developing
> other packages, not its private, internal only interface (at least the
> documentation in the manual; such functions/variables could have doc
> strings).

Indeed.  The ELisp manual is aimed primarily at a Lisp programmer who
develops Lisp programs, not necessarily Emacs per se.  Someone who
develops Emacs can rarely stay at the Lisp level for too long, so the
documentation needed by Emacs developers should have a radically
different orientation, and include information we currently don't have
anywhere except in the comments.

It is a good idea to have such documentation for Emacs developers, but
no one stepped forward to do the job (which is not trivial).

Re: Changes in revision 114466

[Andreas Röhler]

Am 30.09.2013 07:21, schrieb Drew Adams:
>> But I see one problem: not every {functions, variables, ...} needs
>> documenting.  E.g., some functions/variables use two hyphens to separate
>> prefix.  These functions/variables usually don't needs documenting.
>
> Why not?  Do you think developers do not need documentation?
>
>> IMO every user option and every command needs documentation.
>
> IMO also.  And pretty much every function, variable, face, widget,...
> Why not?
>
>

IMO that depends, in some cases would welcome that.

OTOH a lot is either trivial or the kind, I would want to read the code, no explanations, maybe run with edebug.

Some comments inside the code seem best than.

Re: Changes in revision 114466

[Eli Zaretskii]

> Date: Mon, 30 Sep 2013 12:55:47 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> IMO every user option and every command needs documentation.

First, the original issue that started this thread was about changes
in the ELisp manual, so user options and commands are not really
relevant.

In any case, please keep in mind the downsides of this "document
everything" attitude: it would bloat the Info manuals to humongous
proportions, for reasons that IMO are not good enough.

Here are some numbers obtained by a series of simplistic searches:

 . There are over 5000 commands in Emacs, and over 7500 defcustom's.

 . Out of these, the Emacs User Manual documents about 1400 commands
   and slightly less than 700 user options and variables.

 . Manuals in doc/misc document 2000 more commands and 2000 options.

So even if we assume that there's no duplicates between doc/emacs/ and
doc/misc/ manuals (I didn't check), a suggestion to document
everything would bloat the manual almost twofold.  If you ever saw the
User Manual in printed format, you know that it is already a very fat
book, holding several hundreds of pages.  Making it twice that would
most probably require to split it into two volumes, something that
makes both the book and its production significantly more expensive,
and actually shoots the FSF, who produces the book, in the foot,
because a larger and more expensive book will get sold less, and thus
cut the revenues even more.

The maintenance burden of maintaining twice more docs is also
something we shouldn't discount easily.  The process of updating and
reviewing the manuals before a release, especially a major release, is
already exceedingly long and painful, typically delaying the release
for many weeks.  Do we really want to make it even more painful?

Meanwhile, most of the stuff that is not in the manual has (barring
any bugs) doc strings, which document those commands and options quite
adequately, and are at users' fingertips even more readily than the
Info manual.  What exactly will we say in the manual, besides
reiterating those same doc strings, and why is that a necessity?

The only serious problem with the doc strings is that they lack the
"glue": the kind of overview and background material that we usually
put in the manual when we describe a significant topic.  So what would
probably be a good idea in order to improve the visibility of those
commands and options that are not in the manual is the following
measures:

 . Add a new manual to doc/misc/, which will be separate from the user
   manual.  In that manual, provide short descriptions of every
   package, with index entries that will make it easy to find those
   descriptions even if one doesn't know the package name, and state
   the file(s) in which the package lives.

 . Improve the doc strings so that "apropos-documentation" and other
   apropos commands would find stuff more efficiently.

I think this is a much more practical way of improving the user
documentation without incurring the kind of overhead that will be
required if we decide to "document everything".

RE: Changes in revision 114466

[Drew Adams]

> > IMO every user option and every command needs documentation.
> 
> First, the original issue that started this thread was about changes
> in the ELisp manual, 

That may be.  But the statement that every user option and command needs
documentation does not speak about manuals.  In any case, that's how I
understood it: these things need documentation.

Which they (and others, IMHO) do: doc strings.

> The only serious problem with the doc strings is that they lack the
> "glue": the kind of overview and background material that we usually
> put in the manual when we describe a significant topic.

A manual is exactly where such glue (overview, background, context,
relations) belongs.

> So what would probably be a good idea in order to improve the visibility
> of those commands and options that are not in the manual is the following
> measures:

I disagree.  We don't need such an additional manual.

Either (a) something should be documented in the manual or
(b) it does not to be documented there and doc strings suffice.

By "doc strings" (plural), I include the possibility that one doc string
refers to (links to) another.

What we might want/need (I have proposed this several times, and so have
others) is linking from doc strings to the manuals.  That would indeed be
useful, IMO.  It would provide missing glue, as you put it.

There are a very few doc strings, IIRC, that actually do this.  It would
be good to generalize it, or at least make use of it more.

Re: Changes in revision 114466

[Xue Fuqiao]

On Tue, Oct 1, 2013 at 12:38 AM, Drew Adams <drew.adams@oracle.com> wrote:
> But the statement that every user option and command needs
> documentation does not speak about manuals.  In any case, that's how I
> understood it: these things need documentation.

Sorry for being unclear.  Actually, I _do_ (and _did_) mean the
documentation in the manuals (*.texi).

> What we might want/need (I have proposed this several times, and so have
> others) is linking from doc strings to the manuals.  That would indeed be
> useful, IMO.  It would provide missing glue, as you put it.
>
> There are a very few doc strings, IIRC, that actually do this.  It would
> be good to generalize it, or at least make use of it more.

+1

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: Changes in revision 114466

[Stephen J. Turnbull]

 > On Tue, Oct 1, 2013 at 12:38 AM, Drew Adams <drew.adams@oracle.com> wrote:

 > What we might want/need (I have proposed this several times, and so have
 > others) is linking from doc strings to the manuals.  That would indeed be
 > useful, IMO.  It would provide missing glue, as you put it.
 >
 > There are a very few doc strings, IIRC, that actually do this.  It would
 > be good to generalize it, or at least make use of it more.

XEmacs has `Info-elisp-ref' which jumps to the Elisp manual entry for
a function, defaulting to the function at point.  Add a fallback to
the current docstring's function, and you're most of the way there
(the problem being that I-e-r currently doesn't know how to check
other manuals than the Lispref).

RE: Changes in revision 114466

[Drew Adams]

>  > What we might want/need (I have proposed this several times, and so have
>  > others) is linking from doc strings to the manuals.  That would indeed be
>  > useful, IMO.  It would provide missing glue, as you put it.
>  >
>  > There are a very few doc strings, IIRC, that actually do this.  It would
>  > be good to generalize it, or at least make use of it more.
> 
> XEmacs has `Info-elisp-ref' which jumps to the Elisp manual entry for
> a function, defaulting to the function at point.  Add a fallback to
> the current docstring's function, and you're most of the way there
> (the problem being that I-e-r currently doesn't know how to check
> other manuals than the Lispref).

GNU Emacs has `info-lookup-symbol', which is bound to `C-h S' globally,
so you can use it anywhere.  But users are not necessarily aware of it.
It would be good to provide explicit (visible) links for some symbols
in some doc strings.

RE: Changes in revision 114466

[Drew Adams]

> >  > What we might want/need (I have proposed this several times, and so
> >  > have others) is linking from doc strings to the manuals.  That would
> >  > indeed be useful, IMO.  It would provide missing glue, as you put it.
> >  >
> >  > There are a very few doc strings, IIRC, that actually do this.  It
> >  > would be good to generalize it, or at least make use of it more.
> >
> > XEmacs has `Info-elisp-ref' which jumps to the Elisp manual entry for
> > a function, defaulting to the function at point.  Add a fallback to
> > the current docstring's function, and you're most of the way there
> > (the problem being that I-e-r currently doesn't know how to check
> > other manuals than the Lispref).
> 
> GNU Emacs has `info-lookup-symbol', which is bound to `C-h S' globally,
> so you can use it anywhere.  But users are not necessarily aware of it.
> It would be good to provide explicit (visible) links for some symbols
> in some doc strings.

Here is a previous discussion of this, FWIW.
http://lists.gnu.org/archive/html/emacs-devel/2009-01/msg00938.html

RE: Changes in revision 114466

[Stephen J. Turnbull]

Drew Adams writes:

 > GNU Emacs has `info-lookup-symbol', which is bound to `C-h S'
 > globally, so you can use it anywhere.

Ah, we do too although it's in a package, and not bound by default.
I'll have to try this.

 > But users are not necessarily aware of it.

Isn't that what should be fixed, then?

 > It would be good to provide explicit (visible) links for some symbols
 > in some doc strings.

Which ones and which ones?  And why is that better (or easier to
achieve) than having access for all symbols in all docstrings at the
user's option?

RE: Changes in revision 114466

[Drew Adams]

>  > But users are not necessarily aware of it.
> 
> Isn't that what should be fixed, then?

1) How?  2) It's still good to provide a visual cue that a given term
is in the manual.

>  > It would be good to provide explicit (visible) links for some symbols
>  > in some doc strings.
> 
> Which ones and which ones?  

It would be a matter of judgment, case by case.  Unless you decide
that every (documented) symbol gets a link programmatically, which
might be too busy visually.  Would it be only symbols enclosed in
`...' (yes)?

Some of those are already linked to other *Help* entries, of course.
Maybe such links to the manual should be distinguished visually from
links within *Help*.

We do have links to source files, which appear the same as links
within *Help*.  But if we start adding lots of links to the manuals
for defined symbols then it might help to tell the difference from
links within *Help*.

Maybe distinguish links to the manuals using :underline with
style `wave'?  Maybe use that for any link (e.g. source file target)
that leaves *Help*?

> And why is that better (or easier to achieve) than having access
> for all symbols in all docstrings at the user's option?

Doing it automatically is no doubt easier, not harder, than doing it
using judgment case by case.

At the user's option sounds good.  Systematically might be too much
for some people.

RE: Changes in revision 114466

[Stephen J. Turnbull]

Drew Adams writes:

 >>> But users are not necessarily aware of [info-lookup-symbol].
 >> 
 >> Isn't that what should be fixed, then?
 > 
 > 1) How?

Bind C-h f and C-h v (which pretty much everybody knows and uses, I
guess) to a command that offers a menu of ways to get help on a symbol
(as a variable vs. as a function, docstring vs. manual).  Put it under
control of the old-and-cranky library (an as-yet-nonexistent novice-
like module that puts the traditional binding back when the user
invokes the command M-x im-old-and-cranky-so-put-the-binding-back).

 > 2) It's still good to provide a visual cue that a given term
 > is in the manual.

*Everything* "should" be in the manual.  It shouldn't be possible to
find a place to click in a help buffer that doesn't find offer useful
new information, IMHO.  Yes, I acknowledge that both "everything in
the manual" and "no place left to click" are hard tasks. ;-)  But
shouldn't that be our goal?

 > Maybe use that for any link (e.g. source file target) that leaves
 > *Help*?

As long as you stay in Emacs, why would one care?  C-x b *Help* RET is
hardly onerous, and if it is inconvenient, we could provide a global
C-h binding for "help-back-to-last-help".

 > Doing it automatically is no doubt easier, not harder, than doing it
 > using judgment case by case.

In that case, the prosecution rests. :-)