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: Wed, 07 Jun 2017 08:28:25 +0300 Message-ID: <83r2yw8iyu.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> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1496813346 5544 195.159.176.226 (7 Jun 2017 05:29:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 7 Jun 2017 05:29:06 +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 Wed Jun 07 07:29:01 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 1dITWd-000180-UX for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 07:29:00 +0200 Original-Received: from localhost ([::1]:41284 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dITWj-0000Jn-6O for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 01:29:05 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59339) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dITWE-0000JW-I8 for emacs-devel@gnu.org; Wed, 07 Jun 2017 01:28:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dITWB-0001E8-Dv for emacs-devel@gnu.org; Wed, 07 Jun 2017 01:28:34 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:43257) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dITWB-0001E2-Aa; Wed, 07 Jun 2017 01:28:31 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3587 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dITWA-0006Cb-C6; Wed, 07 Jun 2017 01:28:30 -0400 In-reply-to: <0d081c78-3e64-4cc3-afdd-471b49f21f24@yandex.ru> (message from Dmitry Gutov on Wed, 7 Jun 2017 00:50:23 +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:215493 Archived-At: > From: Dmitry Gutov > Date: Wed, 7 Jun 2017 00:50:23 +0300 > > On 6/7/17 12:21 AM, Drew Adams wrote: > >>> they should not duplicate each other. > >> > >> Then you have something else in mind than the current > >> situation with documentation in Emacs. > > > > No, you do, if you think the intention now is that > > they duplicate each other. It never has been. > > Please look up the difference between "intention" and "current situation". 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. 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? > > Some of the information is often the same; that's all. > > That's called "duplication". You are overloading the meaning of "duplication". 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. > > In particular, doc strings are written as user help. > > The interactive use, if any, is typically described > > first, and from the point of an interactive user. > > Not so, the Elisp manual. > > We have different manuals, with different goals. > > The fact that docstrings often describe the interactive case (when it > exists) doesn't make them necessarily targeted at the end user. Just > exhaustive. 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.