bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description

["Mattias Engdegård" <mattiase@acm.org>]

[-- Attachment #1: Type: text/plain, Size: 1454 bytes --]

27 dec. 2023 kl. 22.47 skrev Stefan Kangas <stefankangas@gmail.com>:

>> Please consider moving the description of `rx' forms from after the
>> description of SEQPAT forms (`and' and `or').  The scope of the latter
>> description is less clear if `rx' follows the descriptions of `and' and
>> `or' (with no particular separation).  IOW, separate the SEQPAT
>> description from the other pattern descriptions better.
> 
> Mattias, since you added that part, do you have any thoughts?

The location of the `rx` pattern description is fine; it's the SEQPAT paragraph that causes trouble as it splits the table into two parts.

I suggest we remove that paragraph because it doesn't actually say anything useful at that point; the user can learn how `or` and `and` patterns work without knowing that they are SEQPATs. Actually, I'd hoist those two patterns and reorder them to keep patterns in a rough order of usage: something like

  pred, guard, or, and, let, app, rx

makes more sense -- `pred` and `guard` clearly belong together, `app` is less common than `let`.

We could explain SEQPAT in a short sentence somewhere else, either near the beginning of the node or further down in the 'Caveats' subsection. A simple (and probably flawed) patch attached.

Stefan M probably has a better sense of how to improve the text. (By the way, the caveat section says that sequencing patterns use `eq` for comparison. Don't they use `eql`?)


[-- Attachment #2: seqpat.diff --]
[-- Type: application/octet-stream, Size: 3400 bytes --]

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index d4bd8c14ae3..2c0caacbc17 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -640,37 +640,9 @@ pcase Macro
 the actual function call becomes: @w{@code{(= 42 @var{expval})}}.
 @end table
 
-@item (app @var{function} @var{pattern})
-Matches if @var{function} called on @var{expval} returns a
-value that matches @var{pattern}.
-@var{function} can take one of the forms described for @code{pred},
-above.  Unlike @code{pred}, however, @code{app} tests the result
-against @var{pattern}, rather than against a boolean truth value.
-
 @item (guard @var{boolean-expression})
 Matches if @var{boolean-expression} evaluates to non-@code{nil}.
 
-@item (let @var{pattern} @var{expr})
-Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval}
-matches @var{pattern}.  (It is called @code{let} because @var{pattern}
-can bind symbols to values using @var{symbol}.)
-@end table
-
-@cindex sequencing pattern
-A @dfn{sequencing pattern} (also known as @var{seqpat}) is a
-pattern that processes its sub-pattern arguments in sequence.
-There are two for @code{pcase}: @code{and} and @code{or}.
-They behave in a similar manner to the special forms
-that share their name (@pxref{Combining Conditions}),
-but instead of processing values, they process sub-patterns.
-
-@table @code
-@item (and @var{pattern1}@dots{})
-Attempts to match @var{pattern1}@dots{}, in order, until one of them
-fails to match.  In that case, @code{and} likewise fails to match, and
-the rest of the sub-patterns are not tested.  If all sub-patterns
-match, @code{and} matches.
-
 @item (or @var{pattern1} @var{pattern2}@dots{})
 Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order,
 until one of them succeeds.  In that case, @code{or} likewise matches,
@@ -685,6 +657,24 @@ pcase Macro
 variables bound by each sub-pattern.  If a variable is not bound by
 the sub-pattern that matched, then it is bound to @code{nil}.
 
+@item (and @var{pattern1}@dots{})
+Attempts to match @var{pattern1}@dots{}, in order, until one of them
+fails to match.  In that case, @code{and} likewise fails to match, and
+the rest of the sub-patterns are not tested.  If all sub-patterns
+match, @code{and} matches.
+
+@item (app @var{function} @var{pattern})
+Matches if @var{function} called on @var{expval} returns a
+value that matches @var{pattern}.
+@var{function} can take one of the forms described for @code{pred},
+above.  Unlike @code{pred}, however, @code{app} tests the result
+against @var{pattern}, rather than against a boolean truth value.
+
+@item (let @var{pattern} @var{expr})
+Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval}
+matches @var{pattern}.  (It is called @code{let} because @var{pattern}
+can bind symbols to values using @var{symbol}.)
+
 @ifnottex
 @anchor{rx in pcase}
 @item (rx @var{rx-expr}@dots{})
@@ -881,9 +871,10 @@ pcase Macro
 @anchor{pcase-symbol-caveats}
 @subheading Caveats for @var{symbol} in Sequencing Patterns
 
-The preceding examples all use sequencing patterns
-which include the @var{symbol}
-sub-pattern in some way.
+@cindex sequencing pattern
+The preceding examples all use @dfn{sequencing patterns}
+(@code{and} and @code{or} patterns)
+which include the @var{symbol} sub-pattern in some way.
 Here are some important details about that usage.
 
 @enumerate