RE: docstrings and elisp reference

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

> - Better integration between the manual browser and the docstring
>   browser, so you can click on a function/variable name in the manual to
>   get to its docstring and you can easily jump from a docstring to the
>   relevant section of the manual.

Yes, 100%.  I've long argued that.  Cross-reference, not text reuse.

And Emacs has already come a fair distance in that direction.  It
could still be improved.

> - Remove the redundant var/fun documentation from the manual (this is
>   a tedious job: there is some redundance but it's not systematic, so
>   we can't just do this removal systematically).

We should not remove redundant _information_, if there is a
reason that it will help readers.  And that's the case for 99.9%
of the var/fun presentations in the manual.  There is often a
discussion about whether a given var/fun should be explicitly
doc'd in the manual - it's a judgment call.  It's not because
we _can_ add the doc for a var/fun to the manual that we should.

Think redundancy NOT for maintainers (I'm not saying you did that)
but for readers.

A reader should be _able_ to click to go to additional info
or to a different presentation/orientation of the same material.

But it is important, IMO, for the manual to have the information
that it has, even when that means that the same information is
provided also elsewhere (e.g. in a doc string).  We lose, do not
gain, if we decide to remove the doc for a given function etc.
from the manual just because it has a doc string - or vice versa.

The question of redundancy _for the user_ means that we also do
not, in general, want to have exactly the same text in doc string
and manual.  A user does not want to click a function name in one
or the other, only to end up seeing exactly the same text in the
other location.

"Reuse" for readers is generally a negative - it means reading
the same thing again, generally without being forewarned.
Little is more frustrating for a reader.  ("Why did you send me
here?  This is the same text!")

That is not to say that repetition in doc is always negative.
Far from it.  It's about judgment: repeat when there is a good
(e.g. pedagogical) reason to repeat.

> - Come up with a way to re-add those var/fun documentation into the
>   printed manual (e.g. by adding to the Texinfo source external
>   references to docstrings, which are then processed by now ad-hoc
>   script).

Not a good idea, IMO.  See above.