Re: [PATCH v3 2/2] blame: document --color-* options

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 4, 2021, 11:41 UTC
Message-ID: <xmqqk0itxbjn.fsf@gitster.g>
In-Reply-To: <e70942cd-8362-b8d0-f168-01f6c190fb0b@gmail.com>

Bagas Sanjaya <bagasdotme@gmail.com> writes:

Show 17 quoted lines

> On 02/10/21 02.10, Eric Sunshine wrote:
>>> +       config option. Only the line annotation (see "The Default Format" section)
>>> +       is colored.
>> You can drop the last sentence entirely if you start the blurb like
>> this:
>>      Color line annotations differently, if...
>> 
>>> +--color-by-age::
>>> +       Color lines depending on the age of the line. The `color.blame.highlightRecent`
>>> +       config option controls what color is used for which range of age. Only the
>>> +       line annotation (see "The Default Format" section) is colored.
>> Ditto about dropping the last sentence.
>>      Color line annotations depending upon the age of the line.
>> 
>
> I observed that both --color-lines and --color-by-age only apply to
> default blame format, ...

Technically, it is sufficient to say "color line annotations" because the default format is the only one that is described to give "line annotations". I do not think it would hurt too much to be a bit more explicit, perhaps like:

    Color line annotations, depending upon the age of the line, in
    the default output format.

I personally feel "(see section X)" is being a bit more ditracting than being helpful to readers.

Thanks.