Re: docstrings and elisp reference

[Dmitry Gutov]

On 6/7/17 8:28 AM, Eli Zaretskii wrote:
> There is a difference, that's true.  But the fact that reality is
> different from the ideal doesn't mean we should give up the ideal, at
> least not lightly.  And we certainly should consider whether the
> alternative proposal will produce a far worse situation than what we
> have today.

Of course a carefully hand-crafted manual is best for the users. But by 
how much?

What we have now is the situation where we don't have a lot of manpower, 
and more people are interested in contributing code (and docstrings, at 
most) than there are those whole also contribute to the manual. I'm sure 
you know it all yourself.

Having some features absent from the manual can be bad enough, but the 
cases where the docstring was updated but the manual wasn't (e.g. the 
contributor didn't know where to look there for the things to update) 
are even more problematic. And yes, that possibility is created by 
duplication of information, not text (although I've seen both).

My personal "good enough" ideal is a high-level overview of a package in 
Commentary, and a set of docstrings. Sometimes that's not enough, and 
then we produce a manual that describes things in more detail and ties 
things together. I think the "more detail" part is a good indicator of 
whether we actually need a manual, aside from manuals like Elisp Into 
and Emacs Intro, of course.

> Once again, I suggest that you take a good look at
> manuals of GnuTLS and Guile, they are produced using the methodology
> that you propose.  That is our future if we go that way.  Do you
> really like the result?

Do you mean e.g. 
https://www.gnu.org/software/guile/manual/html_node/index.html?

At a brief glance, it looks well-structured and fairly readable. But I'm 
not sure I see the part where it's auto-generated.

> > That's called "duplication".
>
> You are overloading the meaning of "duplication".

It's still one of the common uses of the word.

> The original
> proposal was for a literal copying of the same text.  Drew was talking
> about duplicating the information, but expressed in a different,
> sometimes very different, form.

And my problem is that it's very often expressed in a very similar form, 
if not copied verbatim.

> This doesn't really resolve the issue pointed out by Drew.  And that
> is only one of the issues, there are others, also valid ones.

Drew said docstrings are mostly for the interactive case. That's wildly 
inaccurate: as an Elisp programmer, I almost always look at the 
docstrings and comments, but very rarely at the manuals. Many others do 
the same.