Re: Improving 'pcase' documentation

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> 1. Mention backquote patterns earlier in the 'pcase' docstring. While
>> backquote patterns are in the docstring, they're pasted after the main
>> body and not listed in the part that says, "PATTERN can take one of the
>> forms: ...". Since backquote patterns aren't immediately obvious and are
>> hard to search for, they could probably stand to get mentioned earlier.
>> (Likewise, we could do the same for the 'rx' pattern in 'pcase'.) I'm
>> not sure the best way to go about this when using 'pcase-defmacro', but
>> even just manually adding it to the main 'pcase' docstring might improve
>> matters.

I'd rather not do that.  The docstring is a reference, not a manual.
But what we could do maybe is to make it more clear that the patterns
presented first (i.e. those that in pcase's main docstring) are
"internal" (and used mostly to define higher-level patterns) and somehow
encourage people to "jump further" to see the actual higher-level
patterns.

And then arrange the ordering of those higher-level patterns so
backquote comes first (which seems to be the case here, but maybe it's
a lucky accident).

>> 2. Add a simpler conceptual summary for backquote patterns. I think you
>> could get pretty far by describing them as "running the usual
>> backquoting in reverse". That is, instead of building a list where you
>> splice values *in*, you're destructuring a list where you cut values *out*.

This "general principle" to make patterns look like calls to the
corresponding constructors should be mentioned somewhere, indeed (along
ith a caveat that it's only true for some patterns).

3-6 all sound very good.


        Stefan