[bug#53439] [PATCH] doc: Document search paths.

[Maxim Cournoyer]

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