bug#31311: 27.0; doc of `pcase'

[Drew Adams <drew.adams@oracle.com>]

> It seems that no one really cares to document this facility.

I care enough about `pcase' and its doc to file this bug report.

> Maybe 'pcase' is seen as a kind of test: if you succeed in
> using and understanding it without any clear documentation,
> you are admitted to certain quarters where only wizards can enter.

If that's the approach being taken then perhaps remove all
of the doc.  If users need to resort to analyzing the code
and trying examples (tests) then perhaps no doc is better
than misleading doc.

I don't think that's the case, but if you think it is then
please remove the doc.  I think the doc is partly helpful.
But it needs fixing.  Dunno whether it is currently better
than nothing, but I think so.

> What you see in the manual is mostly the result of desperate efforts
> of a single individual to have something remotely palatable in our
> documentation.
> 
> Consequently, bug reports without patches are unlikely to yield any
> real results, IME.

Too bad.

Perhaps you can at least remove the incomprehensible and
seemingly unrelated text (I cited) that appears at the end
of the doc string, as a start.

There are also some other parts of my report that can be
acted on without any real knowledge of `pcase', I believe.