From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 17 Jun 2017 17:10:48 +0300 Message-ID: <83mv96zouv.fsf@gnu.org> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <13fd66c8-b22b-5b87-bd8c-34dbe0c7ec38@yandex.ru> <3d5a1ca0-645f-421f-8044-f344c586705d@default> <0d081c78-3e64-4cc3-afdd-471b49f21f24@yandex.ru> <83r2yw8iyu.fsf@gnu.org> <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1497708705 21655 195.159.176.226 (17 Jun 2017 14:11:45 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 17 Jun 2017 14:11:45 +0000 (UTC) Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 17 16:11:40 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dMERv-0005Ep-LX for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 16:11:39 +0200 Original-Received: from localhost ([::1]:34912 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMERy-0004il-Vo for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 10:11:43 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53379) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMERR-0004ie-2F for emacs-devel@gnu.org; Sat, 17 Jun 2017 10:11:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dMERN-0000JK-6G for emacs-devel@gnu.org; Sat, 17 Jun 2017 10:11:09 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:41963) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMERN-0000J2-3P; Sat, 17 Jun 2017 10:11:05 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1526 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dMERM-0008CG-6F; Sat, 17 Jun 2017 10:11:04 -0400 In-reply-to: <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> (message from Dmitry Gutov on Sat, 17 Jun 2017 15:46:58 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:215695 Archived-At: > Cc: drew.adams@oracle.com, stephen_leake@stephe-leake.org, emacs-devel@gnu.org > From: Dmitry Gutov > 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.