From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Marcin Borkowski Newsgroups: gmane.emacs.devel Subject: Re: The poor state of documentation of pcase like things. Date: Fri, 18 Dec 2015 13:21:39 +0100 Message-ID: <87d1u47xrg.fsf@mbork.pl> References: <20151216202605.GA3752@acm.fritz.box> <87fuz0ydvb.fsf@russet.org.uk> <83poy4xm60.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1450441377 26999 80.91.229.3 (18 Dec 2015 12:22:57 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 18 Dec 2015 12:22:57 +0000 (UTC) Cc: kaushal.modi@gmail.com, acm@muc.de, emacs-devel@gnu.org, Phillip Lord To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 18 13:22:43 2015 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 1a9u3Q-0002II-UX for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 13:22:37 +0100 Original-Received: from localhost ([::1]:59928 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9u3P-0004ZO-TJ for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 07:22:35 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45423) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9u2o-0004Qm-L2 for emacs-devel@gnu.org; Fri, 18 Dec 2015 07:21:59 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9u2m-0005i6-33 for emacs-devel@gnu.org; Fri, 18 Dec 2015 07:21:57 -0500 Original-Received: from mail.mojserwer.eu ([2a01:5e00:2:52::8]:53772) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9u2i-0005hQ-9G; Fri, 18 Dec 2015 07:21:52 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by mail.mojserwer.eu (Postfix) with ESMTP id D6A2D8F201C; Fri, 18 Dec 2015 13:21:49 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mail.mojserwer.eu Original-Received: from mail.mojserwer.eu ([127.0.0.1]) by localhost (mail.mojserwer.eu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Sl--R6k4iaXz; Fri, 18 Dec 2015 13:21:40 +0100 (CET) Original-Received: from localhost (unknown [109.232.24.28]) by mail.mojserwer.eu (Postfix) with ESMTPSA id DBB9B8F2016; Fri, 18 Dec 2015 13:21:39 +0100 (CET) User-agent: mu4e 0.9.13; emacs 25.0.50.1 In-reply-to: <83poy4xm60.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2a01:5e00:2:52::8 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:196468 Archived-At: On 2015-12-18, at 08:15, Eli Zaretskii wrote: >> From: phillip.lord@russet.org.uk (Phillip Lord) >> Date: Thu, 17 Dec 2015 21:16:56 +0000 >> Cc: Alan Mackenzie , Emacs developers >> >> Could I suggest [pcase] be promoted in the manual a >> little. Currently, it's a subnode of "conditionals", but pattern >> match is really a form of control flow in its own right. > > If that's your itch, feel free to scratch it. > > IMO, that's largely a waste of your time and energy: the manual is > rarely if ever read in its entirety, or even in large portions. Most Well, I did read most of it some time ago (15 years?). Then, I mainly relied on NEWS, `C-s' and `i' in the manual. I'd love to read the whole manual again some day - I like it - but it's soo time-consuming... > of its uses is to quickly find the subject whose description you need, > hopefully by using the Info-index command ("i TOPIC RET"), and read > that and perhaps some of the cross-references there. With this use > case, the level on which a description is found is irrelevant. > > Btw, the importance is in the eyes of the beholder. You look at that > through the glasses of someone who hacks Emacs core. Try to take the > POV of a casual Lisper who just wants to put some advanced > customizations in her ~/.emacs, for example. IOW, advanced features > and subjects are frequently very important to power users, but much > less so to "mere mortals". The manual is supposed to serve both types > of audience. > > Bottom line: what we do need is make the description clear and > complete. Where it appears is orders of magnitude less important. Agreed. -- Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski Faculty of Mathematics and Computer Science Adam Mickiewicz University