Re: Replace trivial pcase occurrences in the Emacs sources

[Eli Zaretskii]

> From: Stefan Monnier <address@hidden>
> Date: Tue, 30 Oct 2018 13:16:33 -0400
> Cc: Michael Heerdegen <address@hidden>, address@hidden
> 
> >> I wonder if the manual shouldn't have a section somewhere making
> >> explicit the difference between `pcase' -- where a single value is
> >> matched against many patterns, and may fail to match altogether, and
> >> destructuring is only one of the use-cases -- and the other
> > Yes, I'll send a patch for that,
> 
> How 'bout...

Thanks.  I have a few comments:

> +* Destructuring patterns:: Using pcase patterns to extract subfields.

We never used "pcase patterns" in the manual before, so I wonder
whether we should start now.  If we want to do that, this should be
defined before it is used.

> address@hidden Destructuring patterns
> address@hidden Destructuring Patterns
> address@hidden Destructuring patterns

By convention, index entries should start with a lower-case letter.

> +The macros described in this section use @emph{destructuring}
> +patterns, which are normal Pcase patterns used in a context where we
> +presume that the object does match the pattern, and we only want
> +to extract some subfields.

I think we need to define "destructuring" here (or elsewhere in the
manual, and have a cross-reference there in this section).  Readers
that aren't familiar with that term will not be able to understand why
this word is used here.  We need to start this with something like

  @dfn{Destructuring} means ...

It would also help to tell what exactly makes a pattern a
destructuring one.

> address@hidden
> +  (pcase-let ((`(add ,x ,y) l))
> +    (message "Contains %S and %S" x y))
> address@hidden example
> +
> +Does the same as the previous example, except that it directly tries

You want the text after the example to start like this:

  @noindent
  does the same as ...

Otherwise, this sentence sounds awkward, and will also be indented.

> address@hidden is a list of bindings of the form @code{(@var{pattern}
> address@hidden)}

Please use @w{..} around this form, so that it doesn't get broken
between two lines.

> +All @var{exp}s are evaluated first after which they are matched
> +against their respective @var{pattern}, introducing new variable
> +bindings which can then be used inside @var{body}.

AFAIU, this means only some of the pcase patterns make sense in this
context.  If that is true, I'd suggest ti somehow tell which are (or
which aren't, if that's easier).

> address@hidden pcase-dolist (pattern list) address@hidden
> +This construct executes @var{body} once for each element of
> address@hidden, in a context where the destructuring pattern
> address@hidden was matched against the element.

I don't think I understand what "in a context where the pattern was
matched" means here.  Is any aspect of the match except destructuring
bindings relevant to execution of the body?  If so, what other aspects
are relevant?

Thanks.