RE: The poor state of documentation of pcase like things.

[Drew Adams]

> You can write good and bad
> pcase code, code that emphasizes what it's doing, and code that looks
> more like the result of a mechanical replacement.

+1 for that formulation: "code that emphasizes what it's doing".
When I see a `pcase' I want it to be telling me that there is
some local-binding (decomposition pattern-matching) going on.

> But I think I agree to the goal to use cl-case where possible.

> cond is a bit different,

Definitely different from `cl-case', since it does not do any
pattern-matching (except perhaps by explicit testing with a
predicate).

> since it is as powerful as pcase (in principle),

See previous - it does not do pattern-matching.  And that is
the particular "power" of `pcase' - what it really has to
offer (IMO).

> so when you see a cond, you can't assume much about what is (not) done
> there.

> pcase is not only useful when destructuring is involved (though
> it is the most important feature).

I disagree.  I think it is only useful when destructuring is
involved.  If it is just doing literal pattern-matching then
it offers nothing more than does `cl-case'.

(Unless it lets you change the equality predicate (does it?).
That's one thing that I wish `cl-case' (and Common lisp `case')
would let you do: specify something a comparer other than `eql'.)

> The often cited case of a long list of conditions that only tests for
> equality for a longer list of symbols is a good example,

I don't know what example you mean.  Do you mean testing
for equality against more than one symbol, as in multiple
`cl-case's?  Or testing the same symbol value more than once
(just use a `let')?

> but also an extreme one, because this is a case that doesn't appear
> so often in practise.
> 
> Oh, and I also think there are a lot of places in the sources that would
> get simpler when using pcase.

To vague to judge whether you are right.  But maybe so, if you
mean taking advantage of destructuring.

The same would be true of a let construct that only destructures
(e.g., `destructuring-bind').