[Emacs-diffs] fix/bug-31311-pcase-doc e0cda90 7/9: rework ‘evaluate’ explanation

[Thien-Thi Nguyen]

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

    rework ‘evaluate’ explanation
    
    - split into two paras
      - start each para by naming the kind of pattern
      - 1st: backquote-style patterns
      - 2nd: core patterns
    - (1st para) use "clause" for ‘call’, ‘fn’
    - replace "pattern checks/matches and DOES-EVALUATION" w/
      "pattern checks/matches; body DOES-EVALUATION"
    - (2nd para) reword to use "match"
---
 doc/lispref/control.texi | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 5f9aa03..df1d516 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -852,15 +852,22 @@ requires lexical binding, @pxref{Lexical Binding}):
 @end example
 
 @noindent
-Here @code{`(add ,x ,y)} is a pattern that checks that @code{form} is a
-three-element list starting with the literal symbol @code{add}, then
-extracts the second and third elements and binds them to the variables
address@hidden and @code{y}.  Then it evaluates @code{x} and @code{y} and
-adds the results.  The @code{call} and @code{fn} patterns similarly
-implement two flavors of function calls.  @code{(pred numberp)} is a
-pattern that simply checks that @code{form} is a number and if so,
-evaluates it.  @code{(pred symbolp)} matches symbols, and returns
-their association.  Finally, @code{_} is the catch-all pattern that
+Here, the first three clauses use backquote-style patterns.
address@hidden(add ,x ,y)} is a pattern that checks that @code{form}
+is a three-element list starting with the literal symbol @code{add},
+then extracts the second and third elements and binds them
+to symbols @code{x} and @code{y}, respectively.
+The clause body evaluates @code{x} and @code{y} and adds the results.
+Similarly, the @code{call} clause implements a function call,
+and the @code{fn} clause implements an anonymous function definition.
+
+The remaining clauses use core patterns.
address@hidden(pred numberp)} matches if @code{form} is a number.
+On match, the body evaluates it.
address@hidden(pred symbolp)} matches if @code{form} is a symbol.
+On match, the body looks up the symbol in @code{env} and
+returns its association.
+Finally, @code{_} is the catch-all pattern that
 matches anything, so it's suitable for reporting syntax errors.
 
 Here are some sample programs in this small language, including their