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

From: Junio C Hamano <[email-masked]>
Date: Mon, 04 Oct 2021 04:41:00 -0700

Bagas Sanjaya <[email-masked]> writes:

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