[Emacs-diffs] fix/bug-31311-pcase-doc 3f614b6 7/8: rewrite intro

[Thien-Thi Nguyen]

branch: fix/bug-31311-pcase-doc
commit 3f614b606184a954bbca043e02138b68468c67a5
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>

    rewrite intro
    
    - split one para into two
    - first para
      - add Issue comment
      - mention "hybrid" of ‘cond’, ‘case’
      - summarize ‘cond’ operation, limitations
      - likewise for ‘case’
      - explain what ‘pcase’ inherits, adds
      - define "matching"
    - second para
      - define "pattern"
      - show commutivity of "matches" (P m V, V m P)
---
 doc/lispref/control.texi | 61 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 51 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 6375d01..f2751c3 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -297,16 +297,57 @@ For example:
 @cindex pcase
 @cindex pattern matching
 
-The @code{cond} form lets you choose between alternatives using
-predicate conditions that compare values of expressions against
-specific values known and written in advance.  However, sometimes it
-is useful to select alternatives based on more general conditions that
-distinguish between broad classes of values.  The @code{pcase} macro
-allows you to choose between alternatives based on matching the value
-of an expression against a series of patterns.  A pattern can be a
-literal value (for comparisons to literal values you'd use
address@hidden), or it can be a more general description of the expected
-structure of the expression's value.
address@hidden Issue: I use ‘case’ w/ the thought that it being an alias
address@hidden        to ‘cl-case’ is an ``implementation detail''.
address@hidden        (However, below i use ‘cl-case’ explicitly.  Hmmm.)
address@hidden        Is this okay?
+This subsection describes the @code{pcase} macro,
+a hybrid of @code{cond} and @code{case}
+that overcomes their limitations.
address@hidden ...and saving the universe... :-D
+
address@hidden
address@hidden The @code{cond} form chooses among alternatives
+by evaluating the predicate @var{condition} of each
+of its clauses (@pxref{Conditionals}).
+The primary limitation is that variables let-bound in @var{condition}
+are not available to the clause's @var{body-forms}.
+
+Another annoyance (more an inconvenience than a limitation)
+is that when a series of @var{condition} predicates implement
+equality tests, there is a lot of repeated code.
+For that, why not use @code{case}?
+
address@hidden
+The @code{case} macro chooses among alternatives by evaluating
+the equality of its first argument against a set of specific
+values (@pxref{Conditionals,,,cl,Common Lisp Extensions}).
+The limitations are two-fold:
+
address@hidden
address@hidden The equality tests use @code{eql}.
address@hidden The values must be known and written in advance.
address@hidden enumerate
+
address@hidden
+These render @code{case} unsuitable for strings or compound
+data structures (e.g., lists or vectors).
+For that, why not use @code{cond}?  Wait, what?  @dots{}
address@hidden itemize
+
address@hidden
+Conceptually, the @code{pcase} macro borrows the first-arg focus
+of @code{case} and the clause-processing flow of @code{cond},
+replacing @var{condition} with a generalization of
+``equality test'' called @dfn{matching},
+and adding facilities so that you can concisely express a
+clause's predicate, and arrange to share let-bindings between
+a clause's predicate and @var{body-forms}.
+
+The concise expression of a predicate is known as a @dfn{pattern}.
+When the predicate, called on the value of the first arg,
+returns address@hidden, the pattern matches the value
+(or sometimes ``the value matches the pattern'').
 
 @defmac pcase expression &rest clauses
 Each clause in @var{clauses} has the form: