Re: Improving 'pcase' documentation

[Stefan Kangas]

Copying in Stefan Monnier (author of pcase.el).

Jim Porter <jporterbugs@gmail.com> writes:

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