From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Stefan Monnier <monnier@iro.umontreal.ca>
Newsgroups: gmane.emacs.devel
Subject: Re: Improving 'pcase' documentation
Date: Mon, 25 Dec 2023 13:33:47 -0500
Message-ID: <jwvbkaejfzz.fsf-monnier+emacs@gnu.org>
References: <19a64b7a-cec0-ed8a-d413-096451cc7413@gmail.com>
 <CADwFkm=aZB29-Jc_WGBWj+SdwrQJ1KRCqvJUPgaqR=JpWDLVGA@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="12419"; mail-complaints-to="usenet@ciao.gmane.io"
User-Agent: Gnus/5.13 (Gnus v5.13)
Cc: Jim Porter <jporterbugs@gmail.com>,  emacs-devel@gnu.org
To: Stefan Kangas <stefankangas@gmail.com>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Dec 25 19:34:53 2023
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>
Envelope-to: ged-emacs-devel@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>)
	id 1rHpmu-0002uk-TQ
	for ged-emacs-devel@m.gmane-mx.org; Mon, 25 Dec 2023 19:34:53 +0100
Original-Received: from localhost ([::1] helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <emacs-devel-bounces@gnu.org>)
	id 1rHpmA-0002qF-R5; Mon, 25 Dec 2023 13:34:06 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <monnier@iro.umontreal.ca>)
 id 1rHpm7-0002q1-V1
 for emacs-devel@gnu.org; Mon, 25 Dec 2023 13:34:04 -0500
Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <monnier@iro.umontreal.ca>)
 id 1rHpm6-0002VQ-2N
 for emacs-devel@gnu.org; Mon, 25 Dec 2023 13:34:03 -0500
Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1])
 by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 0AA9810009E;
 Mon, 25 Dec 2023 13:34:00 -0500 (EST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca;
 s=mail; t=1703529234;
 bh=qsBkNpUC97HFgPtUHShgPCtlYiTyRw6u6MnX59j4PWM=;
 h=From:To:Cc:Subject:In-Reply-To:References:Date:From;
 b=Ks/5Nlz4+pawb2PR0IsTvAPzdpVpHgRBQqZadOzi8G3mhHvgfFDcEeXxa3AKZv814
 cqvZPSLTpA9IobYMylJdPlf1Zcq6SegHPA/OUpkHpKrbniSkacLekG9pKfxrjYYEfw
 asvOsfwxJeLQvLDMXd8uoRlvFSVfjL/HSLSKxNu0DSITeJVMUanAYwTusun+Uzul7w
 ppvu0gfIL5hlSc7qDtHFObr21KjttYcTR6BaOWW96xIF7W+qtMlQqgVvv3ytS4ISjG
 RoDt/puwnLwus2wo7wWhdo45zIVXsqRVCcIc4prb2RnOfDV0GT/2W8IqnaNP5gECgJ
 jcmIKUcX5daPg==
Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1])
 by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id E78C8100054;
 Mon, 25 Dec 2023 13:33:54 -0500 (EST)
Original-Received: from pastel (65-110-221-238.cpe.pppoe.ca [65.110.221.238])
 by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 75B661205BC;
 Mon, 25 Dec 2023 13:33:54 -0500 (EST)
In-Reply-To: <CADwFkm=aZB29-Jc_WGBWj+SdwrQJ1KRCqvJUPgaqR=JpWDLVGA@mail.gmail.com>
 (Stefan Kangas's message of "Mon, 25 Dec 2023 06:44:37 -0800")
Received-SPF: pass client-ip=132.204.25.50;
 envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca
X-Spam_score_int: -42
X-Spam_score: -4.3
X-Spam_bar: ----
X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3,
 SPF_HELO_NONE=0.001, SPF_PASS=-0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Emacs development discussions." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/emacs-devel>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Xref: news.gmane.io gmane.emacs.devel:314214
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/314214>

>> 1. Mention backquote patterns earlier in the 'pcase' docstring. While
>> backquote patterns are in the docstring, they're pasted after the main
>> body and not listed in the part that says, "PATTERN can take one of the
>> forms: ...". Since backquote patterns aren't immediately obvious and are
>> hard to search for, they could probably stand to get mentioned earlier.
>> (Likewise, we could do the same for the 'rx' pattern in 'pcase'.) I'm
>> not sure the best way to go about this when using 'pcase-defmacro', but
>> even just manually adding it to the main 'pcase' docstring might improve
>> matters.

I'd rather not do that.  The docstring is a reference, not a manual.
But what we could do maybe is to make it more clear that the patterns
presented first (i.e. those that in pcase's main docstring) are
"internal" (and used mostly to define higher-level patterns) and somehow
encourage people to "jump further" to see the actual higher-level
patterns.

And then arrange the ordering of those higher-level patterns so
backquote comes first (which seems to be the case here, but maybe it's
a lucky accident).

>> 2. Add a simpler conceptual summary for backquote patterns. I think you
>> could get pretty far by describing them as "running the usual
>> backquoting in reverse". That is, instead of building a list where you
>> splice values *in*, you're destructuring a list where you cut values *out*.

This "general principle" to make patterns look like calls to the
corresponding constructors should be mentioned somewhere, indeed (along
ith a caveat that it's only true for some patterns).

3-6 all sound very good.


        Stefan