From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: 53439@debbugs.gnu.org
Subject: [bug#53439] [PATCH] doc: Document search paths.
Date: Mon, 24 Jan 2022 16:06:50 -0500 [thread overview]
Message-ID: <87r18w6dxx.fsf@gmail.com> (raw)
In-Reply-To: <875yqayvuw.fsf_-_@gnu.org> ("Ludovic Courtès"'s message of "Sun, 23 Jan 2022 22:40:07 +0100")
Hi Ludovic,
Ludovic Courtès <ludo@gnu.org> writes:
> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>>> * doc/guix.texi (package Reference): Link to "Search Paths".
>>> (Build Phases): Mention 'set-paths' phase.
>>> (Search Paths): New node.
>>> ---
>>> doc/guix.texi | 184 +++++++++++++++++++++++++++++++++++++++++++++++++-
>>> 1 file changed, 183 insertions(+), 1 deletion(-)
>>
>> [...]
>>
>>> +@item @code{file-type} (default: @code{'directory})
>>> +The type of file being matched.
>>> +
>>> +In the libxml2 example above, we would match regular files.
>>
>> Here I am left wondering what other valid values (other than 'regular or
>> 'directory) may be? I remember trying to find such answer, and it was
>> not obvious (I can't remember where the answer lies in the Guile manual
>> as I type this!).
>
> Oh right, these are the symbols returned by ‘stat:kind’. I’ll clarify
> that.
>
>>> +@item @code{file-pattern} (default: @code{#f})
>>> +When true, this is a regular expression specifying files to be
>>> matched
>>
>> I'd replace "When true", which I find confusing, by 'Optional' or
>> similar.
>
> “When true” is to be taken literally: if it has truth value, in the
> Scheme sense. But “Unless @code{#f}” might be clearer?
>
> (“Optional” 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.
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.
My 2 cents, and either way I'm fine with it :-)
Thanks,
Maxim
next prev parent reply other threads:[~2022-01-24 21:07 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-01-22 10:47 [bug#53439] [PATCH] doc: Document search paths Ludovic Courtès
2022-01-22 12:49 ` Maxime Devos
2022-01-22 15:54 ` Ludovic Courtès
2022-01-22 12:54 ` Maxime Devos
2022-01-22 13:00 ` Maxime Devos
2022-01-23 3:00 ` Maxim Cournoyer
2022-01-23 21:40 ` Ludovic Courtès
2022-01-23 22:41 ` bug#53439: " Ludovic Courtès
2022-01-24 21:06 ` Maxim Cournoyer [this message]
2022-01-25 13:06 ` [bug#53439] " Ludovic Courtès
2022-01-26 1:50 ` Maxim Cournoyer
[not found] ` <handler.53439.D53439.164297769417402.notifdone@debbugs.gnu.org>
2022-01-24 9:41 ` Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87r18w6dxx.fsf@gmail.com \
--to=maxim.cournoyer@gmail.com \
--cc=53439@debbugs.gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).