bug#31311: 27.0; doc of `pcase'

[Thien-Thi Nguyen]

() Eli Zaretskii <eliz@gnu.org>
() Wed, 23 May 2018 18:28:19 +0300

   >  +@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".

Also, ‘pcase’ is the only conditional construct that takes a
first arg and evaluates it (like ‘case’).  The new text explains
its hybrid nature (‘cond’ and ‘case’) in more detail.

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

   You can always add subsections, subsubsections, etc., if you
   want to structure the text into more parts than it is
   already.

In branch ‘fix/bug-31311-pcase-doc’ (note, not -squash), commit
567342a88e53 does such a re-arranging.  If you prefer, i can
demote everything one level and move it back to "Conditionals".
I'd then need to update that node's intro para to say "five".
That might reduce the diff, too.

However, i have explained (above) why i would be against this.

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)
   (pcase (context query)
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

signature.asc
Description: PGP signature