Re: pcase docs

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden,  address@hidden
> Date: Sat, 23 Jan 2016 13:05:22 +0100
> 
> Eli Zaretskii <address@hidden> writes:
> 
> > Sorry, I don't understand: how can knowing what 'defmacro' does help
> > to know what 'pcase-defmacro' does?
> 
> It works extremely analogous.

Maybe so, but the purpose is very different, so I think the analogy
doesn't really help.

> >   (pcase-defmacro map (&rest args)
> >     "Build a `pcase' pattern matching map elements.
> >
> >   The `pcase' pattern will match each element of PATTERN against
> >   the corresponding elements of the map.
> 
> > (btw: what PATTERN?),
> 
> the pattern that is gotten by expanding.

Expanding what?

> > As an aside, when I look at such doc strings, I always become
> > frustrated, because I must be extremely stupid to ask all these
> > questions, when no one else evidently cares, which must mean they all
> > understand this stuff, and only I alone don't, right?
> 
> Surely not!  I just had the time to read the code, carefully (I had to,
> to be able to write my el-search.el thing).  Most others don't care
> because they just don't care, I think.

But this stuff is widely used, by several different individuals.  How
do they know what to put in the code, if they, like me, are confused
about the purpose and the usage?

> Actually `pcase-defmacro' is easy to understand if you understood
> `defmacro': You define a pattern by its name and by the arguments it
> will accept.

But 'pcase' patterns don't accept any arguments, they are matched
against a value of an expression.  So how to understand "arguments" in
this context?

> When the pcase "compiler" finds a pattern that is defined as a macro, it
> substitutes the "call" with the "code" returned by evaluating the macro
> definition with the given arguments.

What do you mean by "call" here?

And how to explain that a pattern that starts with "`(list" will
somehow end up using the pattern defined with "(pcase-defmacro map"?

> Try to understand the definition of ` - it's a challenge, but if you
> succeed, you will see that things are much easier than you had expected.

Sorry, I don't want to go that way.  Understanding too much of the
implementation will "contaminate" my mind, and I will no longer be
able to see this from the POV of a Lisp programmer who needs to study
this stuff from scratch.  I want to understand it without looking
under the hood too much, then I will be able to document it in a
useful way.

Thanks.