Re: [PATCH] doc: clarify "config --bool" behaviour with empty values

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 14, 2017, 22:21 UTC
Message-ID: <xmqqlgmlu6y7.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <914098af-00a9-fbc8-cdfe-a65918b2951b@gmail.com>

Andreas Heiduk <asheiduk@gmail.com> writes:

Show 12 quoted lines

>> However, I think this "no value (but still with '=')" is making it
>> more confusing than necessary for two reasons.
> [...]
>  
>> I notice that in this Values section (where the boolean:: is the
>> first entry) there is no mention on how to spell a string value.
>
> I assumed this is due to the pretext of the definition list:
>
> 	Values of many variables are treated as a simple string, but there
> 	are variables that take values of specific types and there are rules
> 	as to how to spell them.

I assumed so too.

But if you knew that "[section] var =" is a valid way to spell an empty string, I'd thought that you wouldn't have written "no value but still with '=')" there.

The description for "true" (i.e. "[section] var" and nothing else) is also spelled out perfectly well in the Syntax section, but it is duplicated in Values section. I think that it is a good thing to have the complete picture in a single Values section, without assuming readers to know what is in the other Syntax section.

So if it bothers you to have a non-specific "string" description in the Values section, I think it would be more helpful to update the pretext so that including the description of a simple string there does not look unnatural, IMHO.