From: Dragan Simic <dsimic@manjaro.org>
Date: Thu, 21 Mar 2024 05:16:01 GMT
Subject: Re: [PATCH v4 4/4] config.txt: describe handling of whitespace further
Message-ID: <9a5217f7f7a35768a3eb45060fb3e4f4@manjaro.org>
In-Reply-To: <CAPig+cSYhYBa0NsvJCOYo4JsWzLJT9rU++U1QKA3jRB6Cptbhw@mail.gmail.com>

On 2024-03-21 06:11, Eric Sunshine wrote:
> On Thu, Mar 21, 2024 at 12:17 AM Dragan Simic <dsimic@manjaro.org> 
> wrote:
>> Make it more clear what the whitespace characters are in the context 
>> of git
>> configuration files, and significantly improve the description of the 
>> leading
>> and trailing whitespace handling, especially how it works out together 
>> with
>> the presence of inline comments.
>> 
>> Helped-by: Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
>> ---
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> @@ -63,13 +64,15 @@ the variable is the boolean "true").
>>  A line that defines a value can be continued to the next line by
>> +ending it with a `\`; the backslash and the end-of-line are stripped.
>> +Leading whitespace characters before 'name =' are discarded.
>> +The portion of the line after the first comment character, including
>> +the comment character itself, is discarded.  Unless enclosed in 
>> double
>> +quotation marks (`"`), any leading or trailing whitespace characters
>> +surrounding 'value' are discarded.  Internal whitespace characters
>> +within 'value' are retained verbatim.
> 
> I find this statement confusing and ambiguous:
> 
>     Unless enclosed in double quotation marks (`"`), any leading or
>     trailing whitespace characters surrounding 'value' are discarded.
> 
> since it might imply that the shown <SP> and <TAB> whitespace is
> retained outside the quotes, as well:
> 
>     key =<SP><TAB>" string "<SP>
> 
> It should be possible to rephrase it to be more definite, while
> dropping the final sentence altogether. Perhaps:
> 
>     Whitespace surrounding `name`, `=` and `value` is ignored. If
>     `value` is surrounding by double quotation marks (`"`), all
>     characters within the quoted string are retained verbatim,
>     including whitespace. Comments starting with either `#` or `;` and
>     extending to the end of line are discarded. A line that defines a
>     value can be continued to the next line by ending it with a `\`;
>     the backslash and the end-of-line are stripped.

Looking good to me, thanks.  I'll include it into the v5, with
a small grammar issue fixed.