From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 17 Jun 2017 15:46:58 +0300 Message-ID: <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1497703688 3563 195.159.176.226 (17 Jun 2017 12:48:08 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 17 Jun 2017 12:48:08 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:54.0) Gecko/20100101 Thunderbird/54.0 Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 17 14:48:04 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 1dMD91-0000jm-I3 for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 14:48:03 +0200 Original-Received: from localhost ([::1]:34610 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMD96-0006tl-Pg for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 08:48:08 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41210) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMD87-0006sl-NV for emacs-devel@gnu.org; Sat, 17 Jun 2017 08:47:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dMD82-0006tV-Sx for emacs-devel@gnu.org; Sat, 17 Jun 2017 08:47:07 -0400 Original-Received: from mail-wm0-x22d.google.com ([2a00:1450:400c:c09::22d]:35634) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dMD82-0006tC-L8; Sat, 17 Jun 2017 08:47:02 -0400 Original-Received: by mail-wm0-x22d.google.com with SMTP id x70so45083443wme.0; Sat, 17 Jun 2017 05:47:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=FfkgA0H1u8lIsa1UwHuwhk5u7l9NtK7MZ+i1k9wfrwo=; b=ZllYDfnrf3aCV86UAeKemf/gXOg/ATSzE7OiLqoQukcnRQ5PJA4zmpBDUOtSoEj5Ss pj66KP45rcrA6CtUnkf1iH5/VgaNxlKlMCrKwpXcyStUQTgRsVFuFx1PIpaUrsqo+wAn ZnYp6RndJMqOFNix6dBJ+6BCGC3sGr4AH8VDKeYiNQAuzWNi1RIEbh/xt9SqNvYf6j90 EozavhPuFJOwi3FQDVboPpbbj67x5zutWSXmP8Oj7aKNu2b6Zje0aazMoClzOXcO+DAy ShOi7JjoF/s94mQg+x6/GWlYnx7BAoDHcp1Aj0EBY93I2uwEHBEiL6/XGqqmlekjllQW B6AA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=FfkgA0H1u8lIsa1UwHuwhk5u7l9NtK7MZ+i1k9wfrwo=; b=tu4YwcxjTpCcQwCWh/q+1c2mUhpxRMK3Vtl5SKTgQ22JQWZz1xaxn8guIRIfjprZWW jLd2pwtagdmbhkhrfRM/c1C2iAvLtrdnk2c20cWmNO5pM8Vznl58PvQS417VO5u7gwR/ T46itaObN1ownLCHccvlTLbOTQJoKv9nkctRxgYAwHVdKHEJ+xhmgUvHfI1lpscHFR3t SYTj1zB8lPhUhZWMRsQugaKELwCsjr6L5yTSIO517O/BPxEznRBB4T3JIkZCQnNcmvcQ cAacJZqScZYb/Tkux9iP58QoXO8hAHcRcg8Kin+qdnEoSeo9TN5n/wNxiRf2/dB0TwNp C2HQ== X-Gm-Message-State: AKS2vOzvIoxakF82jSQ56cNqxXnyyK+KwJPjExU70dVVj2bvVTHjVd6j Ac3Vjn34Ry8oOCpfR3M= X-Received: by 10.28.128.198 with SMTP id b189mr9806406wmd.79.1497703621275; Sat, 17 Jun 2017 05:47:01 -0700 (PDT) Original-Received: from [192.168.1.3] ([185.105.174.193]) by smtp.googlemail.com with ESMTPSA id e14sm6009473wmi.16.2017.06.17.05.46.59 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 17 Jun 2017 05:47:00 -0700 (PDT) In-Reply-To: <83r2yw8iyu.fsf@gnu.org> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:400c:c09::22d 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:215690 Archived-At: 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.