Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: John Wiegley <address@hidden>
> Cc: Eli Zaretskii <address@hidden>
> Date: Fri, 22 Jan 2016 10:03:55 -0800
> 
> Below is an update to the pcase.texi I sent earlier, with Michael's
> corrections.

Thanks.

> Eli, I'm not sure the Texinfo here is even sane.

Texinfo is the least of our problems in this and similar cases.

I updated the docs, thanks to both of you.  I used your text, John,
and also Michael's pcase-guide.el as the starting points, source of
inspiration and examples, and sometimes source of swaths of text as
well.  I also used what was already in the manual.  The end result,
for which I accept full responsibility (although you are named as
co-authors), is in the repository; please take a look and comment,
modify, and improve as appropriate.  In particular, the UPattern
example needs to be improved as the comment there says, please do so
if you have time.

Some subtle points that I still don't regard as resolved in a
satisfactory manner:

  . The description of the 'let' pattern is not entirely clear.
    Michael's examples actually confused me instead of helping to
    understand it, because the examples use the same symbol for the
    1st arg of 'pcase' and for symbols that are UPatterns (and also in
    other contexts).  Example:

     (pcase x
       ((and (pred numberp)
             (let (pred (lambda (x) (< 5 x)))
               (abs x)))
        t)
       (_ nil))

    The documentation of 'let' says that it matches if the expression
    matches the pattern.  Here, the expression is "(abs x)" and the
    pattern is "(pred (lambda (x) (< 5 x)))", right?  So how can they
    "match"?  The fact that 'x' is used here in no less than 3
    different contexts doesn't help, either.  I actually don't
    understand the "(abs x)" part at all, since 'x' was not bound to
    anything by any previous pattern.  AFAIU, the 1st argument of
    'pcase' cannot be used like that, because it will not be a symbol
    in the general case, it's an expression whose value is not bound
    to anything.

    The sharp-eyed among you might notice that the documentation of
    the 'let' pattern is somewhat vague -- the above is the reason.

  . The exact syntax and possible forms of QPatterns are described
    ambiguously and seemingly incompletely, and profoundly contradict
    almost every given example of them.  Both Michael and the previous
    manual text describe them as follows:

     The form is `QPAT where QPAT is one of the following:

       (QPAT1 . QPAT2)
       [QPAT1 QPAT2 ... QPATn]
       ,PAT
       ATOM

    The last two look wrong: AFAIU, there is no QPattern of the form
    `,PATH or `ATOM.  These 2 seem to be _components_ or QPatterns,
    see below.

    The examples are terribly confusing.  They all use this form:

     `(A B C D ...)

    where each of A, B, etc. can be one of:

     - ,UPAT
     - ATOM

    And yet this pattern doesn't appear at all in the possible forms
    of QPAT above!

  . Many of the examples using QPatterns seem to allow to be easily
    rewritten to use only UPatterns, by adding additional 'pred' and
    'guard' conditions.  Is that true?  If so, we should tell this
    somewhere, because otherwise the reader might think she
    misunderstood something very important.  I did, because none of
    the texts I've seen in preparation for this work discusses this
    aspect.  Take this, for example:

     (pcase x
       (`("foo")         t)
       (`("foo" ,a)      a)
       (`("foo" . ,(and (pred listp) rest)) rest))

    What do we have here that cannot be done with UPatterns?

  . Last, but not least: NEWS says we now have a new UPattern 'quote',
    but neither John, nor Michael or the doc strings mention this
    pattern.  What did I miss?

Thanks.