Re: docstrings and elisp reference

[Eli Zaretskii]

> Cc: address@hidden, address@hidden, address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Sat, 17 Jun 2017 15:46:58 +0300
> 
> 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?

IME, by a lot.

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

Actually, I'm quite satisfied by our documentation efforts, manpower
issues notwithstanding.  Lately, all changes that need to be reflected
in the manuals come with documentation patches included.  It's clear
that some of us need to invest more efforts in writing documentation,
and their contributions need to be reviewed more thoroughly, but I
think the result is much better than it used to be, when each release
needed a lot of catching up in the manuals.  I guess we will see
whether my impression is accurate when we release the next version.

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

I don't think we have this lately.

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

Yes, because the good parts are actually written by hand.

> But I'm not sure I see the part where it's auto-generated.

Those are the *.doc files generated during the build.

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

Sometimes that is appropriate.  Other times it isn't.