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

["Ludovic Courtès" <ludo@gnu.org>]

Hello,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

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

[...]

>> “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.

Yes, that’s what the “(default: @code{#f})” bit conveys.

> 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’s 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’re 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’s
rigorous.

Ludo’.