From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#31311: 27.0; doc of `pcase' Date: Thu, 24 May 2018 19:23:22 +0300 Message-ID: <83lgc9aupx.fsf@gnu.org> References: <83wowqrmp8.fsf@gnu.org> <87efixlv8g.fsf@web.de> <83muxlsvfm.fsf@gnu.org> <871sexlqvw.fsf@web.de> <83k1sps9n3.fsf@gnu.org> <87wowpndoo.fsf@gmail.com> <87fu3c6cm3.fsf@gnuvola.org> <83zi1kqynx.fsf@gnu.org> <871seh3yw8.fsf@gnuvola.org> <877eo9kmid.fsf@web.de> <87y3gl574j.fsf@gnuvola.org> <87po1xc5lb.fsf@web.de> <87muwz6ftl.fsf@gnuvola.org> <874lj7r5mx.fsf@web.de> <878t8e2lw1.fsf@gnuvola.org> <83in7ecrxo.fsf@gnu.org> <87r2m22ndx.fsf@gnuvola.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1527179155 19427 195.159.176.226 (24 May 2018 16:25:55 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 24 May 2018 16:25:55 +0000 (UTC) To: 31311@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu May 24 18:25:50 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fLt3m-0004y9-Hr for geb-bug-gnu-emacs@m.gmane.org; Thu, 24 May 2018 18:25:50 +0200 Original-Received: from localhost ([::1]:39685 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLt5t-0001ly-Mc for geb-bug-gnu-emacs@m.gmane.org; Thu, 24 May 2018 12:28:01 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34321) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLt28-000744-1b for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 12:24:12 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fLt22-0001JO-7A for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 12:24:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:38763) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fLt22-0001J5-2w for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 12:24:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fLt21-0003To-Ng for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 12:24:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 24 May 2018 16:24:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31311 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31311-submit@debbugs.gnu.org id=B31311.152717900413329 (code B ref 31311); Thu, 24 May 2018 16:24:01 +0000 Original-Received: (at 31311) by debbugs.gnu.org; 24 May 2018 16:23:24 +0000 Original-Received: from localhost ([127.0.0.1]:46660 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fLt1Q-0003Sv-0h for submit@debbugs.gnu.org; Thu, 24 May 2018 12:23:24 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:43054) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fLt1P-0003Sk-1S for 31311@debbugs.gnu.org; Thu, 24 May 2018 12:23:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fLt1E-0000qu-UB for 31311@debbugs.gnu.org; Thu, 24 May 2018 12:23:17 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:38142) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLt1E-0000qo-Pv for 31311@debbugs.gnu.org; Thu, 24 May 2018 12:23:12 -0400 Original-Received: from [176.228.60.248] (port=3921 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fLt1E-0004wo-8K for 31311@debbugs.gnu.org; Thu, 24 May 2018 12:23:12 -0400 In-reply-to: <87r2m22ndx.fsf@gnuvola.org> (message from Thien-Thi Nguyen on Wed, 23 May 2018 21:16:42 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:146484 Archived-At: > From: Thien-Thi Nguyen > Cc: Eli Zaretskii > Date: Wed, 23 May 2018 21:16:42 +0200 > > > +@c Issue: Should this be split off into its own > > node/subsection? > > Why is this important? > > It is important because ‘pcase’ is a construct that selects > based on new concepts: "pattern" and "matching". It also > supports defining and sharing (to some extent) let-bindings. > All the other conditional constructs select on value (squashed > to boolean, that is), and don't have any let-binding support. > > It's true that the macro eventually expands to a ‘let’-wrapped > ‘cond’, but my understanding that this expansion is an > implementation detail -- maybe in the future it will be expanded > in another more-fitting way. So, the new concepts stand on > their own, rather than "stylized expressions for a predicate in > the ‘cond’ CONDITION position". The documentation of 'pcase' is inside Conditionals not because it expands to 'cond', but because it can be perceived as a kind-of generalization of 'cond' (and the current text even says so explicitly). > The last reason is that ‘pcase’ supports "sequencing patterns", > i.e., ‘(and PAT...)’ and ‘(or PAT...)’. These are analogous to > the same-named special forms documented in "Constructs for > Combining Conditions" and the ‘pcase’ docs points that out as a > conceptual backward-direction xref. It's nice if the back-xref > is also in the text as well. The reader sees/thinks: > - conditionals / four, ok, simple, no prob > - combining conditions / two, old hat, no prob > - pcase "sequencing conditions" / two, xref AH! like ‘and’, ‘or’ > for patterns instead of for values, new hat but still no prob > > If we were to reverse the latter two (i.e., placing "Combining" > last), the reader would encounter the xref in the forward > direction. I feel strongly that it's desirable to minimize > forward references in documentation (or work really hard to make > them less disconcerting). I think you read too much into the tree-like structure of the manual, in particular it sounds like you assume many people will read all the sections of this chapter in strict depth-first order. But that is not what happens in most use cases. People usually read just the part(s) they need to understand the particular feature they need to use in their programs. When read like this, the order matters much less. What does matter is that details and "advanced" features are at lower levels, so that first reading doesn't require people to negotiate too many obstacles unnecessarily, which would prevent them from easily grasping the higher-level picture and main ideas. So I personally don't see too many serious reasons to promote this subsection to the level of a section; quite the contrary. But neither am I willing to make yet another dispute out of a minor issue such as this. If you feel strongly about this, feel free to do it. P.S. Your messages in this thread have a Mail-Followup-To header that points back to the bug address, 31311@debbugs.gnu.org. This causes Rmail to produce both To and CC headers to the bug address when I reply, and I'm forced to manually remove one of them, which is an annoyance. Would it be possible for you to avoid using that header, please? TIA.