From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Sun, 17 Apr 2016 19:23:22 +0300 Message-ID: <83twj09pc5.fsf@gnu.org> References: <6ok2vyzwf9.fsf@fencepost.gnu.org> <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru> <87oa9dzgl0.fsf@gmx.de> <87potshczh.fsf@gmx.de> <87h9f4ghzg.fsf@gmx.de> <8737qnc8ep.fsf@gmx.de> <87k2jwd3gr.fsf_-_@gmx.de> <8dfdfe5d-41fe-7c05-0054-0bd3e589390e@yandex.ru> <831t64b7l0.fsf@gnu.org> <3c95a1a7-a334-73e7-0644-71aa0d862b50@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1460910247 15307 80.91.229.3 (17 Apr 2016 16:24:07 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 16:24:07 +0000 (UTC) Cc: rgm@gnu.org, michael.albinus@gmx.de, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 18:23:59 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1arpUM-0005Bu-Ci for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 18:23:58 +0200 Original-Received: from localhost ([::1]:48497 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpUL-0003mQ-FI for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 12:23:57 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36557) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpU6-0003iz-BW for emacs-devel@gnu.org; Sun, 17 Apr 2016 12:23:43 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arpU3-0007Vc-4w for emacs-devel@gnu.org; Sun, 17 Apr 2016 12:23:42 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:51418) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpU3-0007VY-1f; Sun, 17 Apr 2016 12:23:39 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4697 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1arpU1-00030g-Vy; Sun, 17 Apr 2016 12:23:38 -0400 In-reply-to: <3c95a1a7-a334-73e7-0644-71aa0d862b50@yandex.ru> (message from Dmitry Gutov on Sun, 17 Apr 2016 18:15:17 +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:203017 Archived-At: > Cc: michael.albinus@gmx.de, rgm@gnu.org, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Sun, 17 Apr 2016 18:15:17 +0300 > > On 04/17/2016 06:03 PM, Eli Zaretskii wrote: > > >> The `mapatoms' manual entry is neither. And yet, wouldn't you agree that > >> it's problematic? > > > > If you mean that mapatoms' doc string is too terse and omits some > > details it shouldn't, I agree. Otherwise, I'm not sure what you mean; > > please elaborate. > > That someone saw fit to put "Then it returns ‘nil’" into the manual when > it's not in the docstring. And that it's easy to make such a mistake. Making mistakes is always easier than avoiding them. I don't think this fact is significant. > >> Sure. But I think that means that we should have a policy that the > >> manual is secondary to the information contained in the source files. > > > > No, it's not secondary. It should be an expanded and augmented > > version of the same information. > > Either you're saying the same as me (when writing a manual, you > elaborate, but not add new essential new information, and thus make a > derivative), or I don't understand how to produce the manual entries. To produce a good manual text, you need to try to describe and explain the subject in some logical way. The result is not a derivative, in that it doesn't necessarily repeat the doc strings and then adds some more stuff (although doing that is sometimes TRT). It could be that most of the text of the manual section has no direct relation at all to the doc strings. It could even be an entirely different POV of looking at the subject. E.g., compare the node "Generic Functions" in the ELisp manual with the doc strings of the symbols covered by that node. As an even more extreme example, compare the node "Bidirectional Editing" in the user manual with the doc strings of the 3 variables it covers. > > Both. There's more than one way to tell the truth. > > Both of them are necessarily fallible, it seems. Of course. "To err is human".