From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 17 Jun 2017 13:04:35 +0000 Message-ID: <20170617130435.GA2955@acm.fritz.box> 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=us-ascii X-Trace: blaine.gmane.org 1497704787 26488 195.159.176.226 (17 Jun 2017 13:06:27 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 17 Jun 2017 13:06:27 +0000 (UTC) User-Agent: Mutt/1.5.24 (2015-08-30) Cc: Eli Zaretskii , 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 Sat Jun 17 15:06:20 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 1dMDQh-0006SE-Qt for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 15:06:19 +0200 Original-Received: from localhost ([::1]:34657 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMDQn-00032G-10 for ged-emacs-devel@m.gmane.org; Sat, 17 Jun 2017 09:06:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43672) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMDQA-00031z-Jn for emacs-devel@gnu.org; Sat, 17 Jun 2017 09:05:47 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dMDQ7-0008Jt-D5 for emacs-devel@gnu.org; Sat, 17 Jun 2017 09:05:46 -0400 Original-Received: from ocolin.muc.de ([193.149.48.4]:20954 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1dMDQ7-0008JS-65 for emacs-devel@gnu.org; Sat, 17 Jun 2017 09:05:43 -0400 Original-Received: (qmail 86348 invoked by uid 3782); 17 Jun 2017 13:05:40 -0000 Original-Received: from acm.muc.de (p548C72DB.dip0.t-ipconnect.de [84.140.114.219]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sat, 17 Jun 2017 15:05:39 +0200 Original-Received: (qmail 2997 invoked by uid 1000); 17 Jun 2017 13:04:35 -0000 Content-Disposition: inline In-Reply-To: <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.4 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:215691 Archived-At: Hello, Dmitry. On Sat, Jun 17, 2017 at 15:46:58 +0300, Dmitry Gutov wrote: > 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. Are we really all that short of manpower? Compared with the Emacs project in times past? My impression is that most contributors here do their best to update the manuals wrt their contributions. [ .... ] > 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. For what it's worth, I read the Elisp manual frequently. I value its style, its content and its readability. I also attempt to update it and the Emacs manual each time I make pertinent changes. It was the quality of these manuals which lead me greatly to prefer Emacs over XEmacs around 15 years ago. -- Alan Mackenzie (Nuremberg, Germany).