Re: [PATCH 1/6] doc: stripspace: mention where the default comes from

From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date: May 21, 2025, 15:04 UTC
Message-ID: <817a28ae-b7dc-44ce-9ae4-2527081745da@app.fastmail.com>
In-Reply-To: <xmqqjz6bhzkm.fsf@gitster.g>

On Tue, May 20, 2025, at 21:06, Junio C Hamano wrote:

Show 25 quoted lines

>> diff --git a/Documentation/git-stripspace.adoc b/Documentation/git-stripspace.adoc
>> index a293327581a..1132a4cf9a9 100644
>> --- a/Documentation/git-stripspace.adoc
>> +++ b/Documentation/git-stripspace.adoc
>> @@ -37,7 +37,8 @@ OPTIONS
>>  -------
>>  -s::
>>  --strip-comments::
>> -	Skip and remove all lines starting with a comment character (default '#').
>> +	Skip and remove all lines starting with a comment character (default `#`).
>> +	See `core.commentChar` in linkgit:git-config[1].
>
> I've seen this kind of thing treat the configuration as the first
> level default, with the hardcoded value as a fallback, i.e. spelling
> it more like this:
>
>     ... a comment character.  Defaults to `core.commentChar`, which
>     in turn defaults to `#`.
>
> The way you phrased is syntactically easier to parse, but to some
> readers, the readon why they are encouraged to learn about the
> `core.commentChar` configuration may not be immediately obvious, so
> I dunno.
>
> Thanks.

I’m fine with that too. I ended up with this version because I tried to avoid complex sentences. But it’s best to avoid a new paragraph.

Another alternative:

    a comment character (`core.commentChar`, default `#`)

And the linkgit to git-config(1) is probably not needed on this kind of doc.

-- 
Kristoffer