Improving 'pcase' documentation

[Jim Porter]

(Separate thread from the other 'pcase' thread since that thread is 
getting hard to follow for me now.)

On the discussion of 'pcase', I notice that one of the issues people 
have mentioned a few times is that the documentation is insufficient, at 
least compared to how intuitive the syntax is ("not very", for some 
people). To that end, I think it would be worth improving these 
deficiencies so that it's easier for someone unfamiliar with 'pcase' to 
understand it (at least well enough to maintain ordinary uses of 'pcase').

Here are some areas I think we could improve. There may be more:

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.

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

3. Add shortdoc examples for 'pcase', including some common ways to 
combine patterns. Starting simple and then building to something more 
complex would show how the pieces fit together, and would (hopefully) 
make it the syntax clear since you can see the final form all together.

4. Improve the reference manual. We could move the examples in the 
'pcase' documentation to a separate subnode, and add a couple of simpler 
examples first. That way, we can again introduce 'pcase' by example a 
bit more gradually. We could also change how we introduce 'pcase' in the 
main "Pattern-Matching Conditional" node. Currently, it compares the 
relative benefits of 'pcase', 'cond', and 'cl-case'; that's useful and 
informative, but maybe not as the very first introduction to 'pcase'. 
What about describing what "pattern matching programming style" means, 
show a brief example, and then move onto the rest of the documentation? 
The comparison with 'cond' and 'cl-case' could be the last subnode of 
the section.

5. Mention 'pcase' in the Lisp Intro manual? A beginner's guide to 
'pcase' could make sense in the Lisp Intro, and while we wouldn't have 
to cover everything, it would at minimum alert readers to the fact that 
it exists, and the basics of how 'pcase' works.

6. Improve editing support. I'm not sure how feasible this is, but it 
would be nice if Emacs understood 'pcase' better when editing. For 
example, font-lock support on the various macro forms; Emacs already 
font-locks the 'or' pattern, but only because 'or' is font-locked 
normally. It would be nice if the same applied to 'pred', 'guard', etc. 
Similarly, ElDoc and Help (C-h f) could do the right thing inside 
'pcase', providing us with the appropriate documentation. (I also think 
it'd be nice to font-lock anything that looks like ",SYMBOL", even 
outside of 'pcase', but maybe others would find that annoying.)

Does anyone have any particular feedback on these ideas, suggestions of 
what would be the most beneficial, etc?

- Jim