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 18:12:18 +0300 Message-ID: <83ziss9sml.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> <8737qkcwoo.fsf@gmx.de> <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1460905994 17876 80.91.229.3 (17 Apr 2016 15:13:14 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 15:13:14 +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 17:13:02 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 1aroNi-0004CK-0B for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 17:13:02 +0200 Original-Received: from localhost ([::1]:47558 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aroNe-0006Sy-2u for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 11:12:58 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52620) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aroNL-0006PC-RH for emacs-devel@gnu.org; Sun, 17 Apr 2016 11:12:40 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aroNH-0000i6-2B for emacs-devel@gnu.org; Sun, 17 Apr 2016 11:12:39 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:50303) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aroNG-0000i2-Um; Sun, 17 Apr 2016 11:12:34 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4620 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aroNF-0003qm-R1; Sun, 17 Apr 2016 11:12:34 -0400 In-reply-to: <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> (message from Dmitry Gutov on Sun, 17 Apr 2016 14:42:28 +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:203013 Archived-At: > From: Dmitry Gutov > Date: Sun, 17 Apr 2016 14:42:28 +0300 > Cc: Glenn Morris , emacs-devel > > On 04/17/2016 02:16 PM, Michael Albinus wrote: > > > No primary or secondary. If docstring and manual are inconsistent, it is > > a bug which must be fixed. > > What's "inconsistent" in this case? They are almost always different. They can be different, but still consistent. There's more than one way to tell the same story, without contradicting the others. > > There is no automatism that the docstring is > > always right, and the manual is wrong in this case. It could be also > > vice versa. > > Wouldn't it be better if we had this "automatism"? No, not IMO. > I'm not arguing in favor of leaving mistakes in the manual. But I think > it should be strictly a derivative work. I.e. the docstrings must > contain the complete information (if maybe presented in a terse > fashion), and the manual could rephrase that, only to make it more > accessible (but not more informative). Once you allow rephrasing, you already allow deviation. And there really is no way around allowing it, because a manual that includes only the doc strings with a minimum "glue" is much less palatable. You can look at Guile as one example; GnuTLS is another. Such manuals are much less useful, IME, than what we have in Emacs. One thing that you will never find in doc strings is a discussion of merits and demerits of different ways of solving some problem, especially if such a discussion requires to jump back and forth between these ways, in order to make some point. IOW, writing a good manual is still a human activity that cannot be easily automated. Ideally, doc strings should be phrased like reference material, covering all the traits as tersely as possible, while the manual should provide an easier reading with more continuity text and even some explanations why things are the way they are. At least IMO.