From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Josselin Poiret Newsgroups: gmane.lisp.guile.devel Subject: Re: [PATCH v3] docs/match: pattern matcher example makeover Date: Fri, 03 Feb 2023 14:43:44 +0100 Message-ID: <87ilgix3sf.fsf@jpoiret.xyz> References: <20230201130930.6624-1-blake@reproduciblemedia.com> <9725d8d9-faf2-3306-94ae-209086aa5a82@telenet.be> <20230202144720.306d1bb3@aicha> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32557"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Blake Shaw , guile-devel@gnu.org To: David Pirotte , Maxime Devos Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Fri Feb 03 14:44:17 2023 Return-path: Envelope-to: guile-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 1pNwMS-0008Hg-80 for guile-devel@m.gmane-mx.org; Fri, 03 Feb 2023 14:44:17 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNwM4-0000ob-C8; Fri, 03 Feb 2023 08:43:52 -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 1pNwM2-0000oR-OD for guile-devel@gnu.org; Fri, 03 Feb 2023 08:43:50 -0500 Original-Received: from jpoiret.xyz ([206.189.101.64]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pNwM1-0006pq-9I for guile-devel@gnu.org; Fri, 03 Feb 2023 08:43:50 -0500 Original-Received: from authenticated-user (jpoiret.xyz [206.189.101.64]) by jpoiret.xyz (Postfix) with ESMTPA id 2821B185313; Fri, 3 Feb 2023 13:43:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jpoiret.xyz; s=dkim; t=1675431825; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=zfT6Gi63BmZysX0BzGQ7mSVhmdo4q+5rpcZ05dycZik=; b=SLoAIh8kmAz5TJJM1dSplWL1WH+RdurHoZwYyMGRAvSDAEAFnq1bAjthpQmnFifPzwkcHy /RWG9Hmofg8/+GCerJ/Q1iUUSfni1cwkhbLutfD1jIQCZ9VmYohKXdLbkDWRvnqS9lnruw plAi4uqXNAItbLdJrbcdKgyjBP+UHt9ZuXjLqhdUaL9K1jNBqB+iZNl/sLBpQbajmHGZre 150F4fp+4I2SEcR6O77eAPMxemZDyA2ekXMWtx0Z9qk8nRp9DvOCx0QRvGuG6OjOoAdU9K sPpEL7cHfMQeAHyqGczsIdbEzeWqFp6p1VuLWk1iz4JapPShHcjio8nwQ6U7gg== In-Reply-To: <20230202144720.306d1bb3@aicha> Authentication-Results: jpoiret.xyz; auth=pass smtp.auth=jpoiret@jpoiret.xyz smtp.mailfrom=dev@jpoiret.xyz X-Spamd-Bar: / Received-SPF: pass client-ip=206.189.101.64; envelope-from=dev@jpoiret.xyz; helo=jpoiret.xyz X-Spam_score_int: -15 X-Spam_score: -1.6 X-Spam_bar: - X-Spam_report: (-1.6 / 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, FROM_SUSPICIOUS_NTLD=0.499, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_PDS_OTHER_BAD_TLD=0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.devel:21679 Archived-At: Hi Blake and David, We were talking about this very node of the documentation yesterday with Ludovic and zimoun, so here are my two cents. Rewriting this introduction is a very good idea, the current one is pretty hard to get into for novices. David Pirotte writes: > Not at all - and quite annoying. imo. > So i'd 'vote' not to use them anywhere in the guile reference manual I agree that it's not "idiomatic Guile" so should probably be left out. Regarding the examples, I think the first one is nice but the next one is too involved, using a named let which a lot of users might not know. I'd suggest demonstrating each feature without any extra prerequisite, to make it as accessible as possible. The third example, introducing the ellipsis, uses 2 of them directly, with one nested! It also doesn't explain what the pattern variables are bound to when an ellipsis is involved. Also, the example data you're matching on looks too intimidating, which could scare novice readers. Best, -- Josselin Poiret