Re: [PATCH] help: colorize man pages

[Felipe Contreras <felipe.contreras@gmail.com>]

Ævar Arnfjörð Bjarmason wrote:
> 
> On Tue, May 18 2021, brian m. carlson wrote:
> 
> > [[PGP Signed Part:Undecided]]
> > On 2021-05-18 at 03:22:37, Felipe Contreras wrote:
> >> brian m. carlson wrote:
> >> > I think we should let the user decide whether they want to set this
> >> > feature themselves instead of setting it for them.  For example, I have
> >> > specific colors set up with these environment variables, and I'd like
> >> > Git to honor them without having to configure Git independently of less.
> >> > I expect other users will expect Git's rendering of the manual pages to
> >> > work like other instances of man(1) on their system as well.
> >> 
> >> It does respect them.
> >> 
> >> This would render the man page with the color specified in the
> >> environment, not the default of git.
> >> 
> >>   LESS_TERMCAP_md=$'\e[1;33m' LESS_TERMCAP_me=$'\e[m' git help git
> >
> > It still doesn't work like other instances of man(1) on the system.
> > While you claimed that "that's a preference others don't share", I'm
> > pretty certain that I'm not the only person who feels this way.
> >
> > There's a big difference between Git coloring a Git UI, like a diff, and
> > Git coloring a separate program that already has sensible, standard
> > defaults.  A user who has not configured any color settings would
> > probably not want Git to render manual pages one way, cargo to render
> > manual pages a second way, and still other programs to render manual
> > pages in other, incompatible ways.  We need to consider not only the
> > impact that our decisions have in a vacuum, but what results similar
> > decisions from other projects would produce in the software ecosystem as
> > a whole.
> >
> > Would you consider various projects coloring their respective manual
> > pages differently to be a desirable state of affairs?
> 
> I think it's an important distinction that we're not coloring any manual
> pages,

But we *are* coloring man pages. The docbook stylesheets format links as
blue.

Try this:

  GROFF_SGR=1 man git

> Right now our documentation seems to suggest that we won't do any such
> magic, but you can also set man.viewer to e.g. invoke a web browser or
> something instead of man(1).
> 
> I don't think it's confusing in that context if we learn to do some "man
> with fancy on top" in this mode.

But man already does fancy stuff.

You can open a browser:

  man -Hchromium git

You display some shitty X viewer:

  man -X git

You can send the man page to a printer, or generate a DVI file.

The pager mode in man is also just one of many modes.

I think most people have not read man man.

> I'm not running the patch in this thread currently, but I'm running with
> Felipe's earlier man alias noted in the other thread. So I see how
> losing the underline would be confusing.

But in my patch you don't lose the underline.

The function version I sent was an updated version of something I've
been using for a long time. But I did more effort in the version for
wide consumption, and the underline is preserved.

This is the equivalent of my latest patch:

  man () {
    GROFF_NO_SGR=1 \
    LESS_TERMCAP_md=$'\e[1;31m' \
    LESS_TERMCAP_me=$'\e[m' \
    LESS_TERMCAP_us=$'\e[1;34m\e[4m' \
    LESS_TERMCAP_ue=$'\e[m' \
    LESS_TERMCAP_so=$'\e[1;35m\e[7m' \
    LESS_TERMCAP_se=$'\e[m' \
    command man "$@"
  }

> I think there's good arguments for/against that, but I do think that
> ultimately it was a good choice, and programs such as hg(1) seemed to
> since have moved to git's more aggressive "color by default" stance.

I would say a lot of programs have been doing that, and I like it. The
last one I discovered is jq.

> > I should clarify that the patch doesn't permit them to be configured
> > using the normal Git mechanisms.  For example, unless the user sets the
> > environment variables, which take effect globally, they're stuck with
> > the colors that we've chosen here.  Yes, they can specify a single
> > environment variable before the command, but practically nobody will do
> > that.
> >
> > It's my argument that the user doesn't want Git manual pages to be
> > colored differently than other manual pages on the system, but if you
> > believe differently, then we should allow the user to configure the
> > colors that are used in the Git-specific context using Git standard
> > mechanisms.
> 
> I'm in vehement agreement about this. If we do invoke "man" differently
> based on how we'd do coloring for any other git program we invoke, we
> should of course be respecting the same configuration
> mechanisms. I.e. it should respect color.ui=auto etc., you shouldn't
> need to set LESS_TERMCAP_md or whatever.

Yes, but good software is developed in stages.

You shouldn't expect a first patch to provide all the functionality in
the world. Not only does it take longer, increase the review burden, and
generate longer disucssions, but it increases the probability of the
feature never been merged.

Plus increases the probability of bugs bein introduced.

More features can be added later.

What is important is that users don't lose anything from what they have
now.

And unconfigurable colors is better than what they have now... Nothing.

> In any case, I think for these defaults we need to be considering the
> vast majority of users, who are mostly interfacing with one or two
> computers in their use of "git", and who are running some modern OS that
> supports terminal coloring, which is why color.ui=auto became the
> default (to some objections at the time, but I think those have gotten
> less prominent as time marched on).

Exactly.

Moreover, if colors are really that bad, then users will complain (I bet
they won't), and then we can switch this off by default.

Easy.

-- 
Felipe Contreras