Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jun 21, 2021, 19:08 UTC
Message-ID: <87mtrj2faq.fsf@evledraar.gmail.com>
In-Reply-To: <xmqqfsxbika3.fsf@gitster.g>

On Mon, Jun 21 2021, Junio C Hamano wrote:

Show 59 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> So, in order for this change to have any effect:
>>
>>  1. color.man=true must be set in the config
>>  2. The user must use less
>>  3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
>>  4. Have color.ui enabled
>>  5. Not have color.pager disabled
>>  6. Not have git with stdout directed to a file
>>
>> 1. https://lore.kernel.org/git/87tun1qp91.fsf@evledraar.gmail.com/
>> 2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
>>
>> Suggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>>
>> On Tue, Jun 08 2021, Junio C Hamano wrote:
>>
>>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>>>
>>>> I've been running with this on my personal git build since May 26th. I
>>>> haven't had any issues with it, and I like the new coloring.
>>>> ...
>>>> I think this is a good example of a change that we're better off just
>>>> merging down and then reverting if the wider audience of git users hates
>>>> it, rather than trying to come to some perfect consensus here
>>>> on-list.
>>>
>>> My impression was tht we already had a rough consensus here on-list
>>> that it may be good to educate users who like this "new coloring"
>>> like you do to configure their "less", so that they consistently get
>>> the "new coloring" they like whether they are doing "git help git",
>>> "man git", or even "man ls", and the approach the posted patch takes
>>> will not help (it only affects "git help git" among these).
>>>
>>> I'd rather not to take it.
>>
>> Fair enough, here's a version I think you and others will find
>> acceptable then. It allows users like me who like this to explicitly
>> opt-in via color.man=true.
>
> Not really.
>
> [snip] I think it would be easier to understand to end-users
> if this were exposed as a new "mode", like "git help --web" and "git
> help --info" are different modes from the "git help --man",
> something like "git help --fancy-man" (or whatever is easy to type
> and explain, and also add it to the variants help.format knows about
> to make it easy to set the default).
>
> One advantage of doing so is that we do not have to worry about "ah,
> user has LESS_BLAH environment variable so we should disable this
> new mode here" etc.  As long as the new mode is requested either via
> the command line option or help.format configuration, it can
> completely take it over.  That simplifies the necessary explanation
> given to the users quite a lot, no?

The interaction between "git help" and "man"/"less" doesn't really have an equivalent in the rest of git as far as color output goes. Usually we emit colors via our own programs.

But no, I think it makes the most sense to consider this orthagonal to help.format=man or man.viewer=<cmd>.

We're not invoking a different man viewer or command, we're just expecting that mode to invoke the pager, and if that pager is less to have these variables tweak our color preferences.

> [unsnip] Since the implementation of the posted patch, as I understand it,
> does not aim to affect both "git help -m foo" and "man git-foo"
> identically,

Aside from this patch I don't think it makes sense to view git's UI and interaction with the pager like that.

To probably >95% of our users the "we invoke the pager" is just a technical implementation details they're not aware of. Git just has pretty colors by default, so I don't think it's jarring that "git help xyz" and "man git-xyz" look different.

We also don't try to maintain the UI that:

    git cmd >file &&
    pager file

Gives you the same UX as:

    # Invokes pager(1) for you
    git cmd

Since we set e.g. PAGER_ENV already, I believe this was brought up in past discussions. So we're already past the point of git adding its own magic custom options to feed to the pager.

So I don't see the problem with having "a bit more like PAGER_ENV" hidden behind a color.man=true config option in this case.

Show 18 quoted lines

>> 	----
>> 	git-config - Get and set [...]
>>
>> 	SYNOPSIS
>> 	--------
>> 	[...]
>> 	'git config' [<file-option>] [...]
>> 	[...]
>> 	The `--type=<type>` option instructs 'git config' to ensure [...]
>>
>> Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git
>> config" and other '-quoted parts in BLUE UNDERLINE instead of
>> UNDERLINE, and `--type=<type>` and other `-quoted parts in RED BOLD
>> instead of BOLD. The "Standout" setting is then used for the user's
>> own search bar (invoked with "/") and prompt. See [2] for more
>> examples
>
> There are BOLD RED and READ BOLD; are they differently rendered?

Yes, that's just an omission/mistake. It should be the "RED BOLD", i.e. "<COLOR> <ATTR>".