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: Wed, 7 Jun 2017 07:05:16 -0700 (PDT) Message-ID: <490eb522-8de7-43d5-820b-bb088ab7fa29@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> 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 1496844359 4612 195.159.176.226 (7 Jun 2017 14:05:59 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 7 Jun 2017 14:05:59 +0000 (UTC) To: Dmitry Gutov , Stephen Leake , emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 07 16:05:53 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 1dIbar-0000wY-Az for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 16:05:53 +0200 Original-Received: from localhost ([::1]:44180 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbaw-0006OO-Po for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 10:05:58 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43258) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbaP-0006OH-68 for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:05:26 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIbaL-0000hQ-Vu for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:05:25 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:37715) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dIbaL-0000gr-MJ for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:05:21 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v57E5IQ2006748 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:05:19 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v57E5Ipq013177 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:05:18 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id v57E5H1q008804; Wed, 7 Jun 2017 14:05:17 GMT In-Reply-To: <0d081c78-3e64-4cc3-afdd-471b49f21f24@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: aserv0022.oracle.com [141.146.126.234] 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:215499 Archived-At: > >>> 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. >=20 > Please look up the difference between "intention" and "current situation"= . There may be some examples in the "current situation" where the doc string text and the text in the Elisp manual are identical. That is hardly how I would characterize "the current situation". Laziness and sloppiness happens. And there might even be a few cases where having the exact same text is not inappropriate. But in general the "current situation" jibes well, I think, with the "intention": doc string and manual are generally _not_ exactly the same - their presentations, and to some extent their content, are different. > > Some of the information is often the same; that's all. >=20 > That's called "duplication". INFORMATION. Yes, much of the _information_ is duplicated. Of course. Almost all of the information contained in doc strings is in the Elisp manual. The text/presentation is different. The contexts are different. The readers are often different. A reader's intention in consulting them is often different. > > 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. > > > > The Elisp doc for a command tells a Lisp programmer > > what the function and its parameters are, and > > describes their behavior. It might or might not > > mention that one of the parameters corresponds to > > the prefix arg when called interactively. >=20 > We have different manuals, with different goals. >=20 > The fact that docstrings often describe the interactive case (when it > exists) doesn't make them necessarily targeted at the end user. Just > exhaustive. The question about interactive use is a one of emphasis and audience. Interactive use is presented _first_ in doc strings. The aim in presenting it is not merely to be exhaustive. It's about whom the different docs are presented to and what the aims typically are in reading them. And yes, that involves judgment calls. We are not (and should not be) aiming only at reducing emacs-dev maintenance time. We are (and should be) aiming at the best possible help for Emacs users, including Lisp users. That involves trade-offs, of course. What it does not involve is throwing up our hands and saying "Too hard, bothersome, and error prone. Let's just write it once - one size fits all - and reuse the same thing for both Elisp manual and doc string." (As if that were a new idea...) Doc/help has been extremely important to the Emacs project since Day One. It's part of the mantra: self-documenting editor. And a lot of care and time has been spent, including by some of the most qualified and knowledgable Emacs developers, getting it right, where "right" means paying attention to the differences among the roles of doc string, Emacs manual, and Elisp manual. I'm pretty sure that those who have long held a high priority for the quality of Emacs doc, including in particular RMS and Eli, do not share a reductive, JavaDoc-like view of it. I can't speak for them, of course. Perhaps they will care to speak up; perhaps not. In any case, I've given my opinion about this: using only a JavaDoc-like approach to Emacs doc would be a step backward, not forward. That does not mean that there can never be any reuse (we do that with `apropos' functions, for example). It means that human judgment is called for.