Subject: Re: [PATCH v6] help: colorize man pages

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Tue, 08 Jun 2021 14:35:24 +0200

On Sun, May 23 2021, Felipe Contreras wrote:

> We already colorize tools traditionally not colorized by default, like
> diff and grep. Let's do the same for man.
>
> Our man pages don't contain many useful colors (just blue links),
> moreover, many people have groff SGR disabled, so they don't see any
> colors with man pages.
>
> We can set LESS_TERMCAP variables to render bold and underlined text
> with colors in the pager; a common trick[1].
>
> Bold is rendered as red, underlined as blue, and standout (prompt and
> highlighted search) as inverse cyan.
>
> Obviously this only works when the less pager is used.
>
> If the user already has LESS_TERMCAP variables set in his/her
> environment, those are respected and nothing changes.
>
> A new color configuration is added: `color.man` for the people that want
> to turn this feature off, otherwise `color.ui` is respected.
> Additionally, if color.pager is not enabled, this is disregarded.
>
> Normally check_auto_color() would check the value of `color.pager`, but
> in this particular case it's not git the one executing the pager, but
> man. Therefore we need to check pager_use_color ourselves.
>
> Also--unlike other color.* configurations--color.man=always does not
> make any sense here; `git help` is always run for a tty (it would be very
> strange for a user to do `git help $page > output`, but in fact, that
> works anyway, we don't even need to check if stdout is a tty, but just
> to be consistent we do). So it's simply a boolean in our case.
>
> So, in order for this change to have any effect:
>
>  1. The user must use less
>  2. Not have the same LESS_TERMCAP variables set
>  3. Have color.ui enabled
>  4. Not have color.pager disabled
>  5. Not have color.man disabled
>  7. Not have git with stdout directed to a file
>
> Fortunately the vast majority of our users meet all of the above, and
> anybody who doesn't would not be affected negatively (plus very likely
> comprises a very tiny minority).
>
> [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
>
> Suggested-by: Ævar Arnfjörð Bjarmason <[email-masked]>
> Phillip Wood <[email-masked]>
> Comments-by: Jeff King <[email-masked]>
> Signed-off-by: Felipe Contreras <[email-masked]>
> ---

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 for one would like to have this picked up by Junio.

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.

We have a wider audience running "next" than "seen" (but this didn't
even make "seen"), if this were to make it into a release and users
overwhelmingly dislike it it's no big deal. There's a config option to
turn it off, and/or we could make it opt-in later.

Alternatively this could be opt-in and not fall under the color.ui=auto
umbrella, or only in combination with feature.experimental (or a new
ui.experimental?, which would default to that?).

But in any case if judgement call UI changes are always hidden behind
options we'll never make forward progress on things that are possibly
better defaults (and if they're not, we can always simply revert the
change).