From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@russet.org.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Mon, 18 Apr 2016 13:55:16 +0100 Message-ID: <878u0bcc0b.fsf@russet.org.uk> 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 X-Trace: ger.gmane.org 1460984152 13602 80.91.229.3 (18 Apr 2016 12:55:52 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Apr 2016 12:55:52 +0000 (UTC) Cc: rgm@gnu.org, emacs-devel@gnu.org, michael.albinus@gmx.de, Dmitry Gutov To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 18 14:55:42 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 1as8iH-0007WI-MS for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 14:55:37 +0200 Original-Received: from localhost ([::1]:37158 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1as8iG-0000Sa-LW for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 08:55:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50720) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1as8i5-0000Ko-1L for emacs-devel@gnu.org; Mon, 18 Apr 2016 08:55:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1as8i3-0007Cz-S9 for emacs-devel@gnu.org; Mon, 18 Apr 2016 08:55:24 -0400 Original-Received: from cloud103.planethippo.com ([31.216.48.48]:52818) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1as8hy-00076K-6w; Mon, 18 Apr 2016 08:55:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=russet.org.uk; s=default; h=Content-Type:MIME-Version:Message-ID: In-Reply-To:Date:References:Subject:Cc:To:From; bh=Km3maje1+CqeRfmmQHIoQi8DtruUpfLIeDj/9CcA2zY=; b=B6lAxjMWCPpPJkVpYShl+kukvk 7a4tq0WqRyY84VXevyNfIzEwGoSHWIgM01GkZ/133vFh0wIMrp/1wPFisokcsOPmHrjYuiSFH5RoN b6QHjKF7e01EjMfKGUCXbtjP5/gypg5yKjdV9e9y2bCeFEjpPzPPUilkzEuRVbpq5rNag8zvC//t1 UzaltnSaNNWkWh9uaK/oTwUU7swf5pLUAx1fz/OhXEsClR0pNrBM1DUYKRIU/6ybnG+AneAoW170V WSFh6ERQqfXginpEdLRI99HJ3ma2o5aYwulphRuCZ2OQeOiOfzp3oKhpQOaBvVjsNoPpQPBj6PcjB njho41ug==; Original-Received: from janus-nat-128-240-225-60.ncl.ac.uk ([128.240.225.60]:32600 helo=russet.org.uk) by cloud103.planethippo.com with esmtpsa (TLSv1.2:DHE-RSA-AES128-SHA:128) (Exim 4.86_1) (envelope-from ) id 1as8hx-0026sH-88; Mon, 18 Apr 2016 13:55:17 +0100 In-Reply-To: <83ziss9sml.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Apr 2016 18:12:18 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - cloud103.planethippo.com X-AntiAbuse: Original Domain - gnu.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - russet.org.uk X-Get-Message-Sender-Via: cloud103.planethippo.com: authenticated_id: phillip.lord@russet.org.uk X-Authenticated-Sender: cloud103.planethippo.com: phillip.lord@russet.org.uk X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 31.216.48.48 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:203041 Archived-At: Eli Zaretskii writes: >> 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. I think that the two should have a different purpose. I would like more "tutorial" information in the manual (in the sense of "here is a bit of code that does something with the functions we are discussing at this point"), while the docstrings should be the main documentation. For myself, I think, being able to get to the docstring easily (probably with a tooltip) from any occurrence of a function or variable in the manual would be excellent. Phil