[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Improving 'pcase' documentation

From: Jim Porter
Subject: Improving 'pcase' documentation
Date: Sun, 19 Nov 2023 12:14:39 -0800

(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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]