Re: Instead of pcase

[Jim Porter]

On 11/23/2023 7:34 PM, Richard Stallman wrote:
>    > >>           > (`(,hookfun . (,start ,end ,collection . ,plist))
>    > > I was not sure which part of the line that rule applies to.
>    > >
>    > >>           > (`(,hookfun ,start ,end ,collection . ,plist)
>    > > Would that be equiva;ent?
>
> I as a reader, trying to understand what that pcase construct did, did
> not know they would be equivalent.  So this specific piece of
> cleverness specifically interfered with my understanding that example
> and therefore with my trying to understand pcase.

For cases like this, I hope to (at least partially) address it with 
better documentation. I'm not sure we can expect every instance of 
'pcase' in the Emacs codebase to be a good teachable example for how to 
use 'pcase', but I do think we could achieve that with shortdocs. The 
shortdocs could start small with almost-trivial examples, and then build 
up to more-complex forms that show how the pieces interact.

Broadly, my goal would be that anyone who already knows Lisp could load 
up the shortdocs for pcase and get the hang of 95% of it in a few minutes.

(I also think we could improve the manuals and the docstring, but I 
think 'pcase' is a great candidate for teaching by example. The shortdoc 
system seems ideal for that.)