Re: Update of pcase docs for the elisp manual

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> >> > 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.

But it's defined as a macro in Lisp.  Macros in Lisp do not see the
source code's text, they only see the Sexp representation, so just like
they can't see how much whitespace or which comments were present, they
can't distinguish 'foo from (quote foo) since they're both turned by the
Lisp reader into a cons cells with the symbol `quote' in the car.

>> -The @var{pattern} part of a clause can be of one of two types:
>> -@dfn{QPattern}, a pattern quoted with a backquote; or a
>> -@dfn{UPattern}, 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.

OK.

>> -The QPatterns are more powerful.  They allow matching the value of the
>> -@var{expression} 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:
>> +@node Pcase with backquotes
>> +@subsubsection 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 thought it would be good to try and give them an intuition that
hopefully helps them see the correspondance between the normal backquote
macro and the pcase backquote macro.

> 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.

OK.

> 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.

I guess I like structure more than the average human.


        Stefan