From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: Improving 'pcase' documentation Date: Mon, 25 Dec 2023 06:44:37 -0800 Message-ID: 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 To: Jim Porter , 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: 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 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 ) 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 ) 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 ) 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 ; 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." 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:314209 Archived-At: Copying in Stefan Monnier (author of pcase.el). Jim Porter 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