Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: Andy Moreton <address@hidden>
> Date: Tue, 26 Jan 2016 19:58:30 +0000
> 
> >>   - 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.

That's one possible way of looking at the issue.  But to me it doesn't
make a lot of sense, because when I learn a new tool, I don't
necessarily want to study its internal design right there and then.
First, I want to learn to use it.  And for that, the required mental
model doesn't need to reflect the internals too closely, and doesn't
have to be mathematically rigorous.  It just needs to make sense.

> 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.

I hope that's exactly what I did.

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

I tried to look at the issue through the eyes of such a user.