* bug#18288: pcase documentation rewrite
[not found] ` <mailman.7179.1408349599.1147.bug-gnu-emacs@gnu.org>
@ 2014-08-23 14:57 ` Alan Mackenzie
0 siblings, 0 replies; 3+ messages in thread
From: Alan Mackenzie @ 2014-08-23 14:57 UTC (permalink / raw)
To: gnu-emacs-bug
[1}Tassilo Horn <tsdh@gnu.org> wrote:
>Mario Valencia <mariovalspi@gmail.com> 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).
^ permalink raw reply [flat|nested] 3+ messages in thread