From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#18288: pcase documentation rewrite Date: Sat, 23 Aug 2014 14:57:05 +0000 (UTC) Organization: muc.de e.V. Message-ID: References: NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1408806410 23695 80.91.229.3 (23 Aug 2014 15:06:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Aug 2014 15:06:50 +0000 (UTC) To: gnu-emacs-bug@moderators.isc.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Aug 23 17:06:43 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1XLCts-0007PR-Ha for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Aug 2014 17:06:40 +0200 Original-Received: from localhost ([::1]:41467 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCtr-0008RI-TR for geb-bug-gnu-emacs@m.gmane.org; Sat, 23 Aug 2014 11:06:39 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39334) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCsT-0008Lr-6G for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:05:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XLCsJ-0005Tj-8C for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:05:13 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:43327) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCsJ-0005T9-5E for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:05:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1XLCsI-00008M-9a for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:05:02 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 23 Aug 2014 15:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 18288 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: moreinfo Original-Received: via spool by submit@debbugs.gnu.org id=B.1408806255409 (code B ref -1); Sat, 23 Aug 2014 15:05:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 23 Aug 2014 15:04:15 +0000 Original-Received: from localhost ([127.0.0.1]:50270 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XLCrW-00006V-Vj for submit@debbugs.gnu.org; Sat, 23 Aug 2014 11:04:15 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:37519) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XLCrU-00006A-Vj for submit@debbugs.gnu.org; Sat, 23 Aug 2014 11:04:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XLCrI-0005FI-Tl for submit@debbugs.gnu.org; Sat, 23 Aug 2014 11:04:07 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:49571) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCrI-0005FE-RE for submit@debbugs.gnu.org; Sat, 23 Aug 2014 11:04:00 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39223) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCrC-0008Cs-I0 for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:04:00 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XLCr6-0005Eg-KS for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:03:54 -0400 Original-Received: from xvm-90.mit.edu ([18.181.2.90]:39188 helo=mod-relay.xvm.mit.edu) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XLCr6-0005Ea-Hb for bug-gnu-emacs@gnu.org; Sat, 23 Aug 2014 11:03:48 -0400 Original-Received: by mod-relay.xvm.mit.edu (Postfix) id 2189221190; Sat, 23 Aug 2014 11:03:47 -0400 (EDT) Original-Received: from mail.muc.de (colin.muc.de [193.149.48.1]) by mod-relay.xvm.mit.edu (Postfix) with ESMTP id CBB2E1EF42 for ; Sat, 23 Aug 2014 11:03:46 -0400 (EDT) Original-Received: (qmail 14676 invoked by uid 8); 23 Aug 2014 14:57:05 -0000 Original-Path: not-for-mail Original-Newsgroups: gnu.emacs.bug Original-Lines: 87 Original-NNTP-Posting-Host: news.muc.de Original-X-Trace: colin.muc.de 1408805825 14674 193.149.48.2 (23 Aug 2014 14:57:05 GMT) Original-X-Complaints-To: news-admin@muc.de Original-NNTP-Posting-Date: Sat, 23 Aug 2014 14:57:05 +0000 (UTC) User-Agent: tin/2.2.0-20131224 ("Lochindaal") (UNIX) (FreeBSD/8.4-RELEASE (amd64)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-Mailman-Approved-At: Sat, 23 Aug 2014 11:06:37 -0400 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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:92622 Archived-At: [1}Tassilo Horn wrote: >Mario Valencia writes: >Hi Mario, >> The documentation in '(elisp) Pattern matching case statement' is very >> difficult to understand. Could somebody please rewrite it so mere >> mortals can read it? >Could you be a bit more specific? What exactly is difficult to >understand? What further questions do you still have after reading the >docs? OK, I'll bite. I think the OP was quite clear - he was utterly unable to understand the page at all, so asking him for "further questions" is not helpful. After trying to read that info page several times over the last few months, I've still only got a vague idea of how to use pcase, so I have to agree with the OP. Here are some of the things that are wrong: (i) Bug: ".... and then compare the value against _each_ UPATTERN ...." is surely wrong - it will compare the value only against _some_ UPATTERNs, stopping when a match is found. Surely? (ii) "UPATTERN" and "QPATTERN" have no definitions - only the relationship between them is sketched, not what they _are_. This makes is difficult to get a conceptual handle on everything. (iii) In the first example ("(pcase (get-return-code x) ...)") it is entirely unclear why the symbols there are quoted with backquote. Why not just with quote? (iv) It would seem that the reader macros backquote and comma mean something different in the pcase construct from their normal meanings. This desperately needs explicitly stating and emphasising, and early on. What about ",@"? (v) The meaning and rules for the idiosyncratic backquote and comma need to be rigorously and explicitly documented. (vi) Where, if anywhere, inside a pcase construct can standard backquote be used? (vii) "The UPATTERN mentioned above are ..." is a singlular noun with a plural verb. (viii) [In the "definition" of QPATTERN] "The intention is to mimic the backquote macro: this pattern matches those values that COULD HAVE BEEN BUILT BY SUCH A BACKQUOTE EXPRESSION" is very vague. What on earth is "could" supposed to mean here? In what parallel universe might those values have been built? "the backquote macro" could be confusing - there would seem to be (at least) two distinct backquote macros; perhaps the word "standard" should be inserted before "backquote". (ix) [Carrying on from (viii)] "Since we're pattern matching rather than building a value, the unquote does not indicate where to plug an expression, but .....". This is so bad as to be painful to dissect. o - What does "building a value" here mean? o - What's an "unquote"? Throughout the Elisp manual "unquoted" means "not being quoted by '". Is "backquote" meant here? o - What does "plug an expression" (at a place) mean? (x) [Carrying on from (ix)] "... but instead it lets one specifiy a U-pattern that should match the value at that location". Which "location"? What does "location" even mean? What "value"? (xi) It would be really nice if "QPATTERN" were defined. (xii) [First paragraph] "the macro `pcase' can come handy", should be "... can come IN handy". (xiii) Why is the "don't care" symbol "_" rather that t? This should be explained. The entire page is wishy-washy and vague. I think it probably makes good sense to somebody who already knows how pcase works. As I said, I haven't grasped the pcase mechanism enough even to be able to criticize the info page properly. It would seem readers are expected to absorb the details of pcase by osmosis rather than systematic reading. >Bye, >Tassilo -- Alan Mackenzie (Nuremberg, Germany).