From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Docstrings and manuals Date: Sun, 17 Apr 2016 08:54:33 -0700 (PDT) Message-ID: 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>> <<83ziss9sml.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1460908523 22283 80.91.229.3 (17 Apr 2016 15:55:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 15:55:23 +0000 (UTC) Cc: rgm@gnu.org, michael.albinus@gmx.de, emacs-devel@gnu.org To: Eli Zaretskii , Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 17:55:11 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 1arp2S-0007dB-F5 for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 17:55:08 +0200 Original-Received: from localhost ([::1]:48136 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arp2O-0001Iw-I9 for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 11:55:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60495) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arp28-0001FS-Hw for emacs-devel@gnu.org; Sun, 17 Apr 2016 11:54:49 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arp27-0001XQ-C2 for emacs-devel@gnu.org; Sun, 17 Apr 2016 11:54:48 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:37840) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arp23-0001Wu-Ev; Sun, 17 Apr 2016 11:54:43 -0400 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u3HFsc42022076 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 17 Apr 2016 15:54:38 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0021.oracle.com (8.13.8/8.13.8) with ESMTP id u3HFsbNH024082 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 17 Apr 2016 15:54:37 GMT Original-Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id u3HFsX9g020787; Sun, 17 Apr 2016 15:54:33 GMT In-Reply-To: <<83ziss9sml.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6744.5000 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] 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:203016 Archived-At: > > > 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. >=20 > They can be different, but still consistent. There's more than one > way to tell the same story, without contradicting the others. >=20 > > > 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"? >=20 > No, not IMO. >=20 > > 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). >=20 > 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. >=20 > 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. >=20 > 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. +10 to what Eli and Michael are saying. Neither doc string nor manual serves the purpose of the other. The manual is not Javadoc. It is up to humans to write the most appropriate text for each, and to make coherent any differences in message or presentation. Differences should be based on the context (including readers) and should not involve contradiction in meaning (semantics, behavior) of the things described. IOW, both need to be faithful descriptions of those things. There can be differences in degree of abstraction or of precision. But within a given level of abstraction/precision, each must be a faithful picture of the behavior it describes. The same is true of any other communication about these things to users, including tooltips and error messages: The behavior/meaning of the program being described is the same, and that needs to be reflected in a lack of contradiction wrt description of that behavior/meaning.