Improve documentation of destructuring-binding macros

* lisp/emacs-lisp/pcase.el (pcase-dolist, pcase-let)
(pcase-let*): Improve the doc strings.

* doc/lispref/sequences.texi (Sequence Functions): Improve
wording and rename arguments of seq-let to be more
descriptive.  Add a cross-reference to "Destructuring with
pcase Patterns".
* doc/lispref/control.texi (Pattern-Matching Conditional):
Improve wording and the menu.
(pcase Macro): Incorporate patch suggested by Paul Eggert
<eggert@cs.ucla.edu>.  Reformat text.
(Destructuring with pcase Patterns): Rename from
"Destructuring patterns", and improve wording and indexing.

1 files changed, 13 insertions, 7 deletions

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 51d724cb1d8..60d017c3e44 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1049,15 +1049,18 @@ that @var{sequence} can be a list, vector or string.  This is
 primarily useful for side-effects.
 @end defmac
 
-@defmac seq-let arguments sequence body@dots{}
+@anchor{seq-let}
+@defmac seq-let var-sequence val-sequence body@dots{}
 @cindex sequence destructuring
-  This macro binds the variables defined in @var{arguments} to the
-elements of @var{sequence}.  @var{arguments} can themselves include
-sequences, allowing for nested destructuring.
+  This macro binds the variables defined in @var{var-sequence} to the
+values that are the corresponding elements of @var{val-sequence}.
+This is known as @dfn{destructuring binding}.  The elements of
+@var{var-sequence} can themselves include sequences, allowing for
+nested destructuring.
 
-The @var{arguments} sequence can also include the @code{&rest} marker
-followed by a variable name to be bound to the rest of
-@code{sequence}.
+The @var{var-sequence} sequence can also include the @code{&rest}
+marker followed by a variable name to be bound to the rest of
+@var{val-sequence}.
 
 @example
 @group
@@ -1081,6 +1084,9 @@ followed by a variable name to be bound to the rest of
 @end group
 @result{} [3 4]
 @end example
+
+The @code{pcase} patterns provide an alternative facility for
+destructuring binding, see @ref{Destructuring with pcase Patterns}.
 @end defmac
 
 @defun seq-random-elt sequence