[Emacs-diffs] fix/bug-31311-pcase-doc 4f5f3eb 4/5: reorg ‘Pattern-Matching Conditional’

[Thien-Thi Nguyen]

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

    reorg ‘Pattern-Matching Conditional’
    
    - promote to section
      - add entry to ‘Control Structures’ menu
      - drop entries from ‘Conditionals’ menu
      - add Issue
      - zonk MAINTAINME
      - rewrite intro
        - mention "four basic conditional forms"
        - drop "advanced usage" blurb + xref
      - add menu w/ three entries
    - split off subsection ‘pcase Macro’
      - add "for background" intro blrub + xref
    - split ‘Extending pcase’
      - move ‘Backquote-Style Patterns’ to its own subsection
      - drop related cindex entries, blurb portion
    - new subsection ‘Backquote Patterns’
      - move cindex entries here, shorten (drop "pattern")
      - add intro para
---
 doc/lispref/control.texi | 50 +++++++++++++++++++++++++++++-------------------
 1 file changed, 30 insertions(+), 20 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 0daca4f..f886edb 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -37,6 +37,7 @@ 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}.
 * Iteration::              @code{while} loops.
 * Generators::             Generic sequences and coroutines.
@@ -288,26 +289,24 @@ For example:
 @end group
 @end example
 
address@hidden Issue: This seems out of place.  It also gives lie to
address@hidden        ``Emacs Lisp has four conditional forms''.
address@hidden
-* Pattern-Matching Conditional::
-* Extending @code{pcase}: Extending pcase.
address@hidden menu
-
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?
 @node Pattern-Matching Conditional
address@hidden Pattern-Matching Conditional
address@hidden MAINTAINME: ``subsection'', ``subheading''
address@hidden Pattern-Matching Conditional
 @cindex pcase
 @cindex pattern matching
 
 @c Issue: I use ‘case’ w/ the thought that it being an alias
 @c        to ‘cl-case’ is an ``implementation detail''.
 @c        Is this okay?
-This subsection describes the @code{pcase} macro,
+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}
 that overcomes their limitations.
-For advanced usage information, @xref{Extending pcase}.
 
 @itemize
 @item The @code{cond} form chooses among alternatives
@@ -352,6 +351,17 @@ When the predicate, called on the value of the first arg,
 returns address@hidden, the pattern matches the value
 (or sometimes ``the value matches the pattern'').
 
address@hidden
+* The @code{pcase} macro: pcase Macro.  Plus examples and caveats.
+* Extending @code{pcase}: Extending pcase.  Define new kinds of patterns.
+* Backquote-Style Patterns: Backquote Patterns.  Structural matching.
address@hidden menu
+
address@hidden pcase Macro
address@hidden The @code{pcase} macro
+
+For background, @xref{Pattern-Matching Conditional}.
+
 @defmac pcase expression &rest clauses
 Each clause in @var{clauses} has the form:
 @address@hidden(@var{pattern} @address@hidden)}}.
@@ -842,18 +852,12 @@ The body form references both symbols (line 5).
 
 @node Extending pcase
 @subsection Extending @code{pcase}
address@hidden pcase, defining new kinds of pattern
address@hidden pattern matching, structural
address@hidden structural pattern matching
address@hidden pcase, defining new kinds of patterns
 
 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}.)
 
 @defmac pcase-defmacro name args [doc] &rest body
 Define a new kind of pattern for @code{pcase}, to be invoked
@@ -903,9 +907,15 @@ The second uses two core patterns: @code{and} and 
@code{pred},
 as well as the newly-defined pattern @code{less-than}.
 Both use a single backquote construct (@pxref{Backquote}).
 
address@hidden Issue: Should this be split off into its own node/subsection?
address@hidden Backquote-Style Patterns
address@hidden Backquote Patterns
address@hidden Backquote-Style Patterns
 @cindex backquote-style patterns
address@hidden matching, structural
address@hidden structural matching
+
+This subsection describes @dfn{backquote-style patterns},
+a set of builtin patterns that eases structural matching.
+For background, @xref{Pattern-Matching Conditional}.
 
 @dfn{Backquote-style patterns} are a powerful set of
 @code{pcase} pattern extensions (created using @code{pcase-defmacro})