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: Mon, 18 Apr 2016 21:56:11 +0300 Message-ID: <831t62agqc.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> <83ziss9sml.fsf@gnu.org> <878u0bcc0b.fsf@russet.org.uk> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1461005798 19866 80.91.229.3 (18 Apr 2016 18:56:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Apr 2016 18:56:38 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 18 20:56:34 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 1asELZ-0004Rh-Iu for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 20:56:33 +0200 Original-Received: from localhost ([::1]:43728 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asELZ-0001S3-2g for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 14:56:33 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36735) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asELV-0001P7-8J for emacs-devel@gnu.org; Mon, 18 Apr 2016 14:56:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1asELQ-0007u7-6l for emacs-devel@gnu.org; Mon, 18 Apr 2016 14:56:29 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:53741) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asELQ-0007tv-3y; Mon, 18 Apr 2016 14:56:24 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1890 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1asELP-0001qY-Fa; Mon, 18 Apr 2016 14:56:23 -0400 In-reply-to: (message from Stefan Monnier on Mon, 18 Apr 2016 11:47:17 -0400) 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:203064 Archived-At: > From: Stefan Monnier > Date: Mon, 18 Apr 2016 11:47:17 -0400 > > > 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. > > FWIW, I like this idea. I think we could reduce the amount of > "reference info" in the manual (a part that's already available in the > docstrings) by referring to the docstring instead, and instead increase > the amount of explanation giving tips/examples about how to use it. Then the manual will be a very awkward reading, even on-line. To say nothing of the fact that the current doc strings are usually much worse than the documentation in the manual. IOW, let's first make sure every changeset is accompanied by good documentation, and only then consider such significant changes.