From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Improving 'pcase' documentation Date: Mon, 25 Dec 2023 13:33:47 -0500 Message-ID: References: <19a64b7a-cec0-ed8a-d413-096451cc7413@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 , emacs-devel@gnu.org To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Dec 25 19:34:53 2023 Return-path: 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 ) 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 ) 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 ) 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 ) 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: (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." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: >> 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