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 22:39:43 +0300 Message-ID: <83r3e2905c.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> <831t62agqc.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1461008412 29131 80.91.229.3 (18 Apr 2016 19:40:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Apr 2016 19:40:12 +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 21:40:08 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 1asF1j-0006Wo-5n for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 21:40:07 +0200 Original-Received: from localhost ([::1]:44324 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asF1f-0005LY-90 for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 15:40:03 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49372) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asF1b-0005IQ-7u for emacs-devel@gnu.org; Mon, 18 Apr 2016 15:39:59 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1asF1Y-0006rd-2I for emacs-devel@gnu.org; Mon, 18 Apr 2016 15:39:59 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:54514) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asF1X-0006rZ-WD; Mon, 18 Apr 2016 15:39:56 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1936 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1asF1X-0003ZR-Bm; Mon, 18 Apr 2016 15:39:55 -0400 In-reply-to: (message from Stefan Monnier on Mon, 18 Apr 2016 15:33:20 -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:203069 Archived-At: > From: Stefan Monnier > Cc: emacs-devel@gnu.org > Date: Mon, 18 Apr 2016 15:33:20 -0400 > > >> 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. > > Maybe we could just change the manual so it's not as > complete-and-definitive, but it's still self-standing (tho with easy > ways to get more details via docstrings). I think going that way would need a way of inserting doc strings into the displayed manual, which will require some infrastructure first. Without having reference material, the manual won't be able to be self-sufficient. > > To say nothing of the fact that the current doc strings are usually > > much worse than the documentation in the manual. > > Docstrings should (ideally) always be as complete as the manual, in the > sense that the actual info is there. In practice, I find it's usually > the case. But it's often present in a much rougher shape, indeed, so > you can only figure out that info after reading the manual to figure out > what the docstring really means. Indeed, in my experience I frequently need to read the manual to make sense of the doc string.