Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: Stefan Monnier <address@hidden>
> Cc: address@hidden
> Date: Mon, 25 Jan 2016 20:40:12 -0500
> 
> >> > Unless, that is, there are important scenarios where using (quote FOO)
> >> > in a pattern is required where it isn't a trivial replacement
> >> > for 'FOO.
> >> A macro (such as pcase) can never distinguish 'A from (quote A) since
> >> the reader returns exactly the same result either way.
> > Sorry, is that a no?
> 
> It's not just a "no", it's a "no, because it's impossible".
> I thought that would be obvious to a seasoned Lisper like you, but
> clearly it isn't so we need to say it more explicitly.

pcase isn't Lisp, it's a macro that assigns different meanings to some
Lisp constructs.

> I've appended a suggested patch to try and correct those inaccuracies.

Thanks.  But I don't understand the rationale for most of the
changes.  I understand why you suggest to use "backquoted patterns"
where I used "QPatterns", and I agree with that.  But why all the
other changes?  E.g., this:

> -The @var{pattern} part of a clause can be of one of two types:
> address@hidden, a pattern quoted with a backquote; or a
> address@hidden, which is not quoted.  UPatterns are simpler, so we
> -describe them first.

If we use "backquoted patterns" here, the rest does have a purpose,
and removing it diminishes the ease of reading, I think.  The purpose
of this was to provide some outlook on the issue that's about to be
described.

> -The QPatterns are more powerful.  They allow matching the value of the
> address@hidden that is the first argument of @code{pcase} against
> -specifications of its @emph{structure}.  For example, you can specify
> -that the value must be a list of 2 elements whose first element is a
> -string and the second element is a number.  QPatterns can have one of
> -the following forms:
> address@hidden Pcase with backquotes
> address@hidden Pcase with backquotes
> +
> +Additionally to the above patterns, one can also use a backquoted
> +pattern.  This facility is designed with the idea that a backquoted
> +pattern should match all values that could be constructed
> +by a similarly backquoted expression.  For example, you can specify
> +that the value must be a list of 2 elements whose first element is the
> +string @code{"first"} with a pattern like @code{`("first" ,elem)}.

I agree that your example is better, but why the other changes?  Why
is it important to tell the reader the design idea?

I also don't think further dividing this sub-section into
sub-sub-sections is a good idea: there are less than 200 lines in it,
so it's not too large.  The last sub-sub-section you holds just 6
lines, way to few to justify a separate unit, I think.

In general, subdividing into nodes breaks the continuity of
description, so it's only justified for significant portions or for
some obscure aspect (like an extended footnote), or for almost
entirely unrelated subjects.  None of that happens here, I think.

Thanks.