Re: Update of pcase docs for the elisp manual

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 24 Jan 2016 18:17:10 -0500
> 
> >> >   . 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.
> 
> Yes, the ` pcase-macro introduces a new kind of patterns (the
> QPatterns) which are those that appear under the ` .
> 
> So when I say that `ATOM is a valid UPattern, it means that ATOM is
> a valid QPattern.  And similarly when I say that "`,PAT is a valid
> UPattern" it means that ",PAT" is a valid QPattern.

What I wrote in the manual uses the reverse notation: QPatterns
_include_ the backquote.  The reason for adopting this notation was
that every time QPatterns are used, the backquote is there.  So IMO
the description makes more sense the way I wrote it.

> The QPattern and UPattern languages are not mutually exclusive: you
> can't tell by looking at a pattern if it's a QPattern or a UPattern.
> Instead, the context (whether it's within a ` or not) determines which
> of the two is expected.

That's not an important distinction for using the languages, IMO.  I
understand how it can be important for someone who knows the
implementation very well.

> >> 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.
> 
> Agreed.  Not needed for the docstring (which is more meant as
> a reference for people who already know how it works, and needs to be
> both exhaustive and concise), but useful for the manual.

My quotation was not from the doc string, but from Michael's tutorial.

> >> >   . 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.
> 
> Just like the (A B C) vs (A . (B . (C . nil))) issue, 'A is one and the
> same as (quote A), so it's definitely not a separate pattern.

We can certainly point out the difference between A and 'A in this
context, but I see no reason to document 'quote' as a separate pattern.

> > 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.
> 
> A macro (such as pcase) can never distinguish 'A from (quote A) since
> the reader returns exactly the same result either way.

Sorry, is that a no?