From: Dmitry Gutov <dgutov@yandex.ru>
To: Eli Zaretskii <eliz@gnu.org>
Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com,
emacs-devel@gnu.org
Subject: Re: docstrings and elisp reference
Date: Sat, 17 Jun 2017 15:46:58 +0300 [thread overview]
Message-ID: <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> (raw)
In-Reply-To: <83r2yw8iyu.fsf@gnu.org>
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.
next prev parent reply other threads:[~2017-06-17 12:46 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-05 21:26 docstrings and elisp reference Jean-Christophe Helary
2017-06-06 0:09 ` Tino Calancha
2017-06-06 5:10 ` Jean-Christophe Helary
2017-06-06 15:03 ` Eli Zaretskii
2017-06-06 20:25 ` Stephen Leake
2017-06-06 20:36 ` Drew Adams
2017-06-08 2:29 ` Etienne Prud’homme
2017-06-08 3:48 ` Jean-Christophe Helary
2017-06-08 5:39 ` Chad Brown
2017-06-08 8:12 ` Jean-Christophe Helary
2017-06-08 15:11 ` Eli Zaretskii
2017-06-08 15:42 ` Jean-Christophe Helary
2017-06-09 0:25 ` Chad Brown
2017-06-08 18:29 ` Etienne Prud’homme
2017-06-09 4:10 ` Richard Stallman
2017-06-08 15:18 ` Eli Zaretskii
2017-06-08 18:10 ` Etienne Prud’homme
2017-06-08 19:14 ` Eli Zaretskii
2017-06-08 20:07 ` Drew Adams
2017-06-08 20:22 ` Etienne Prud’homme
2017-06-08 22:44 ` Jean-Christophe Helary
2017-06-09 4:10 ` Richard Stallman
2017-06-09 5:20 ` Etienne Prud’homme
2017-06-09 7:08 ` Eli Zaretskii
2017-06-09 8:27 ` Yuri Khan
2017-06-09 9:38 ` Eli Zaretskii
2017-06-09 12:21 ` Eli Zaretskii
2017-06-09 12:32 ` Yuri Khan
2017-06-09 13:46 ` Eli Zaretskii
2017-06-09 19:24 ` Etienne Prud’homme
2017-06-10 1:06 ` Jean-Christophe Helary
2017-06-10 11:36 ` Nikolay Kudryavtsev
2017-06-10 14:26 ` Drew Adams
2017-06-10 3:19 ` Richard Stallman
2017-06-10 7:31 ` Eli Zaretskii
2017-06-11 2:43 ` Richard Stallman
2017-06-11 2:44 ` Richard Stallman
2017-06-11 15:18 ` Stefan Monnier
2017-06-12 2:52 ` Richard Stallman
2017-06-12 3:27 ` Stefan Monnier
2017-06-13 3:25 ` Richard Stallman
2017-06-10 8:22 ` Yuri Khan
2017-06-10 3:19 ` Richard Stallman
2017-06-06 20:45 ` Joost Kremers
2017-06-07 13:03 ` Stefan Monnier
2017-06-07 13:23 ` Yuri Khan
2017-06-07 13:31 ` Stefan Monnier
2017-06-07 14:18 ` Drew Adams
2017-06-07 15:43 ` Eli Zaretskii
2017-06-06 20:47 ` Dmitry Gutov
2017-06-06 21:21 ` Drew Adams
2017-06-06 21:50 ` Dmitry Gutov
2017-06-07 5:28 ` Eli Zaretskii
2017-06-17 12:46 ` Dmitry Gutov [this message]
2017-06-17 13:04 ` Alan Mackenzie
2017-06-17 13:55 ` Dmitry Gutov
2017-06-17 20:14 ` Alan Mackenzie
2017-06-18 2:32 ` Eli Zaretskii
2017-06-18 19:52 ` Richard Stallman
2017-06-17 22:13 ` Richard Stallman
2017-06-20 18:05 ` John Wiegley
2017-06-17 14:10 ` Eli Zaretskii
2017-06-17 15:13 ` Stefan Monnier
2017-06-17 18:59 ` Paul Eggert
2017-06-17 14:52 ` Drew Adams
2017-06-19 18:31 ` Thien-Thi Nguyen
2017-06-07 14:05 ` Drew Adams
2017-06-07 14:27 ` Drew Adams
2017-06-08 1:27 ` Richard Stallman
2017-06-06 22:42 ` Richard Stallman
2017-06-06 22:49 ` Dmitry Gutov
2017-06-07 5:20 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru \
--to=dgutov@yandex.ru \
--cc=drew.adams@oracle.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=stephen_leake@stephe-leake.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.