From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Mon, 18 Apr 2016 11:47:17 -0400 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> <878u0bcc0b.fsf@russet.org.uk> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1460994483 27059 80.91.229.3 (18 Apr 2016 15:48:03 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Apr 2016 15:48:03 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 18 17:47:56 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 1asBOz-0005Sd-Ee for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 17:47:53 +0200 Original-Received: from localhost ([::1]:40092 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asBOy-0007dJ-Pc for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 11:47:52 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51415) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asBOg-0007b5-L3 for emacs-devel@gnu.org; Mon, 18 Apr 2016 11:47:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1asBOc-0001xY-Kq for emacs-devel@gnu.org; Mon, 18 Apr 2016 11:47:34 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:44857) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asBOc-0001vZ-EJ for emacs-devel@gnu.org; Mon, 18 Apr 2016 11:47:30 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1asBOZ-0005GV-C4 for emacs-devel@gnu.org; Mon, 18 Apr 2016 17:47:27 +0200 Original-Received: from 45.72.141.36 ([45.72.141.36]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 18 Apr 2016 17:47:27 +0200 Original-Received: from monnier by 45.72.141.36 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 18 Apr 2016 17:47:27 +0200 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 23 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: 45.72.141.36 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) Cancel-Lock: sha1:Rl28/C3hM8CBAWVvUzNJy9gA4sY= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 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:203052 Archived-At: > 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. This said, the manual was also intended to be used as a plain-old-burnable book. So if we decide to reduce the amount of "reference info" by referring to docstrings, that means we mostly give up on using lispref as a book and instead we force its use from within Emacs. I think it's an acceptable choice, but I wouldn't be surprised to hear other opinions. Stefan