Improving 'pcase' documentation

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

Re: Improving 'pcase' documentation

[Dmitry Gutov]

On 19/11/2023 22:14, Jim Porter wrote:
> Does anyone have any particular feedback on these ideas, suggestions of 
> what would be the most beneficial, etc?

I don't have much to add at the moment, but the list sounds great.

Number 6 might be more difficult to do than the rest, since we currently 
don't have any support for context-local syntax (another example would 
be 'should' forms in ert tests) in completion/font-lock, and any such 
logic would have consider the level of quoting/unquoting, but ultimately 
it can be done.

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

And that sounds like a part of more general feature where local 
variables would be highlighted with font-lock-variable-name-face and 
font-lock-variable-use-face. To determine that ,foo is a variable 
declaration (inside a pcase form or anywhere) and not just a reference, 
font-lock would have to do some macro-expansion. I wonder what would be 
the performance implications of such general approach.

Re: Improving 'pcase' documentation

[Michael Heerdegen]

Jim Porter <jporterbugs@gmail.com> writes:

> 1. Mention backquote patterns earlier in the 'pcase' docstring.

Good idea.  The current documentation tries to keep the first parts
simple, but this is also a bit demotivating and artificial (readers may
wonders what this is all good for until they see the whole picture).


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

Yes.  I came to the conclusion that it is important to outline the
design idea and the concept behind `pcase' more.  I guess this would
make the documentation a lot more accessible.

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

A clear "no" from my side.  Beginners should concentrate on basics.

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

I would find the ElDoc part most useful by far.


Thanks so far,

Michael.

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

Re: Improving 'pcase' documentation

[Stefan Monnier]

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

Re: Improving 'pcase' documentation

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > 5. Mention 'pcase' in the Lisp Intro manual?

I object strongly to this.  We should not encourage people learning
Emacs Lisp to use pcase.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)