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: The poor state of documentation of pcase like things. Date: Fri, 18 Dec 2015 09:15:19 +0200 Message-ID: <83poy4xm60.fsf@gnu.org> References: <20151216202605.GA3752@acm.fritz.box> <87fuz0ydvb.fsf@russet.org.uk> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1450422921 26692 80.91.229.3 (18 Dec 2015 07:15:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 18 Dec 2015 07:15:21 +0000 (UTC) Cc: acm@muc.de, emacs-devel@gnu.org, kaushal.modi@gmail.com To: phillip.lord@russet.org.uk (Phillip Lord) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 18 08:15:15 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 1a9pFy-00029W-Jq for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 08:15:14 +0100 Original-Received: from localhost ([::1]:58720 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9pFx-00026S-KP for ged-emacs-devel@m.gmane.org; Fri, 18 Dec 2015 02:15:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56458) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9pFk-00026A-QC for emacs-devel@gnu.org; Fri, 18 Dec 2015 02:15:01 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9pFh-00084K-ID for emacs-devel@gnu.org; Fri, 18 Dec 2015 02:15:00 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:50771) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9pFh-00084F-FA; Fri, 18 Dec 2015 02:14:57 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1691 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1a9pFg-0004m6-L5; Fri, 18 Dec 2015 02:14:57 -0500 In-reply-to: <87fuz0ydvb.fsf@russet.org.uk> (phillip.lord@russet.org.uk) 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.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:196449 Archived-At: > 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 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.