bug#31311: 27.0; doc of `pcase'

[Eli Zaretskii <eliz@gnu.org>]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Wed, 23 May 2018 21:16:42 +0200
> 
>    >  +@c Issue: Should this be split off into its own
>    >  node/subsection?
> 
>    Why is this important?
> 
> It is important because ‘pcase’ is a construct that selects
> based on new concepts: "pattern" and "matching".  It also
> supports defining and sharing (to some extent) let-bindings.
> All the other conditional constructs select on value (squashed
> to boolean, that is), and don't have any let-binding support.
> 
> It's true that the macro eventually expands to a ‘let’-wrapped
> ‘cond’, but my understanding that this expansion is an
> implementation detail -- maybe in the future it will be expanded
> in another more-fitting way.  So, the new concepts stand on
> their own, rather than "stylized expressions for a predicate in
> the ‘cond’ CONDITION position".

The documentation of 'pcase' is inside Conditionals not because it
expands to 'cond', but because it can be perceived as a kind-of
generalization of 'cond' (and the current text even says so
explicitly).

> The last reason is that ‘pcase’ supports "sequencing patterns",
> i.e., ‘(and PAT...)’ and ‘(or PAT...)’.  These are analogous to
> the same-named special forms documented in "Constructs for
> Combining Conditions" and the ‘pcase’ docs points that out as a
> conceptual backward-direction xref.  It's nice if the back-xref
> is also in the text as well.  The reader sees/thinks:
> - conditionals / four, ok, simple, no prob
> - combining conditions / two, old hat, no prob
> - pcase "sequencing conditions" / two, xref AH! like ‘and’, ‘or’
>   for patterns instead of for values, new hat but still no prob
> 
> If we were to reverse the latter two (i.e., placing "Combining"
> last), the reader would encounter the xref in the forward
> direction.  I feel strongly that it's desirable to minimize
> forward references in documentation (or work really hard to make
> them less disconcerting).

I think you read too much into the tree-like structure of the manual,
in particular it sounds like you assume many people will read all the
sections of this chapter in strict depth-first order.

But that is not what happens in most use cases.  People usually read
just the part(s) they need to understand the particular feature they
need to use in their programs.  When read like this, the order matters
much less.  What does matter is that details and "advanced" features
are at lower levels, so that first reading doesn't require people to
negotiate too many obstacles unnecessarily, which would prevent them
from easily grasping the higher-level picture and main ideas.

So I personally don't see too many serious reasons to promote this
subsection to the level of a section; quite the contrary.  But neither
am I willing to make yet another dispute out of a minor issue such as
this.  If you feel strongly about this, feel free to do it.

P.S.  Your messages in this thread have a Mail-Followup-To header that
points back to the bug address, 31311@debbugs.gnu.org.  This causes
Rmail to produce both To and CC headers to the bug address when I
reply, and I'm forced to manually remove one of them, which is an
annoyance.  Would it be possible for you to avoid using that header,
please?  TIA.