[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#53439] [PATCH] doc: Document search paths.
From: |
Maxim Cournoyer |
Subject: |
[bug#53439] [PATCH] doc: Document search paths. |
Date: |
Mon, 24 Jan 2022 16:06:50 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) |
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
Message not available