[Emacs-diffs] fix/bug-31311-pcase-doc 5b775cf 2/2: start to rewrite ‘or’

[Thien-Thi Nguyen]

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

    start to rewrite ‘or’
    
    - similar changes as done for ‘and’
    - add Issue comment
    - add TODO comment
---
 doc/lispref/control.texi | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index b19fcdc..0a85c1a 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -410,8 +410,18 @@ and matches if @var{exprval} matches @var{pattern}.
 @var{pattern} can bind symbols to values using @var{symbol}.)
 
 @item (or @var{pattern1} @address@hidden)
-Matches if one the argument U-patterns matches.  As soon as the first
-matching U-pattern is found, the rest are not tested.  For this reason,
+Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order,
+until one of them succeeds.
+In that case, @code{or} likewise matches,
+and the rest of the sub-patterns are not tested.
+(Note that there must be at least two sub-patterns.
+Simply @address@hidden(or @var{pattern1})}} signals error.)
address@hidden Issue: Is this correct and intended?
address@hidden        Are there exceptions, qualifications?
address@hidden        (Btw, ``Please avoid it'' is a poor error message.)
+
address@hidden TODO: Pick one: (a) drop; (b) forw-ref caveat.
+For this reason,
 if any of the U-patterns let-bind symbols to the matched value, they
 should all bind the same symbols.