[Top][All Lists]

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

Re: docstrings and elisp reference

From: Dmitry Gutov
Subject: Re: docstrings and elisp reference
Date: Sat, 17 Jun 2017 15:46:58 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:54.0) Gecko/20100101 Thunderbird/54.0

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.

reply via email to

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