[Emacs-diffs] fix/bug-31311-pcase-doc 53973de 7/9: refine QPAT table

[Thien-Thi Nguyen]

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

    refine QPAT table
    
    - do ‘s/backquoted pattern/backquote-style pattern/g’
    - use singular in intro blurb
    - do ‘s/qpattern/qpat/g’
    - do ‘s/backquoted lists/lists/’ (DWR: "backquote" overload!)
    - use "literal object"
    - mention @var{pattern} as unrestricted kind
    - add inline example (‘second-elem’ as SYMBOL)
    - add post-table para to define "corresponding element"
    - add inline example (again ‘second-elem’)
---
 doc/lispref/control.texi | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index fe01531..febbe19 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -933,36 +933,46 @@ and avoids binding @code{ls}:
 `("first" ,second-elem)
 @end example
 
-Backquoted patterns have the form @address@hidden where
address@hidden can have the following forms:
+A backquote-style pattern has the form @address@hidden where
address@hidden can have the following forms:
 
 @table @code
 
address@hidden (@var{qpattern1} . @var{qpattern2})
address@hidden (@var{qpat1} . @var{qpat2})
 Matches if @var{expval} is a cons cell whose @code{car}
-matches @var{qpattern1} and whose @code{cdr} matches @var{qpattern2}.
-This readily generalizes to backquoted lists as in
address@hidden@code{(@var{qpattern1} @var{qpattern2} @dots{})}}.
+matches @var{qpat1} and whose @code{cdr} matches @var{qpat2}.
+This readily generalizes to lists as in
address@hidden@code{(@var{qpat1} @var{qpat2} @dots{})}}.
 
address@hidden address@hidden @var{qpattern2} @dots{} @var{qpatternm}]
address@hidden address@hidden @var{qpat2} @dots{} @var{qpatm}]
 Matches if @var{expval} is a vector of length @var{m} whose
address@hidden@code{(@var{m}-1)}th elements match @var{qpattern1},
address@hidden @dots{} @var{qpatternm}, respectively.
address@hidden@code{(@var{m}-1)}th elements match @var{qpat1},
address@hidden @dots{} @var{qpatm}, respectively.
 
 @item @var{symbol}
 @itemx @var{keyword}
 @itemx @var{integer}
 @itemx @var{string}
 Matches if the corresponding element of @var{expval} is
address@hidden to the specified object.
address@hidden to the specified literal object.
 Note that, aside from @var{symbol}, this is the same set of
-self-quoting types that are acceptable as a core pattern.
+self-quoting literal objects that are acceptable as a core pattern.
 
 @item ,@var{pattern}
 Matches if the corresponding element of @var{expval}
-matches the @var{pattern}.
+matches @var{pattern}.
+Note that @var{pattern} is any kind that @code{pcase} supports.
+(In the example above, @code{second-elem} is a @var{symbol}
+core pattern; it therefore matches anything,
+and let-binds @code{second-elem}.)
 @end table
 
+The @dfn{corresponding element} is the portion of @var{expval}
+that is in the same structural position as the structural position
+of @var{qpat} in the backquote-style pattern.
+(In the example above, the corresponding element of
address@hidden is the second element of @var{expval}.)
+
 Note that uses of Q-patterns can be expressed using only core
 patterns, as Q-patterns are implemented on top of core patterns using
 @code{pcase-defmacro}, described below.  However, using Q-patterns will