Re: [PATCH v4 4/4] config.txt: describe handling of whitespace further

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 21, 2024, 05:11 UTC
Message-ID: <CAPig+cSYhYBa0NsvJCOYo4JsWzLJT9rU++U1QKA3jRB6Cptbhw@mail.gmail.com>
In-Reply-To: <f84c5e8e4a90be3f9fe3cc853e0d40aed4e58826.1710994548.git.dsimic@manjaro.org>

On Thu, Mar 21, 2024 at 12:17 AM Dragan Simic <dsimic@manjaro.org> wrote:

Show 18 quoted lines

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