[Emacs-diffs] fix/bug-31311-pcase-doc 5bbbcf4 02/16: move table of PREDFUN forms into ‘pred’ item; refine

[Thien-Thi Nguyen]

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

    move table of PREDFUN forms into ‘pred’ item; refine
    
    refinements:
    - do ‘s/applied to/called on/g’ ("apply" means the function's
      last arg is taken as a list, but EXPVAL can be anything)
    - convert @item-line example into its own ‘Example’ para
    - explain ‘(= 42)’ example more
    - update reference in ‘app’ accordingly
---
 doc/lispref/control.texi | 53 +++++++++++++++++++++++++++---------------------
 1 file changed, 30 insertions(+), 23 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 23a961f..af94884 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -411,8 +411,30 @@ Matches any @var{expval}, and additionally let-binds 
@var{symbol} to
 
 @item (pred @var{predfun})
 Matches if the predicate function @var{predfun} returns address@hidden
-when called with @var{expval} as its argument.
address@hidden can be one of the possible forms described below.
+when called on @var{expval}.
address@hidden can have one of the possible forms:
+
address@hidden @asis
address@hidden function name (a symbol)
+Call the named function with one argument, @var{expval}.
+
+Example: @code{integerp}
+
address@hidden lambda expression
+Call the anonymous function with one argument,
address@hidden (@pxref{Lambda Expressions}).
+
+Example: @code{(lambda (n) (= 42 n))}
+
address@hidden function call with @var{n} args
+Call the function (the first element of the function call)
+with @var{n} arguments (the other elements) and an additional
address@hidden argument that is @var{expval}.
+
+Example: @code{(= 42)address@hidden
+In this example, the function is @code{=}, @var{n} is one, and
+the actual function call becomes: @address@hidden(= 42 @var{expval})}}.
address@hidden table
 
 @item (guard @var{boolean-expression})
 Matches if @var{boolean-expression} evaluates to address@hidden  This
@@ -456,11 +478,13 @@ U-pattern.  For example:
 @c Issue: Same as above (side-effecting EXPRESSION).
 
 @item (app @var{function} @var{upattern})
-Matches if @var{function} applied to @var{expval} returns a
-value that matches @var{upattern}.  This is like the @code{pred}
+Matches if @var{function} called on @var{expval} returns a
+value that matches @var{upattern}.
address@hidden can take one of the
+forms described for @var{predfun}, above.
+This is like the @code{pred}
 U-pattern, except that it tests the result against @var{upattern},
-rather than against a boolean truth value.  The @var{function} call can
-use one of the forms described below.
+rather than against a boolean truth value.
 @c Issue: Same as above (side-effecting FUNCTION or UPATTERN).
 
 @item (or @var{upattern1} @address@hidden)
@@ -473,23 +497,6 @@ should all bind the same symbols.
 Matches if all the argument U-patterns match.
 @end table
 
-The function calls used in the @code{pred} and @code{app} U-patterns
-can have one of the following forms:
-
address@hidden @asis
address@hidden function name (a symbol), e.g., @code{integerp}
-In this case, the named function is applied to @var{expval}.
-
address@hidden lambda expression, e.g., @code{(lambda (n) (= 42 n))}
-In this case, the lambda expression is called with one argument,
address@hidden (@pxref{Lambda Expressions}).
-
address@hidden function call with @var{n} args, e.g., @code{(= 42)}
-This is a function call with @var{n} specified arguments; the function
-is called with these @var{n} arguments and an additional @var{n}+1-th
-argument that is @var{expval}.
address@hidden table
-
 @noindent
 Here's an example of using U-patterns: