From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Stefan Kangas <stefankangas@gmail.com>
Newsgroups: gmane.emacs.devel
Subject: Re: Improving 'pcase' documentation
Date: Mon, 25 Dec 2023 06:44:37 -0800
Message-ID: <CADwFkm=aZB29-Jc_WGBWj+SdwrQJ1KRCqvJUPgaqR=JpWDLVGA@mail.gmail.com>
References: <19a64b7a-cec0-ed8a-d413-096451cc7413@gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="8807"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: Stefan Monnier <monnier@iro.umontreal.ca>
To: Jim Porter <jporterbugs@gmail.com>, emacs-devel@gnu.org
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Dec 25 15:45:36 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 1rHmD1-00027K-Rv
	for ged-emacs-devel@m.gmane-mx.org; Mon, 25 Dec 2023 15:45:35 +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 1rHmCD-0004N6-VS; Mon, 25 Dec 2023 09:44:45 -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 <stefankangas@gmail.com>)
 id 1rHmCC-0004Mw-LP
 for emacs-devel@gnu.org; Mon, 25 Dec 2023 09:44:44 -0500
Original-Received: from mail-ed1-x533.google.com ([2a00:1450:4864:20::533])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <stefankangas@gmail.com>)
 id 1rHmC8-0000Qs-Hn
 for emacs-devel@gnu.org; Mon, 25 Dec 2023 09:44:42 -0500
Original-Received: by mail-ed1-x533.google.com with SMTP id
 4fb4d7f45d1cf-554e4f8610aso577935a12.1
 for <emacs-devel@gnu.org>; Mon, 25 Dec 2023 06:44:40 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=gmail.com; s=20230601; t=1703515478; x=1704120278; darn=gnu.org;
 h=cc:to:subject:message-id:date:mime-version:references:in-reply-to
 :from:from:to:cc:subject:date:message-id:reply-to;
 bh=3TRPmc67WRVO5ydG+yPXa/xpSrUHR1UDhRfN/niVYBc=;
 b=XDwxJKg3Y492SFip3KvxnB5+q1q3oEQ6q4iC2ZqIuuC7F5dp6ktILkXfi6ncRAN3rB
 iD0ELeGPr0aZ76BYAvR3zJbTfQYCXtFhBozBigkvZEb4V14VlM0a/Ts6bOz2+M0BXy+B
 N8XWBWB5MFGLcjt56P0Re9v4gvqyKXQY7+RlvHqTuRVADQa+ZCBmpXpdQqHJCpHgklP8
 hrSV4Huuedy1EpQttrkEYNgQZmZYTYYzcIvKGOZSjy6Ur8ZYgeF8bmMR/z/6yO/bo1Fe
 APVUoC9750Uua/YHXaa+ULTF2phKDy039WS3cCHyBA1GlhQrkB16HF2/Rv/K+TTtQhlS
 OGeA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1703515478; x=1704120278;
 h=cc:to:subject:message-id:date:mime-version:references:in-reply-to
 :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=3TRPmc67WRVO5ydG+yPXa/xpSrUHR1UDhRfN/niVYBc=;
 b=PhZRRtFOAoXcKiCw7+SHdMOmxBYAbERkgOK04fIo+nc7KOkp1YO/OuPiOr2Y45BI03
 6jphUOl0YG06JaqyN6V13Dgg6RzpdSdeKPaM9O36ODQ3szd9GfzRuVqB+kxGL7h0L9u5
 quyfj5uzE4/UYHLBNFsPzZn2xsYrnrqAHWhx4JSHZ4nCl5ox2WA+rgNTs0V+5fZ0cCkR
 BLpNpz/H0yHbx1BCGnKGqvpBVJJ8BSYflqb36sEdgTK7vCmfJjwP1ehYaoXa1dYKnSTG
 UULcf7w4YvgEwTsKo4cDThj5Nq6TqulF+8buzjFaSqXdjbYnDzYAkGqt3njJbqN6Arhk
 d9cQ==
X-Gm-Message-State: AOJu0Yx4/ZHEeaKHww0YbtIK05T2JyNbidnCDuNF6SQaofyXprRcp1dQ
 xER6482WQCiKIzHXGWs6O6L5T+YaKlPw9GDWin9zUXrmhYc8mg==
X-Google-Smtp-Source: AGHT+IG3RxjQz7pfSZMp+dEaUWcdp2N8igJiRRZMt2Qle7PG+M7YB1bMxuvQR8tQjYQqlVX2uSN1wm8yd7F1lnckBww=
X-Received: by 2002:a50:d782:0:b0:54c:4837:a64c with SMTP id
 w2-20020a50d782000000b0054c4837a64cmr4226106edi.57.1703515478089; Mon, 25 Dec
 2023 06:44:38 -0800 (PST)
Original-Received: from 753933720722 named unknown by gmailapi.google.com with
 HTTPREST; Mon, 25 Dec 2023 06:44:37 -0800
In-Reply-To: <19a64b7a-cec0-ed8a-d413-096451cc7413@gmail.com>
Received-SPF: pass client-ip=2a00:1450:4864:20::533;
 envelope-from=stefankangas@gmail.com; helo=mail-ed1-x533.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:314209
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/314209>

Copying in Stefan Monnier (author of pcase.el).

Jim Porter <jporterbugs@gmail.com> writes:

> (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