[Emacs-diffs] fix/bug-31311-pcase-doc 6abf621 5/9: add subsection ‘Extending @code{pcase}’

[Thien-Thi Nguyen]

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

    add subsection ‘Extending @code{pcase}’
    
    - node name: ‘Extending pcase’
    - add to menu in node ‘Conditionals’
    - add xref from ‘Pattern-Matching Conditional’
    - add several @cindex entries
    - populate
      - add intro para
        - xref back to ‘Pattern-Matching Conditional’
        - introduce/define "backquote-style patterns"
        - mention "structural matching"
      - move address@hidden pcase-defmacro’ following
      - move all of `QPAT stuff following
---
 doc/lispref/control.texi | 47 +++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index e3c3568..58c9a81 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -290,6 +290,7 @@ For example:
 
 @menu
 * Pattern-Matching Conditional::
+* Extending @code{pcase}: Extending pcase.
 @end menu
 
 @node Pattern-Matching Conditional
@@ -304,7 +305,7 @@ For example:
 This subsection describes the @code{pcase} macro,
 a hybrid of @code{cond} and @code{case}
 that overcomes their limitations.
address@hidden ...and saving the universe... :-D
+For advanced usage information, @xref{Extending pcase}.
 
 @itemize
 @item The @code{cond} form chooses among alternatives
@@ -756,6 +757,35 @@ and @var{function} (in @code{pred} and @code{app}).
 @c (what does it mean?)
 @end enumerate
 
address@hidden Extending pcase
address@hidden Extending @code{pcase}
address@hidden pcase, defining new kinds of pattern
address@hidden pattern matching, structural
address@hidden structural pattern matching
+
+The @code{pcase} macro supports several kinds of patterns
+(@pxref{Pattern-Matching Conditional}).
+You can add support for other kinds of patterns
+using the @code{pcase-defmacro} macro.
+This subsection describes @code{pcase-defmacro} and
address@hidden patterns}, a set of builtin patterns
+that eases structural matching.  (These patterns were
+defined with @code{pcase-defmacro}.)
+
address@hidden Hmm, shouldn't this be named ‘pcase-defpattern’?
address@hidden I suppose it's too late now....  --ttn
address@hidden pcase-defmacro name args [doc] &rest body
+Define a new kind of pattern for @code{pcase}.  The new pattern will
+be invoked as @code{(@var{name} @var{actual-args})}.  The @var{body}
+should describe how to rewrite the pattern @var{name} into some other
+pattern.  The rewriting will be the result of evaluating @var{body}
+in an environment where @var{args} are bound to @var{actual-args}.
+
+For documentation consistency, use @code{EXPVAL}
+in @var{doc}, the docstring, to stand for the result of
+evaluating @var{expression} (first arg to @code{pcase}).
address@hidden defmac
+
 In addition, you can use backquoted patterns that are more powerful.
 They allow matching @var{expval} against specifications of its
 @emph{structure}.  For example, you can specify that the value must be
@@ -841,21 +871,6 @@ evaluation results:
 (evaluate '(sub 1 2) nil)                 ;=> error
 @end example
 
-Additional patterns can be defined using the @code{pcase-defmacro}
-macro.
-
address@hidden pcase-defmacro name args [doc] &rest body
-Define a new kind of pattern for @code{pcase}.  The new pattern will
-be invoked as @code{(@var{name} @var{actual-args})}.  The @var{body}
-should describe how to rewrite the pattern @var{name} into some other
-pattern.  The rewriting will be the result of evaluating @var{body}
-in an environment where @var{args} are bound to @var{actual-args}.
-
-For documentation consistency, use @code{EXPVAL}
-in @var{doc}, the docstring, to stand for the result of
-evaluating @var{expression} (first arg to @code{pcase}).
address@hidden defmac
-
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions