Re: Instead of pcase

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 23 Nov 2023 20:30:27 -0800
> Cc: philipk@posteo.net, emacs-devel@gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> 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.

It depends on what you mean by "almost-trivial examples", but in
general I find trivial examples to be at best of very limited value.
First, where the use of 'pcase' is trivial, we should usually not use
'pcase' at all, but the equivalent constructs that are easier to read
and understand.  More importantly, trivial examples (the ones I have
in mind) don't add anything to the written documentation, and thus
neither help you better understand the documentation's subtle and
obscure corners nor ease specific practical tasks of writing code that
uses 'pcase' for specific purposes.  The latter is an explicit goal of
shortdocs, why we have it in the first place, so having trivial
examples there for such advanced and flexible constructs defeats its
very purpose, IMO.

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

I disagree that the shortdoc system is intended to teach by example.
Such a system must have many explanations for each example, and
shortdoc provides only a terse single-sentence description of each
example.  From where I stand, shortdoc is supposed to show real-life
examples of doing non-trivial jobs, with the intent that given a
relevant example, the reader could then go back to the documentation
and say: "ah, so that's what they meant when they talked about
so-and-so!"  IOW, shortdoc is NOT supposed to replace the
documentation, only to be a collection of examples that illustrate the
documentation.