From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id mLdxAt4Q8GFRywAAgWs5BA (envelope-from ) for ; Tue, 25 Jan 2022 16:01:50 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id COXiNN0Q8GEXLAAAG6o9tA (envelope-from ) for ; Tue, 25 Jan 2022 16:01:49 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 960984275D for ; Tue, 25 Jan 2022 16:01:49 +0100 (CET) Received: from localhost ([::1]:46294 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nCNKO-0000iG-JX for larch@yhetil.org; Tue, 25 Jan 2022 10:01:48 -0500 Received: from eggs.gnu.org ([209.51.188.92]:39792) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nCLXL-0007sK-9G for guix-patches@gnu.org; Tue, 25 Jan 2022 08:07:08 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:54415) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nCLXK-00035U-Hz for guix-patches@gnu.org; Tue, 25 Jan 2022 08:07:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nCLXK-0000A1-Bo for guix-patches@gnu.org; Tue, 25 Jan 2022 08:07:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#53439] [PATCH] doc: Document search paths. Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 25 Jan 2022 13:07:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 53439 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Maxim Cournoyer Cc: 53439@debbugs.gnu.org Received: via spool by 53439-submit@debbugs.gnu.org id=B53439.1643116017606 (code B ref 53439); Tue, 25 Jan 2022 13:07:02 +0000 Received: (at 53439) by debbugs.gnu.org; 25 Jan 2022 13:06:57 +0000 Received: from localhost ([127.0.0.1]:47318 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nCLXF-00009h-Ao for submit@debbugs.gnu.org; Tue, 25 Jan 2022 08:06:57 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:55388) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nCLXC-00009U-Fl for 53439@debbugs.gnu.org; Tue, 25 Jan 2022 08:06:55 -0500 Received: from localhost (localhost [127.0.0.1]) by hera.aquilenet.fr (Postfix) with ESMTP id 96BF5A4; Tue, 25 Jan 2022 14:06:48 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at aquilenet.fr Received: from hera.aquilenet.fr ([127.0.0.1]) by localhost (hera.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id m75HtthaVc_y; Tue, 25 Jan 2022 14:06:48 +0100 (CET) Received: from ribbon (91-160-117-201.subs.proxad.net [91.160.117.201]) by hera.aquilenet.fr (Postfix) with ESMTPSA id A30259D; Tue, 25 Jan 2022 14:06:47 +0100 (CET) From: Ludovic =?UTF-8?Q?Court=C3=A8s?= References: <20220122104757.1837-1-ludo@gnu.org> <87pmoj6tr0.fsf@gmail.com> <875yqayvuw.fsf_-_@gnu.org> <87r18w6dxx.fsf@gmail.com> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 6 =?UTF-8?Q?Pluvi=C3=B4se?= an 230 de la =?UTF-8?Q?R=C3=A9volution?= X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu Date: Tue, 25 Jan 2022 14:06:47 +0100 In-Reply-To: <87r18w6dxx.fsf@gmail.com> (Maxim Cournoyer's message of "Mon, 24 Jan 2022 16:06:50 -0500") Message-ID: <87a6fknevs.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spamd-Bar: / X-Rspamd-Server: hera X-Rspamd-Queue-Id: 96BF5A4 X-Spamd-Result: default: False [-0.10 / 15.00]; ARC_NA(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; FROM_HAS_DN(0.00)[]; TO_DN_SOME(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; FREEMAIL_ENVRCPT(0.00)[gmail.com]; TAGGED_RCPT(0.00)[]; MIME_GOOD(-0.10)[text/plain]; RCPT_COUNT_TWO(0.00)[2]; FREEMAIL_TO(0.00)[gmail.com]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[]; MID_RHS_MATCH_FROM(0.00)[] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1643122909; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=rwAwIZ+Y+RaQ1t2ZZ4jInFyr2rjJjoppzxSxURtrPtM=; b=nYeGtR88RI1EuX1XHHeCEEFRTPL1yZ1yhHv0PKIf8rv5pPpbbZQkqWFxyoLb3AGwvKPG5W sGEyRa47dwZ/iqTEadsYBRZx5+5oNEzleAyB6CBXKalxul5iYDLz9nQyT2IQkNVWu+RdqL /t8wHYCK3NJ0FJGp/CTVYDYvxc3dsNI404qXwjN63DT9VLBRC9z4VPYip8/YgLZw6ynLz3 7q8ygwSosVE5qCRi6xxKykeq1hjKgalX5rtzRwqTrUy+EULT8fi47twKNPCX4nrj3qa29q A5HerBrOFje84OOFneAzUAbPsY294TXPcIPuZzUgyN6/nGgsxHjnL4srXxCVoA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1643122909; a=rsa-sha256; cv=none; b=GL91s9DeVlEipvI13SYBDEJFn/vLpG3ntNp5Vg0Fcu5/JiDIoJSxXNsOGufer//ekQMZfs o52Kh4jeW9Ft5YURgOdXVgXCctPi/VsH3Sjm07wBa78zVpZDo82jUlEuhKD3I06bQqjhuq 7Vy83B8cje9iQJZjln33bu1eDV0KOecJj97H1WamUJQlxIYSdNBQ4K9pDRgmvC6UhAsaVI GZWBiTznD0n9eI3sv0c62OlGwkREBmjMJ9zl9XXIkIKcz1fCfhTmiJSZXzL4aHVE/YogAI kddoATk1y0afj0/S0VgQAvReJ0K5Q+lp5YnWuSK3HiemtHV/eFN7jjExG7l78Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -5.13 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 960984275D X-Spam-Score: -5.13 X-Migadu-Scanner: scn0.migadu.com X-TUID: RopVKrOz/oKx Hello, Maxim Cournoyer skribis: > Ludovic Court=C3=A8s writes: [...] >> =E2=80=9CWhen true=E2=80=9D is to be taken literally: if it has truth va= lue, in the >> Scheme sense. But =E2=80=9CUnless @code{#f}=E2=80=9D might be clearer? >> >> (=E2=80=9COptional=E2=80=9D sounds confusing to me because there has to = be a value, >> default or not.) > > From the user point of view, specifying it is really optional though. Yes, that=E2=80=99s what the =E2=80=9C(default: @code{#f})=E2=80=9D bit con= veys. > Yours is more correct but perhaps confusing to those not knowing a > string is truthy in Guile (and I'd argue it takes attention away from > what is important here). > > What I had on mind was: > > "An optional regular expression to specify which files should be > matched, based on their base name." or similar. > > (optional because if you don't specify it defaults to #f, which means > "no added behavior"). > > I've used that approach when describing optional fields of service > configurations in the past. OK. The way I see it, that it=E2=80=99s optional is already implied by the= fact it has a default value. Regarding the truth value, I ended up in a00dff3ac113722a709dbe97a727777b3739a5c1 with hopefully clearer wording: @item @code{file-pattern} (default: @code{#f}) This must be either @code{#f} or a regular expression specifying files to be matched @emph{within} the sub-directories specified by the @code{files} field. I guess we=E2=80=99re nitpicking :-) but I like to have, on one hand, text = in natural language with examples that conveys ideas in an informal way, and on the other hand, reference material (@deftp, @deffn, etc.) that=E2=80= =99s rigorous. Ludo=E2=80=99.