[Emacs-diffs] fix/bug-31311-pcase-doc-squash 468e827 2/3: Mention cl-case explicitly

[Thien-Thi Nguyen]

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

    Mention cl-case explicitly
    
    * doc/lispref/control.texi (Pattern-Matching Conditional)
    (pcase Macro): ...here.  Also, convert attempt to be funny
    to explicit statement of reasoning process.
---
 doc/lispref/control.texi | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 4c5df34..112a331 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -423,7 +423,7 @@ This is not completely equivalent because it can evaluate 
@var{arg1} or
 
 Aside from the four basic conditional forms, Emacs Lisp also
 has a pattern-matching conditional form, the @code{pcase} macro,
-a hybrid of @code{cond} and @code{case}
+a hybrid of @code{cond} and @code{cl-case}
 (@pxref{Conditionals,,,cl,Common Lisp Extensions})
 that overcomes their limitations and introduces
 the @dfn{pattern matching} programming style.
@@ -439,10 +439,10 @@ are not available to the clause's @var{body-forms}.
 Another annoyance (more an inconvenience than a limitation)
 is that when a series of @var{condition} predicates implement
 equality tests, there is a lot of repeated code.
-For that, why not use @code{case}?
+For that, why not use @code{cl-case}?
 
 @item
-The @code{case} macro chooses among alternatives by evaluating
+The @code{cl-case} macro chooses among alternatives by evaluating
 the equality of its first argument against a set of specific
 values.
 The limitations are two-fold:
@@ -453,14 +453,15 @@ The limitations are two-fold:
 @end enumerate
 
 @noindent
-These render @code{case} unsuitable for strings or compound
+These render @code{cl-case} unsuitable for strings or compound
 data structures (e.g., lists or vectors).
-For that, why not use @code{cond}?  Wait, what?  @dots{}
+For that, why not use @code{cond}?
+(And here we end up in a circle.)
 @end itemize
 
 @noindent
 Conceptually, the @code{pcase} macro borrows the first-arg focus
-of @code{case} and the clause-processing flow of @code{cond},
+of @code{cl-case} and the clause-processing flow of @code{cond},
 replacing @var{condition} with a generalization of
 the equality test called @dfn{matching},
 and adding facilities so that you can concisely express a
@@ -614,10 +615,10 @@ they @emph{must} all bind the same set of symbols.
 @end table
 
 @anchor{pcase-example-0}
address@hidden Example: Advantage Over @code{case}
address@hidden Example: Advantage Over @code{cl-case}
 
 Here's an example that highlights some advantages @code{pcase}
-has over @code{case}
+has over @code{cl-case}
 (@pxref{Conditionals,,,cl,Common Lisp Extensions}).
 
 @example
@@ -641,9 +642,9 @@ has over @code{case}
 @end example
 
 @noindent
-With @code{case}, you would need to explicitly declare a local
+With @code{cl-case}, you would need to explicitly declare a local
 variable @code{code} to hold the return value of @code{get-return-code}.
-Also @code{case} is difficult to use with strings because it
+Also @code{cl-case} is difficult to use with strings because it
 uses @code{eql} for comparison.
 
 @anchor{pcase-example-1}