[Emacs-diffs] fix/bug-31311-pcase-doc 8929957 5/6: explode first address@hidden pcase’ para

[Thien-Thi Nguyen]

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

    explode first address@hidden pcase’ para
    
    some meta-stylistic notes:
    - the "Issue" comments are TBD, hopefully w/ input from others
    - the "R" means "rationale"
    - the original text will go away
---
 doc/lispref/control.texi | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 3640ee3..9e3a89e 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -308,7 +308,50 @@ literal value (for comparisons to literal values you'd use
 @code{cond}), or it can be a more general description of the expected
 structure of the expression's value.
 
address@hidden Issue: Personally, i'd prefer to ‘s/body-forms/body/g’, but maybe
address@hidden        consistency w/ the ‘cond’ docs is more important.  Hmm.  
--ttn
+
 @defmac pcase expression &rest clauses
+Each clause has the form: @code{(@var{pattern} @address@hidden)}.
address@hidden R: Describing structure early (near the @def) helps chunking.
address@hidden    (Indeed, for simple forms, the @def line is sufficient.)
address@hidden    Qs answered:
address@hidden    (a) What are the parts?
address@hidden    (b) What are their names?
address@hidden    (c) What is the un-named support structure (syntax)?
address@hidden Issue: Whether or not to include ``... in @var{clauses} ...''.
+
address@hidden Variant A
address@hidden R: Key words are ``attempt'' and ``in order'',
address@hidden    which clearly conveys the iterative nature.
+Evaluate @var{expression}, attempt to match the value of
address@hidden with the @var{pattern} of each clause in order,
+and pass control to @var{body-forms} of the clause that matches.
+
address@hidden Variant B
address@hidden R: Better flow (to the author's ear), but perhaps iterative
address@hidden    nature (implied by ``first'') too easy to overlook.
address@hidden    OTOH, key word ``successful'' hints at possibility of
address@hidden    failure, which implies ``attempt'' at something.
address@hidden    What could that something be, but a search (iterative)?
+Evaluate @var{expression} and pass control to @var{body-forms}
+of the first clause in @var{clauses} whose @var{pattern}
+is a successful match for the value of @var{expression}.
+
+If there is a match, the value of @code{pcase} is the value
+of the last of @var{body-forms} in the successful clause.
+Otherwise, @code{pcase} evaluates to @code{nil}.
address@hidden See, using ``body'' instead of ``body-forms'' allows for:
address@hidden   If there is a match, the value of @code{pcase} is the value
address@hidden   of the last @var{body} form in the successful clause.
address@hidden which could surely be further improved...  /whine  --ttn
+
+Depending on the pattern, a match may provide additional
+bindings (@pxref{Dynamic Binding}),
+during the evaluation of @var{body-forms}.
address@hidden Issue: ∃ (better xref target)?
+
address@hidden Original text.
 Evaluate @var{expression} and choose among an arbitrary number of
 alternatives based on the value of @var{expression}.  The possible
 alternatives are specified by @var{clauses}, each of which must be a