GNU bug report logs - #68028
29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description

Previous Next

To reply to this bug, email your comments to 68028 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description
Date: Mon, 25 Dec 2023 16:01:24 +0000

(Minor.)

Please consider moving the description of `rx' forms from after the
description of SEQPAT forms (`and' and `or').  The scope of the latter
description is less clear if `rx' follows the descriptions of `and' and
`or' (with no particular separation).  IOW, separate the SEQPAT
description from the other pattern descriptions better.

In GNU Emacs 29.1 (build 2, x86_64-w64-mingw32) of 2023-08-02 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3803)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-tree-sitter CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

Message #10 received at 68028 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Mattias Engdegård <mattiase <at> acm.org>,
 68028 <at> debbugs.gnu.org
Subject: Re: bug#68028: 29.1;
 (elisp) `pcase Macro': move `rx' before SEQPAT description
Date: Wed, 27 Dec 2023 13:47:33 -0800

severity 68028 wishlist
thanks

Drew Adams <drew.adams <at> oracle.com> writes:

> (Minor.)
>
> Please consider moving the description of `rx' forms from after the
> description of SEQPAT forms (`and' and `or').  The scope of the latter
> description is less clear if `rx' follows the descriptions of `and' and
> `or' (with no particular separation).  IOW, separate the SEQPAT
> description from the other pattern descriptions better.

Mattias, since you added that part, do you have any thoughts?

Message #13 received at 68028 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>,
 Drew Adams <drew.adams <at> oracle.com>, 68028 <at> debbugs.gnu.org
Subject: Re: bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT
 description
Date: Thu, 28 Dec 2023 11:29:37 +0100

[Message part 1 (text/plain, inline)]

27 dec. 2023 kl. 22.47 skrev Stefan Kangas <stefankangas <at> gmail.com>:

>> Please consider moving the description of `rx' forms from after the
>> description of SEQPAT forms (`and' and `or').  The scope of the latter
>> description is less clear if `rx' follows the descriptions of `and' and
>> `or' (with no particular separation).  IOW, separate the SEQPAT
>> description from the other pattern descriptions better.
> 
> Mattias, since you added that part, do you have any thoughts?

The location of the `rx` pattern description is fine; it's the SEQPAT paragraph that causes trouble as it splits the table into two parts.

I suggest we remove that paragraph because it doesn't actually say anything useful at that point; the user can learn how `or` and `and` patterns work without knowing that they are SEQPATs. Actually, I'd hoist those two patterns and reorder them to keep patterns in a rough order of usage: something like

  pred, guard, or, and, let, app, rx

makes more sense -- `pred` and `guard` clearly belong together, `app` is less common than `let`.

We could explain SEQPAT in a short sentence somewhere else, either near the beginning of the node or further down in the 'Caveats' subsection. A simple (and probably flawed) patch attached.

Stefan M probably has a better sense of how to improve the text. (By the way, the caveat section says that sequencing patterns use `eq` for comparison. Don't they use `eql`?)

[seqpat.diff (application/octet-stream, attachment)]

Message #16 received at 68028 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>,
 Drew Adams <drew.adams <at> oracle.com>, 68028 <at> debbugs.gnu.org
Subject: Re: bug#68028: 29.1;
 (elisp) `pcase Macro': move `rx' before SEQPAT description
Date: Thu, 28 Dec 2023 07:43:22 -0800

Mattias Engdegård <mattiase <at> acm.org> writes:

> I suggest we remove that paragraph because it doesn't actually say
> anything useful at that point; the user can learn how `or` and `and`
> patterns work without knowing that they are SEQPATs. Actually, I'd
> hoist those two patterns and reorder them to keep patterns in a rough
> order of usage: something like
>
>   pred, guard, or, and, let, app, rx
>
> makes more sense -- `pred` and `guard` clearly belong together, `app`
> is less common than `let`.
>
> We could explain SEQPAT in a short sentence somewhere else, either
> near the beginning of the node or further down in the 'Caveats'
> subsection. A simple (and probably flawed) patch attached.
>
> Stefan M probably has a better sense of how to improve the text. (By
> the way, the caveat section says that sequencing patterns use `eq` for
> comparison. Don't they use `eql`?)

Makes sense to me.  Perhaps your patch could be installed first, and
then we can take it from there.

Message #19 received at 68028 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefankangas <at> gmail.com>,
 Mattias Engdegård <mattiase <at> acm.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>,
 "68028 <at> debbugs.gnu.org" <68028 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#68028: 29.1; (elisp) `pcase Macro': move
 `rx' before SEQPAT description
Date: Thu, 28 Dec 2023 17:29:32 +0000

You might as well make this bug "wont-fix",
like the others you closed for this node.

The whole section, particularly this node,
needs a rewrite and reorg.  Ignoring that
doesn't help users.  Tried to guide you a
bit - sorry for wasting all of our time.

Other `Pattern-Matching Conditional' nodes
are less problematic.  The most useful,
particularly for users unfamiliar with
pattern-matching constructs, is the _last_
in the section, `Destructuring with pcase
Patterns'.
___

(But whaddo I know?  I've only been writing
and managing developer docs professionally
for 50 years.  I've only been familiar with
FP/LP/constraint pattern-matching languages
for 40 years.  Still I try to help out here
a bit - silly me.)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.