GNU bug report logs - #53439
[PATCH] doc: Document search paths.

Previous Next

Full log

Message #34 received at 53439 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: 53439 <at> debbugs.gnu.org
Subject: Re: bug#53439: [PATCH] doc: Document search paths.
Date: Mon, 24 Jan 2022 16:06:50 -0500

Hi Ludovic,

Ludovic Courtès <ludo <at> gnu.org> writes:

> Hi,
>
> Maxim Cournoyer <maxim.cournoyer <at> gmail.com> skribis:
>
>> Ludovic Courtès <ludo <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.