[Emacs-diffs] fix/bug-31311-pcase-doc 567342a 2/3: move ‘Pattern-Matching Conditional’ after ‘Combining Conditions’

[Thien-Thi Nguyen]

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

    move ‘Pattern-Matching Conditional’ after ‘Combining Conditions’
    
    Since ‘pcase’ supports "sequence patterns" ‘and’ and ‘or’,
    it's more helpful to refer back to the values-processing
    analogs, than forward (IMHO).
---
 doc/lispref/control.texi | 258 +++++++++++++++++++++++------------------------
 doc/lispref/elisp.texi   |   5 +-
 2 files changed, 127 insertions(+), 136 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 4733ed1..b0cd777 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -37,8 +37,8 @@ structure constructs (@pxref{Macros}).
 @menu
 * Sequencing::             Evaluation in textual order.
 * Conditionals::           @code{if}, @code{cond}, @code{when}, @code{unless}.
-* Pattern-Matching Conditional::  @code{pcase}, @code{pcase-defmacro}, etc.
 * Combining Conditions::   @code{and}, @code{or}, @code{not}.
+* Pattern-Matching Conditional::  How to use @code{pcase} and friends.
 * Iteration::              @code{while} loops.
 * Generators::             Generic sequences and coroutines.
 * Nonlocal Exits::         Jumping out of a sequence.
@@ -289,12 +289,131 @@ For example:
 @end group
 @end example
 
address@hidden Issue: This node is between ‘Conditionals’ and ‘Combining 
Conditions’.
address@hidden        The latter describes ‘and’ and ‘or’, which have core 
pattern
address@hidden        analogs (the so-called ``sequencing patterns'').  That 
portion
address@hidden        currently xrefs ‘Combining Conditions’, a forward-ref.
address@hidden        Question: Should this section (and its subsections) be 
moved
address@hidden        after ‘Combining Conditions’ so that the xref is 
backwards?
address@hidden Combining Conditions
address@hidden Constructs for Combining Conditions
address@hidden combining conditions
+
+  This section describes three constructs that are often used together
+with @code{if} and @code{cond} to express complicated conditions.  The
+constructs @code{and} and @code{or} can also be used individually as
+kinds of multiple conditional constructs.
+
address@hidden not condition
+This function tests for the falsehood of @var{condition}.  It returns
address@hidden if @var{condition} is @code{nil}, and @code{nil} otherwise.
+The function @code{not} is identical to @code{null}, and we recommend
+using the name @code{null} if you are testing for an empty list.
address@hidden defun
+
address@hidden and address@hidden
+The @code{and} special form tests whether all the @var{conditions} are
+true.  It works by evaluating the @var{conditions} one by one in the
+order written.
+
+If any of the @var{conditions} evaluates to @code{nil}, then the result
+of the @code{and} must be @code{nil} regardless of the remaining
address@hidden; so @code{and} returns @code{nil} right away, ignoring
+the remaining @var{conditions}.
+
+If all the @var{conditions} turn out address@hidden, then the value of
+the last of them becomes the value of the @code{and} form.  Just
address@hidden(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out address@hidden  (Think
+about it; which one did not?)
+
+Here is an example.  The first condition returns the integer 1, which is
+not @code{nil}.  Similarly, the second condition returns the integer 2,
+which is not @code{nil}.  The third condition is @code{nil}, so the
+remaining condition is never evaluated.
+
address@hidden
address@hidden
+(and (print 1) (print 2) nil (print 3))
+     @print{} 1
+     @print{} 2
address@hidden nil
address@hidden group
address@hidden example
+
+Here is a more realistic example of using @code{and}:
+
address@hidden
address@hidden
+(if (and (consp foo) (eq (car foo) 'x))
+    (message "foo is a list starting with x"))
address@hidden group
address@hidden example
+
address@hidden
+Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
address@hidden, thus avoiding an error.
+
address@hidden expressions can also be written using either @code{if} or
address@hidden  Here's how:
+
address@hidden
address@hidden
+(and @var{arg1} @var{arg2} @var{arg3})
address@hidden
+(if @var{arg1} (if @var{arg2} @var{arg3}))
address@hidden
+(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
address@hidden group
address@hidden example
address@hidden defspec
+
address@hidden or address@hidden
+The @code{or} special form tests whether at least one of the
address@hidden is true.  It works by evaluating all the
address@hidden one by one in the order written.
+
+If any of the @var{conditions} evaluates to a address@hidden value, then
+the result of the @code{or} must be address@hidden; so @code{or} returns
+right away, ignoring the remaining @var{conditions}.  The value it
+returns is the address@hidden value of the condition just evaluated.
+
+If all the @var{conditions} turn out @code{nil}, then the @code{or}
+expression returns @code{nil}.  Just @code{(or)}, with no
address@hidden, returns @code{nil}, appropriate because all the
address@hidden turned out @code{nil}.  (Think about it; which one
+did not?)
+
+For example, this expression tests whether @code{x} is either
address@hidden or the integer zero:
+
address@hidden
+(or (eq x nil) (eq x 0))
address@hidden example
+
+Like the @code{and} construct, @code{or} can be written in terms of
address@hidden  For example:
+
address@hidden
address@hidden
+(or @var{arg1} @var{arg2} @var{arg3})
address@hidden
+(cond (@var{arg1})
+      (@var{arg2})
+      (@var{arg3}))
address@hidden group
address@hidden example
+
+You could almost write @code{or} in terms of @code{if}, but not quite:
+
address@hidden
address@hidden
+(if @var{arg1} @var{arg1}
+  (if @var{arg2} @var{arg2}
+    @var{arg3}))
address@hidden group
address@hidden example
+
address@hidden
+This is not completely equivalent because it can evaluate @var{arg1} or
address@hidden twice.  By contrast, @code{(or @var{arg1} @var{arg2}
address@hidden)} never evaluates any argument more than once.
address@hidden defspec
+
 @node Pattern-Matching Conditional
 @section Pattern-Matching Conditional
 @cindex pcase
@@ -1046,131 +1165,6 @@ evaluation results:
 (evaluate '(sub 1 2) nil)                 @result{} error
 @end example
 
address@hidden Combining Conditions
address@hidden Constructs for Combining Conditions
address@hidden combining conditions
-
-  This section describes three constructs that are often used together
-with @code{if} and @code{cond} to express complicated conditions.  The
-constructs @code{and} and @code{or} can also be used individually as
-kinds of multiple conditional constructs.
-
address@hidden not condition
-This function tests for the falsehood of @var{condition}.  It returns
address@hidden if @var{condition} is @code{nil}, and @code{nil} otherwise.
-The function @code{not} is identical to @code{null}, and we recommend
-using the name @code{null} if you are testing for an empty list.
address@hidden defun
-
address@hidden and address@hidden
-The @code{and} special form tests whether all the @var{conditions} are
-true.  It works by evaluating the @var{conditions} one by one in the
-order written.
-
-If any of the @var{conditions} evaluates to @code{nil}, then the result
-of the @code{and} must be @code{nil} regardless of the remaining
address@hidden; so @code{and} returns @code{nil} right away, ignoring
-the remaining @var{conditions}.
-
-If all the @var{conditions} turn out address@hidden, then the value of
-the last of them becomes the value of the @code{and} form.  Just
address@hidden(and)}, with no @var{conditions}, returns @code{t}, appropriate
-because all the @var{conditions} turned out address@hidden  (Think
-about it; which one did not?)
-
-Here is an example.  The first condition returns the integer 1, which is
-not @code{nil}.  Similarly, the second condition returns the integer 2,
-which is not @code{nil}.  The third condition is @code{nil}, so the
-remaining condition is never evaluated.
-
address@hidden
address@hidden
-(and (print 1) (print 2) nil (print 3))
-     @print{} 1
-     @print{} 2
address@hidden nil
address@hidden group
address@hidden example
-
-Here is a more realistic example of using @code{and}:
-
address@hidden
address@hidden
-(if (and (consp foo) (eq (car foo) 'x))
-    (message "foo is a list starting with x"))
address@hidden group
address@hidden example
-
address@hidden
-Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
address@hidden, thus avoiding an error.
-
address@hidden expressions can also be written using either @code{if} or
address@hidden  Here's how:
-
address@hidden
address@hidden
-(and @var{arg1} @var{arg2} @var{arg3})
address@hidden
-(if @var{arg1} (if @var{arg2} @var{arg3}))
address@hidden
-(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
address@hidden group
address@hidden example
address@hidden defspec
-
address@hidden or address@hidden
-The @code{or} special form tests whether at least one of the
address@hidden is true.  It works by evaluating all the
address@hidden one by one in the order written.
-
-If any of the @var{conditions} evaluates to a address@hidden value, then
-the result of the @code{or} must be address@hidden; so @code{or} returns
-right away, ignoring the remaining @var{conditions}.  The value it
-returns is the address@hidden value of the condition just evaluated.
-
-If all the @var{conditions} turn out @code{nil}, then the @code{or}
-expression returns @code{nil}.  Just @code{(or)}, with no
address@hidden, returns @code{nil}, appropriate because all the
address@hidden turned out @code{nil}.  (Think about it; which one
-did not?)
-
-For example, this expression tests whether @code{x} is either
address@hidden or the integer zero:
-
address@hidden
-(or (eq x nil) (eq x 0))
address@hidden example
-
-Like the @code{and} construct, @code{or} can be written in terms of
address@hidden  For example:
-
address@hidden
address@hidden
-(or @var{arg1} @var{arg2} @var{arg3})
address@hidden
-(cond (@var{arg1})
-      (@var{arg2})
-      (@var{arg3}))
address@hidden group
address@hidden example
-
-You could almost write @code{or} in terms of @code{if}, but not quite:
-
address@hidden
address@hidden
-(if @var{arg1} @var{arg1}
-  (if @var{arg2} @var{arg2}
-    @var{arg3}))
address@hidden group
address@hidden example
-
address@hidden
-This is not completely equivalent because it can evaluate @var{arg1} or
address@hidden twice.  By contrast, @code{(or @var{arg1} @var{arg2}
address@hidden)} never evaluates any argument more than once.
address@hidden defspec
-
 @node Iteration
 @section Iteration
 @cindex iteration
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index e15c92d44..6c3182b 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -475,14 +475,11 @@ Control Structures
 * Sequencing::              Evaluation in textual order.
 * Conditionals::            @code{if}, @code{cond}, @code{when}, @code{unless}.
 * Combining Conditions::    @code{and}, @code{or}, @code{not}.
+* Pattern-Matching Conditional::  How to use @code{pcase} and friends.
 * Iteration::               @code{while} loops.
 * Generators::              Generic sequences and coroutines.
 * Nonlocal Exits::          Jumping out of a sequence.
 
-Conditionals
-
-* Pattern-Matching Conditional::  How to use @code{pcase}.
-
 Nonlocal Exits
 
 * Catch and Throw::         Nonlocal exits for the program's own purposes.