From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Jim Porter <jporterbugs@gmail.com>
Newsgroups: gmane.emacs.devel
Subject: Improving 'pcase' documentation
Date: Sun, 19 Nov 2023 12:14:39 -0800
Message-ID: <19a64b7a-cec0-ed8a-d413-096451cc7413@gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="12396"; mail-complaints-to="usenet@ciao.gmane.io"
To: emacs-devel@gnu.org
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Nov 19 21:15:42 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 1r4oCk-00033m-9N
	for ged-emacs-devel@m.gmane-mx.org; Sun, 19 Nov 2023 21:15:42 +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 1r4oBq-00024g-83; Sun, 19 Nov 2023 15:14:46 -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 <jporterbugs@gmail.com>)
 id 1r4oBn-00024D-Pf
 for emacs-devel@gnu.org; Sun, 19 Nov 2023 15:14:43 -0500
Original-Received: from mail-pj1-x102b.google.com ([2607:f8b0:4864:20::102b])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <jporterbugs@gmail.com>)
 id 1r4oBm-000770-48
 for emacs-devel@gnu.org; Sun, 19 Nov 2023 15:14:43 -0500
Original-Received: by mail-pj1-x102b.google.com with SMTP id
 98e67ed59e1d1-27ff7fe7fbcso2959146a91.1
 for <emacs-devel@gnu.org>; Sun, 19 Nov 2023 12:14:41 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=gmail.com; s=20230601; t=1700424880; x=1701029680; darn=gnu.org;
 h=content-transfer-encoding:subject:from:to:content-language
 :mime-version:date:message-id:from:to:cc:subject:date:message-id
 :reply-to; bh=qmIqOlc0b+VCJEHDm402zsfAMLmzQnFP6+7/yNsdQhs=;
 b=mJeq2RhrEJlOcviKELDN175ft4NtsZ1yoWGJEvnnpHgZnkf2PjI8PK58LPPC1Su84d
 mjpn8EbJOl0SF2g+dxhlZTJKZ8KVH+NDCXaKLacHHj2eaEAhC2O/ROYtxBwf9/ZsPK1B
 ZYHfVxX9GB9z9ygVnIMmrmltK+qpfTugPfNIp/wPYfYWaJ8Mnc4am5thqTOlP8bJLpic
 nkCS+iVKbF7PJuP0TTvtDXvBfD4ay8rGCBt9B6KaYoAlA5BjeDwkl2CFwImdK1UJXvuh
 Fg6ZUDFK7SvA376kF/jlPmcf1GCV9ALvixPPB+YkZrr+YiTO1R3JesmEYtCIqwtMVDVW
 7q+Q==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1700424880; x=1701029680;
 h=content-transfer-encoding:subject:from:to:content-language
 :mime-version:date:message-id:x-gm-message-state:from:to:cc:subject
 :date:message-id:reply-to;
 bh=qmIqOlc0b+VCJEHDm402zsfAMLmzQnFP6+7/yNsdQhs=;
 b=MumoKES0EZeUppEQ6+nrO8ZjNtSChcIXBxVCDMbFuW1A4rdFXwNuJR6gcI9L1tfpet
 O67PVnT0UvBhpFaVWe3qoFydTUbxiYYNY1YIIg5Pn7OA4QDoONrTISwX1+Z/BOHp8ml0
 1UJx0W/2T8yk4EBb/t1S306685T5CSsIg34JDEMT9GmWuG4EP1XtWh0SZOcn/9Ophb+t
 g2wRskOpIpgZd3KCsAPkgj/4TnHht+6py8ywxYse6yLiuyDaefiM1OTxc2I8lAf2J+hZ
 +7Oocp88cWOjeDgF1mHwOMaHJ1HV/hI9tUHQq9OZX+uoTJsMedWKl9zhkrwUGgobpNV0
 2EUg==
X-Gm-Message-State: AOJu0YwkyOj4eUq+ZF5tyrzd9Vmnio5c5JmAxKmEqBSqdN5/y26QfLID
 FDH2wosnYlxd9qDQjJa4x4iNZxu56h4=
X-Google-Smtp-Source: AGHT+IH/FzQDl2c+uWGN6JTg63wyJlw9YEsBX60nhztuuT6vcmgKBVBrGyds2s9YcMV9oGLoxf0+fA==
X-Received: by 2002:a17:90b:1c02:b0:280:c98f:2090 with SMTP id
 oc2-20020a17090b1c0200b00280c98f2090mr6200239pjb.32.1700424880325; 
 Sun, 19 Nov 2023 12:14:40 -0800 (PST)
Original-Received: from [192.168.1.2] (cpe-76-168-148-233.socal.res.rr.com.
 [76.168.148.233]) by smtp.googlemail.com with ESMTPSA id
 ne19-20020a17090b375300b00285114454b4sm2437232pjb.22.2023.11.19.12.14.39
 for <emacs-devel@gnu.org>
 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);
 Sun, 19 Nov 2023 12:14:39 -0800 (PST)
X-Mozilla-News-Host: news://news.gmane.io:119
Content-Language: en-US
Received-SPF: pass client-ip=2607:f8b0:4864:20::102b;
 envelope-from=jporterbugs@gmail.com; helo=mail-pj1-x102b.google.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,
 RCVD_IN_DNSWL_NONE=-0.0001, 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:313019
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/313019>

(Separate thread from the other 'pcase' thread since that thread is 
getting hard to follow for me now.)

On the discussion of 'pcase', I notice that one of the issues people 
have mentioned a few times is that the documentation is insufficient, at 
least compared to how intuitive the syntax is ("not very", for some 
people). To that end, I think it would be worth improving these 
deficiencies so that it's easier for someone unfamiliar with 'pcase' to 
understand it (at least well enough to maintain ordinary uses of 'pcase').

Here are some areas I think we could improve. There may be more:

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.

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

3. Add shortdoc examples for 'pcase', including some common ways to 
combine patterns. Starting simple and then building to something more 
complex would show how the pieces fit together, and would (hopefully) 
make it the syntax clear since you can see the final form all together.

4. Improve the reference manual. We could move the examples in the 
'pcase' documentation to a separate subnode, and add a couple of simpler 
examples first. That way, we can again introduce 'pcase' by example a 
bit more gradually. We could also change how we introduce 'pcase' in the 
main "Pattern-Matching Conditional" node. Currently, it compares the 
relative benefits of 'pcase', 'cond', and 'cl-case'; that's useful and 
informative, but maybe not as the very first introduction to 'pcase'. 
What about describing what "pattern matching programming style" means, 
show a brief example, and then move onto the rest of the documentation? 
The comparison with 'cond' and 'cl-case' could be the last subnode of 
the section.

5. Mention 'pcase' in the Lisp Intro manual? A beginner's guide to 
'pcase' could make sense in the Lisp Intro, and while we wouldn't have 
to cover everything, it would at minimum alert readers to the fact that 
it exists, and the basics of how 'pcase' works.

6. Improve editing support. I'm not sure how feasible this is, but it 
would be nice if Emacs understood 'pcase' better when editing. For 
example, font-lock support on the various macro forms; Emacs already 
font-locks the 'or' pattern, but only because 'or' is font-locked 
normally. It would be nice if the same applied to 'pred', 'guard', etc. 
Similarly, ElDoc and Help (C-h f) could do the right thing inside 
'pcase', providing us with the appropriate documentation. (I also think 
it'd be nice to font-lock anything that looks like ",SYMBOL", even 
outside of 'pcase', but maybe others would find that annoying.)

Does anyone have any particular feedback on these ideas, suggestions of 
what would be the most beneficial, etc?

- Jim