bug#59887: pcase vs. pcase-let: Underscore in backquote-style patterns

[hokomo]

> My question is that when we make the text even longer, would 
> that help
> people that don't read carefully (because we don't need to 
> address
> others) at all?

I believe it would. Even though I should've been more careful with 
reading the whole page, one's first instinct (at least mine) when 
reading a reference manual is to jump directly to the operator in 
question and expect to find all of the necessary and essential 
information there, whether it is a detailed explanation or just a 
hint or short remark mentioning some concepts that were introduced 
more thoroughly earlier in the manual.

As an example, the beginning of the Handling Errors page [1] 
describes, among other things, the meaning of the `debug' symbol 
within a condition-case handler's condition list. However, the 
description of condition-case specifically also includes the short 
remark "which can include debug to allow the debugger to run 
before the handler" which is useful to point the reader to the 
description at the beginning (all it takes is searching for 
"debug" on the same page after reading the remark).

[1] 
<https://www.gnu.org/software/emacs/manual/html_node/elisp/Handling-Errors.html>

> My second question is if that would have helped you at all, 
> because your
> crucial misunderstanding was about the meaning of `_`.  Using 
> patterns
> in `pcase-let' that don't match generally doesn't make much 
> sense, it's
> totally unclear what would happen in this case.  That's another 
> reason
> why I don't want to over-emphasize this case.
>
> Maybe saying that `_` is not special when used as a QPAT would 
> make
> sense, in (info "(elisp) Backquote Patterns").  I mean in this
> paragraph:
>
> | ‘SYMBOL’
> | ‘KEYWORD’
> | ‘NUMBER’
> | ‘STRING’
> |      Matches if the corresponding element of EXPVAL is ‘equal’ 
> to the
> |      specified literal object.
>
> We could add that `_` is not special (no symbol is special as a 
> qpat,
> actually).  Would that give a useful hint?  It seems that some 
> people
> seem to expect that `_` is special everywhere in pcase.

That is indeed the core of the issue and I definitely think it 
would be a good idea to have an explicit statement that the 
underscore symbol is not special as a QPAT. You can sort of infer 
it from the specification, but given the unspecified behavior of 
pcase-let in the case of a non-match, making it explicit would be 
nice.

I think I would've ended up poking around pcase-let in any case 
after being puzzled about its behavior, just out of curiosity. 
Having a short remark about "structural compatibility" in the 
documentation of the specific operator would then help me quickly 
narrow down to what I need.

hokomo