[Emacs-diffs] fix/bug-31311-pcase-doc 0f1c170 06/18: settle on address@hidden pcase’ text

[Thien-Thi Nguyen]

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

    settle on address@hidden pcase’ text
    
    - introduce address@hidden
    - use "Variant C" :-D
    - go w/ "body-forms" for now :-/
    - zonk original text
---
 doc/lispref/control.texi | 50 ++++++------------------------------------------
 1 file changed, 6 insertions(+), 44 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 632dc0d..91e62f8 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -308,55 +308,17 @@ 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 @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}.
+Each clause in @var{clauses} has the form:
address@hidden@code{(@var{pattern} @address@hidden)}}.
+
+Evaluate @var{expression} to determine its value, @var{expval}.
+Find the first clause in @var{clauses} whose @var{pattern} matches
address@hidden and pass control to that clause's @var{body-forms}.
 
 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
-
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
-list of the form @code{(@var{pattern} @address@hidden)}.
address@hidden tries to match the value of @var{expression} to the
address@hidden of each clause, in textual order.  If the value matches,
-the clause succeeds; @code{pcase} then evaluates its @var{body-forms},
-and returns the value of the last of @var{body-forms}.  Any remaining
address@hidden are ignored.  If no clauses match, then the @code{pcase}
-form evaluates to @code{nil}.
 @end defmac
 
 The rest of this subsection describes the builtin @var{pattern}