From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: docstrings and elisp reference Date: Sat, 17 Jun 2017 07:52:47 -0700 (PDT) Message-ID: <89a80425-0c56-48aa-a124-b4ded2f41989@default> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1497711452 14995 195.159.176.226 (17 Jun 2017 14:57:32 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 17 Jun 2017 14:57:32 +0000 (UTC) Cc: stephen_leake@stephe-leake.org, emacs-devel@gnu.org To: Dmitry Gutov , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 17 16:57:26 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 1dMFAD-0003Vw-QC for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 16:57:26 +0200 Original-Received: from localhost ([::1]:35341 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMFAJ-0003mg-3T for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 10:57:31 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35450) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMF5x-0000Et-JN for emacs-devel@gnu.org; Sat, 17 Jun 2017 10:53:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dMF5w-0005hr-KB for emacs-devel@gnu.org; Sat, 17 Jun 2017 10:53:01 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:29155) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dMF5r-0005Tf-Nt; Sat, 17 Jun 2017 10:52:56 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v5HEqnMr019106 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 17 Jun 2017 14:52:50 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v5HEqnsr001695 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 17 Jun 2017 14:52:49 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id v5HEqnxG032718; Sat, 17 Jun 2017 14:52:49 GMT In-Reply-To: <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6767.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 156.151.31.81 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:215697 Archived-At: > > The original proposal was for a literal copying of the same =20 > > text. Drew was talking about duplicating the information, > > but expressed in a different, sometimes very different, form. >=20 > And my problem is that it's very often expressed in a very > similar form, if not copied verbatim. What is your problem with such similarity? That it is only sometimes similar and not always identical? That it is at all similar and not totally different? Sometimes there is no need for the presentation to be very different; sometimes a difference makes sense. And nothing says that every existing doc string is perfect. Those that are apparently problematic to you, because similar, might well be candidates for improvement. Their being "very similar" might be wholly appropriate, or it might just represent inattention or laziness. You seem to be missing the point that manual and doc string can have different uses and purposes. You seem to think that when they differ that's a waste, and when they are the same that's a waste because the text could have been reused automatically. Look not at the similarity or difference of this or that function description. Think about the difference in how the two can be used. It is _that_ difference that informs possible differences or similarities of text. A written news article is not a video clip. Both might tell the same story, in part or in whole, but they might well tell it differently. Same or similar message; but often different delivery/presentation. > > 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. >=20 > Drew said docstrings are mostly for the interactive case. No. I never said any such thing. You are either misreading or misrepresenting. I said: The presentation and context of use are different. The level of detail is often different. (Sometimes there is more detail in the manual; sometimes there is more in a doc string.) 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. That says nothing about doc strings being "mostly for the interactive case." It says that a doc string about a _command_ presents the command _first_ in its use as a command, that is, interactively. > That's wildly inaccurate: It's wildly inaccurate for you to say that "Drew said docstrings are mostly for the interactive case." > as an Elisp programmer, I almost always look at the > docstrings and comments, but very rarely at the manuals. > Many others do the same. We all look at doc strings. And many of us look at comments - and the code that is commented. Doc strings are typically the most immediate help for users - and that includes Lisp programmers. Doc strings are not only, or even primarily, "for the interactive case". Doc strings are not manuals, and manuals are not doc strings - that's all. They have purposes that can be different but can overlap. Doc strings are user help, including but not limited to help for non-Lisp users. Interactive use of a command is described first in a doc string because the main purpose of a command is to be used interactively. Hard to believe this is not obvious to us all, by now. Video is not newsprint. A song is not a painting. A garden is not an essay. But perhaps it is not obvious to you because, as you say, you "very rarely" consult the manuals? If doc strings and comments suffice for you, then why worry about this question at all? Is it just because _you_ don't want to be bothered maintaining the manual? If so, and if you feel that strongly, then don't bother. Someone else will do it - or it won't get done. Either way, you need not get bothered by it, if that's your problem. > my problem is that it's very often expressed in > a very similar form, if not copied verbatim. Don't worry. Emacs has always put importance on its manuals, as well as its doc strings. I hope it will long continue to do so, whoever participates in developing and maintaining it. But sure, there have always been those participants who are more, and others who are less, concerned about doc/help, including comments, doc strings, and manuals. Nothing says that each contributor needs to be equally interested in every possible way of contributing. What's wrong is to mistake one's own interests, which are typically limited (parochial), for the broader interests of Emacs as a whole. Just because you might rarely read the manuals, that's not a reason for Emacs to drop development of manuals or reduce their quality.