Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: Stefan Monnier <address@hidden>
> Date: Sat, 23 Jan 2016 23:40:19 -0500
> 
> >      (pcase x
> >        ((and (pred numberp)
> >            (let (pred (lambda (x) (< 5 x)))
> >              (abs x)))
> 
> The second arg to `let' (i.e. (abs x) here) is a plain old normal
> expression, so it does not necessarily use the currently matched object
> and if it wants to, it can do it as above by simply re-using the same
> expression as was passed to `pcase'.

Yes, I know.  That's not the confusing part (although re-using 'x' in
this way muddies the waters and doesn't help).

> So (let (pred (lambda (x) (< 5 x))) (abs x)) ends up being equivalent to
> (guard (< 5 (abs x))).

Yes, because it doesn't use the feature for which 'let' was invented:
it doesn't bind any symbols to values.  And that's the confusing part:
'let' is being used where it isn't really needed, so this is not the
ideal example for the 'let' pattern.

> >   . 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
>
> I think `,PAT is a valid UPattern, which is simply equivalent to PAT.
> 
> >     or `ATOM.
> 
> And `ATOM is also a valid UPattern.

The above describes QPatterns, not UPatterns.  I also arrived at the
conclusion that we should talk about UPatterns (see how I changed the
above for the manual), but then those 2 shouldn't appear in the list
as QPatterns, they should be explained as UPatterns a QPattern can use
by unquoting them.  Which is exactly what I did in the manual.

> >     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!
> 
> Of course it does: `(A B C D ...) is 100% equivalent to
> `(A . (B . (C . (D . ...)))) and (QPAT1 . QPAT2) is a QPAT.

Which IMO means we must add the likes of `(A B C D) to the manual,
because expecting the readers of software documentation to solve
riddles as they read is not a good idea.

> >   . 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?
> 
> Very much so.

Then this, too, should be added, probably with an example.  Michael,
would you mind providing an educational example for that, please?

> >   . 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?
> 
> The docstring says:
> 
>   'VAL          matches if the object is ‘equal’ to VAL.
> 
> and 'VAL is also spelled (quote VAL).

This probably means that 'quote' shouldn't be documented as a separate
pattern, as that is a technicality which is much more likely to
confuse than to help understanding.  Unless, that is, there are
important scenarios where using (quote FOO) in a pattern is required
where it isn't a trivial replacement for 'FOO.  Do you know about such
scenarios?

Thanks.