Re: Instead of pcase

[Dmitry Gutov]

On 01/12/2023 16:44, Eli Zaretskii wrote:
> > Date: Fri, 1 Dec 2023 14:48:22 +0200
> > Cc: owinebar@gmail.com, rms@gnu.org, philipk@posteo.net, emacs-devel@gnu.org
> > From: Dmitry Gutov <dmitry@gutov.dev>
> >
> > On 01/12/2023 13:52, Eli Zaretskii wrote:
> > > If this is that easy, then why do we need no less than 120 lines to
> > > describe pcase in the doc string, and no less than 600 lines to
> > > document its features in the ELisp manual?
> >
> > Most of those describe the extensions, or additional features, which are
> > not essential to understanding the basics, to understand the examples
> > which we were looking at in this thread.
>
> This doesn't match the reality.
>
> The node "pcase Macro" holds over 400 lines.  The first 145 lines
> describe the various feature of pcase itself.  The rest are examples
> and caveats, but the very fact that we decided to have them there
> means that pcase is not easy to understand.
>
> The node "Extending pcase" is indeed about extensions, which is why I
> didn't include its line count in the number above.
>
> The node "Backquote Patterns" is actually part of the pcase
> description in the "pcase Macro" node, and was moved to a separate
> node for methodological and didactic reasons; it holds more than 100
> lines.
>
> The node "Destructuring with pcase Patterns" describes an important
> part of pcase functionality.  At least the first 45 lines of it are
> about pcase, even if you consider pcase-let etc. as "extensions".

That just reaffirms my understanding that the main problem with 'pcase' 
that we have is documentation. The nodes are written very bottom-up, 
whereas what's really needed for someone to understand the core usage, 
would look more like the first half of the node "Destructuring with 
‘pcase’ Patterns".

> So, even if you want to exclude "extensions and additional features",
> the description takes 145+100+45=290 lines, or 400+100+45=545 if you
> agree that all of the first node is documentation, not "extensions".
> That's quite a lot, and we have all that for a reason: you may
> remember the disputes and several significant edits that this section
> went through, because the original, much shorter text was deemed
> insufficient.

Looks like it's still insufficient.

Jim Porter's suggestions for improving the docs are in a separate thread 
("Improving 'pcase' documentation"), it really deserves more attention.

> > > All I'm trying to say is that
> > > there_are_  inherent problems in the DSL whose knowledge is required
> > > to understand code written using pcase, and that you and others should
> > > recognize these inherent problems are real, even though you have
> > > overcome them, and anyone could overcome them given enough time and
> > > experience.
> >
> > Most of us can agree that these DLS have associated costs.
>
> Then we agree.  I just attempted to broaden this agreement.
>
> > Whether they are "problems" (to be fixed?), meaning the costs outweigh
> > the benefits, seems to be the main theme of this thread.
>
> You read too much into the words.  "Problems" are not necessarily
> something that must be fixed, and "costs" is not necessarily something
> that need not be fixed.  Those are basically synonyms in this
> discussion.

Hopefully this clarification can bring most of the argument to a close.