From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.devel Subject: Re: Instead of pcase Date: Sat, 25 Nov 2023 04:08:41 +0100 Message-ID: <87cyvyedhi.fsf@dataswamp.org> References: <87fs169mjj.fsf@posteo.net> <093f11a1-57c2-5e56-d39b-26fef1c67cbb@gutov.dev> <25942.25061.217864.329049@retriever.mtv.corp.google.com> <87zfzdcz6z.fsf@posteo.net> <763f067b-4ca9-1eba-9f3c-424c38589e9c@gutov.dev> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13960"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) To: emacs-devel@gnu.org Cancel-Lock: sha1:arj+iPtgnntl7NTK6IskD3XT/3Y= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Nov 25 07:48:13 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 1r6mSa-0003RT-M4 for ged-emacs-devel@m.gmane-mx.org; Sat, 25 Nov 2023 07:48:12 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r6mRd-0005RS-Hv; Sat, 25 Nov 2023 01:47:13 -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 1r6j2N-0008IB-Oi for emacs-devel@gnu.org; Fri, 24 Nov 2023 22:08:55 -0500 Original-Received: from ciao.gmane.io ([116.202.254.214]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r6j2M-0006sE-59 for emacs-devel@gnu.org; Fri, 24 Nov 2023 22:08:55 -0500 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1r6j2H-0004BT-K9 for emacs-devel@gnu.org; Sat, 25 Nov 2023 04:08:49 +0100 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: emacs-devel@gnu.org Mail-Copies-To: never Received-SPF: pass client-ip=116.202.254.214; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.25, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Sat, 25 Nov 2023 01:47:05 -0500 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:313198 Archived-At: Jim Porter wrote: > For cases like this, I hope to (at least partially) address > it with better documentation. I'm not sure we can expect > every instance of 'pcase' in the Emacs codebase to be a good > teachable example for how to use 'pcase', but I do think we > could achieve that with shortdocs. The shortdocs could start > small with almost-trivial examples, and then build up to > more-complex forms that show how the pieces interact. > > Broadly, my goal would be that anyone who already knows Lisp > could load up the shortdocs for pcase and get the hang of > 95% of it in a few minutes. > > (I also think we could improve the manuals and the > docstring, but I think 'pcase' is a great candidate for > teaching by example. The shortdoc system seems ideal > for that.) One could make the first examples as easy as possible to show all the aspects of pcase use, this is how you do this, this is how you do that, and so on, the bunch. It would include terminology but only terminology that is visible in that example. Then there could be examples that included combinations of such aspects, this is helpful to assimilate the previous examples. After that, actual but typical use cases from the Emacs source. After that, gray areas, weird border cases and so on, also from the Emacs source (if we can find them - if not, all the better). -- underground experts united https://dataswamp.org/~incal