Re: Update of pcase docs for the elisp manual

[Andy Moreton]

On Tue 26 Jan 2016, Eli Zaretskii wrote:

>> From: John Wiegley <address@hidden>
>> Cc: Michael Heerdegen <address@hidden>,  address@hidden
>> Date: Tue, 26 Jan 2016 08:59:42 -0800
>> 
>>   - Is there any way we can get rid of the phrases QPattern and UPattern?
>>     There's decades of prior literature on pattern matching in functional
>>     languages, and none of them use "QPattern" and "UPattern". We're 
>> inventing
>>     terms that make no sense at all to newcomers, except for the 
>> single-letter
>>     correspondence with "quoted" and "unquoted". What if we just call them
>>     "quoted patterns" and "unquoted patterns", if that is what we mean?
>
> The alternatives you propose are longer, which makes it harder to
> produce palatable descriptions.  And there's a long tradition of using
> them in Emacs.
>
> But I don't own the manual; if you want to get rid of those terms, go
> ahead and make the change.
>
>>     I still vote for "literal" and "logical", since a literal pattern matches
>>     by literally being the same value as the input, while a logical pattern
>>     matches due to the logic of the pattern.
>
> AFAIU, your division into logical and literal was different from the
> division between UPatterns and QPatterns.  That's why I didn't use
> those terms.
>
>>   - The docs say "UPatterns are simpler, so we describe them first." Don't
>>     UPatterns represent the entire complexity of `pcase'?
>
> On the implementation level, yes.  But that's not really relevant for
> the documentation (except that we really should say so and give an
> example).
>
>>     How are they simpler?
>
> They are to me.  They use undecorated symbols, and don't require the
> quote/unquote games.  If that doesn't explain why they are simpler,
> then I don't know how to explain it, but the gut feeling is very real.

It seems to me that the distinction in the pcase interface is between
primitive patterns that are irreducible, and composite patterns that are
built by composing primitive patterns.

The pcase_defmacro machinery appears to offer syntactic convenience but
does not offer anything that could not be expressed more verbosely using
more primitive patterns.

The other thing that is important for documentation is that each pattern
needs to describe what the pattern matches, and what bindings are made
if the pattern matches.

Of course I am not an experienced macrologist, but an ordinary emacs
user trying to make sense of how pcase works.

Many thanks to Eli et al for trying to make all of this clearer!

    AndyM