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

Previous Next

Full log

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

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: 53439 <at> debbugs.gnu.org
Subject: Re: bug#53439: [PATCH] doc: Document search paths.
Date: Tue, 25 Jan 2022 14:06:47 +0100

Hello,

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

> Ludovic Courtès <ludo <at> 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’.

Previous Next

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