Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: John Wiegley <address@hidden>,  address@hidden
> Date: Mon, 25 Jan 2016 15:15:14 +0100
> 
> Dunno if it's a good example at all.  But since just binding a symbol is
> better done with just SYMBOL as pattern, I wanted to provide an example
> that shows a different use case.

I understand.  I'm just saying that it would be better to provide an
example of using 'let' which actually made use of the reason for its
introduction: binding symbols to values.

> 
> >     The sharp-eyed among you might notice that the documentation of
> >     the 'let' pattern is somewhat vague -- the above is the reason.
> 
> Sorry, I've lost my orientation.  What is the reason?

My confusion when I tried to take apart the 'let' example.

> >   . 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.
> 
> Did Stefan make it clear for you?

Like I said: he made it clear that you use a different "language"
here, the opposite of what I used.

> Everything involving QPatterns can be expressed without them.  So I'm
> not sure what you mean.

I only talked about the examples I've seen, and I said explicitly "can
be _easily_ rewritten to use only UPatterns".  The "easily" part is
important.  IOW, when we show examples of QPatterns that can be too
easily rewritten without QPatterns, we should at least say in a side
note that this is possible, that we nevertheless provide such examples
just for brevity, and perhaps try avoiding such _easily_ rewritable
examples altogether.  IME, text that begs some question should answer
that question right there and then, otherwise the reader is left with
an impression that she didn't fully understand something important.