From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Instead of pcase Date: Fri, 24 Nov 2023 09:45:16 +0200 Message-ID: <83edgffvcj.fsf@gnu.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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11467"; mail-complaints-to="usenet@ciao.gmane.io" Cc: rms@gnu.org, dmitry@gutov.dev, philipk@posteo.net, emacs-devel@gnu.org To: Jim Porter Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Nov 24 08:46:59 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 1r6Qtu-0002ki-OA for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Nov 2023 08:46:58 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r6Qsx-00080r-Lr; Fri, 24 Nov 2023 02:45:59 -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 1r6Qsq-00080T-BE for emacs-devel@gnu.org; Fri, 24 Nov 2023 02:45:54 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r6Qsp-0000ur-Do; Fri, 24 Nov 2023 02:45:51 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=egonr65aJgdu8lbFymR0TjBaTnq+K8RRb/1IOs0T4xQ=; b=cmHjMS/xFWXZ bgyuH+tYWby4UmcuTDFkyazP2EI+VRnaW24zaVOSzw1UlW1Gv1f6oJ7Jbi2ZN5JiKCEGoj9GUBHu/ UE9Xy7Q3sesr34UT5VDJXVCUtHKDsw6nXhEz1sMTnzrDFsEnkV1rCWvAC3hQBZp84FLVz/e4Q+82n v6xOdjqT9iJIbXHhX626azN+MehRJFRIiSFo19ttpxq5+utuOHMDzIYCb0ZvAUREoF3tUGHndxyis vur1mztu4q40JpWtvyoCr9sPUjbbCG7KK9WXeiAvPY7sfrv62nx4LePGR/QttHNpn4apgsU1u9F9Q xWCSZouLOhG6TEWoaxfZwA==; In-Reply-To: (message from Jim Porter on Thu, 23 Nov 2023 20:30:27 -0800) 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:313172 Archived-At: > Date: Thu, 23 Nov 2023 20:30:27 -0800 > Cc: philipk@posteo.net, emacs-devel@gnu.org > From: Jim Porter > > 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. It depends on what you mean by "almost-trivial examples", but in general I find trivial examples to be at best of very limited value. First, where the use of 'pcase' is trivial, we should usually not use 'pcase' at all, but the equivalent constructs that are easier to read and understand. More importantly, trivial examples (the ones I have in mind) don't add anything to the written documentation, and thus neither help you better understand the documentation's subtle and obscure corners nor ease specific practical tasks of writing code that uses 'pcase' for specific purposes. The latter is an explicit goal of shortdocs, why we have it in the first place, so having trivial examples there for such advanced and flexible constructs defeats its very purpose, IMO. > (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.) I disagree that the shortdoc system is intended to teach by example. Such a system must have many explanations for each example, and shortdoc provides only a terse single-sentence description of each example. From where I stand, shortdoc is supposed to show real-life examples of doing non-trivial jobs, with the intent that given a relevant example, the reader could then go back to the documentation and say: "ah, so that's what they meant when they talked about so-and-so!" IOW, shortdoc is NOT supposed to replace the documentation, only to be a collection of examples that illustrate the documentation.