[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Stefan Monnier
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 11:47:17 -0400
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux)

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]