bug#18288: pcase documentation rewrite

[Alan Mackenzie]

[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).