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:27:18 -0700 (PDT) Message-ID: 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> <490eb522-8de7-43d5-820b-bb088ab7fa29@default> 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 1496845681 23292 195.159.176.226 (7 Jun 2017 14:28:01 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 7 Jun 2017 14:28:01 +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:27:57 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 1dIbwC-0005n7-9n for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 16:27:56 +0200 Original-Received: from localhost ([::1]:44305 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbwH-0001rw-IZ for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 10:28:01 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49456) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIbvj-0001rp-Ei for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:27:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIbvg-0002Mw-BP for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:27:27 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:23860) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dIbvf-0002MC-Vf for emacs-devel@gnu.org; Wed, 07 Jun 2017 10:27:24 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v57ERLQF014448 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:27:21 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v57ERKZY012173 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 7 Jun 2017 14:27:20 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v57ERJ0v009840; Wed, 7 Jun 2017 14:27:19 GMT In-Reply-To: <490eb522-8de7-43d5-820b-bb088ab7fa29@default> 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: userv0022.oracle.com [156.151.31.74] 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:215501 Archived-At: > 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. >=20 > 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. I see they've both done that now. Those who have not yet spent a long time concerned about doc would do well to listen. Doc, like helping users generally, and like lots of other things, is not so trivial. There is no silver bullet or royal road to helpful doc. Emacs deserves the best doc possible. You might say it's been lucky that it's always benefitted from strong developers who are also very concerned about doc. But it's not luck. Quality doc is in part what Emacs is about. If you're interested in Emacs then you pretty much need to be also interested in doc/help. UI development is, in principle, similar, especially free-software dev.