RE: Man pages have colors? A deep dive into groff

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 17, 2021, 23:33 UTC
Message-ID: <60a2fd5d52740_1461a92083d@natae.notmuch>
In-Reply-To: <00b701d74b6f$aa295ed0$fe7c1c70$@nexbridge.com>

Randall S. Becker wrote:

Show 19 quoted lines

> On May 17, 2021 6:44 PM, Felipe Contreras wrote:
> >Junio C Hamano wrote:
> >> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> >>
> >> > This looks much better.
> >> >
> >> > I wonder a good follow-up (hint, hint! :) would be to have
> >> > exec_man_man() and exec_man_cmd() in builtin/help.c set this
> >> > depending on color.ui (so we'd do it by default with "auto").
> >> >
> >> > Then e.g. "git help git" would look prettier than "man git".
> >>
> >> As long as color.man.ui can be used to override the blanket color.ui,
> >> I think it is a good idea.
> >
> >Why not use color.pager?
> 
> I think there is a lesson to be learned from git checkout;
> specifically not to overload semantics.

> Manual representation is a presentation world unto itself that has
> should not be blended with programs like less.

Huh? man is basically a grapper for `groff | less`:

From man(1): "man is the system's manual pager".

You could use it for other purposes, like generating DVI files, but that's not how git uses it. We it in the normal mode, which uses the environment variable MANPAGER.

This has absolutely nothing to do with man:

  export GROFF_NO_SGR=1
  export LESS_TERMCAP_md=$'\e[1;31m'
  export LESS_TERMCAP_me=$'\e[m'
  zcat /usr/share/man/man1/git.1.gz | groff -T utf8 -m man | less -R

> More than that, being someone who loves automated
> documentation generation, manual representation has a broader semantic
> that should not be dismissed.

But what does that have to do with `git help`?

> There are probably a whole class of colours that ultimately might be
> requested - might be me - so I'd rather not blend these into
> color.pager.

But it's 100% pager-dependent. Not only do you need a pager for this to work, but you need specifically the `less` pager.

This:

  MANPAGER=more git -c color.man=always help git

Would not work, because `more` doesn't read use the LESS_TERMCAP variables.

So why call it color.man, if it's not really a man thing?

Cheers.

-- 
Felipe Contreras