Re: Docstrings and manuals

[Stefan Monnier]

> I think that the two should have a different purpose. I would like more
> "tutorial" information in the manual (in the sense of "here is a bit of
> code that does something with the functions we are discussing at this
> point"), while the docstrings should be the main documentation.
> For myself, I think, being able to get to the docstring easily (probably
> with a tooltip) from any occurrence of a function or variable in the
> manual would be excellent.

FWIW, I like this idea.  I think we could reduce the amount of
"reference info" in the manual (a part that's already available in the
docstrings) by referring to the docstring instead, and instead increase
the amount of explanation giving tips/examples about how to use it.

This said, the manual was also intended to be used as
a plain-old-burnable book.  So if we decide to reduce the amount of
"reference info" by referring to docstrings, that means we mostly give
up on using lispref as a book and instead we force its use from
within Emacs.  I think it's an acceptable choice, but I wouldn't be
surprised to hear other opinions.


        Stefan