Subject: Re: Man pages have colors? A deep dive into groff

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Mon, 17 May 2021 18:48:04 +0200

On Sat, May 15 2021, Felipe Contreras wrote:

> Hi,
>
> While I was doing the investigagion for my GNU_ROFF patch [1], I checked
> different versions of all the tools (asciidoc, asciidoctor, docbook, and
> groff).
>
> When I tested my own compiled version of groff I noticed something
> weird: man pages have colors. This did not happen with the version
> shipped by Arch Linux.
>
> I did notice the output generated by docbook stylesheets showed
> \m[blue], but no color showed up.
>
> It turns out Arch Linux disables colors, and so does Debian, by
> disabling a feature called SGR. This happened about 10 years, and the
> rationale was that "it doesn't work correctly".
>
> To enable SGR on these distributions you need to do GROFF_SGR=1, but
> that is not documented anywhere.
>
> groff does check for a variable GROFF_NO_SGR, but it's the other way
> around: SGR is enabled unless that variable is set.
>
> There's other ways your distribution might be screwing up with groff
> (for example Arch Linux converts \' to ', which is not correct), so you
> might want to check your shipped configuration in:
>
>   /usr/share/groff/site-tmac/man.local
>
> Unfortunately the colors in man pages leave a lot to be desired.
>
> Here is a simple trick I've been using to show some custom colors:
>
>   man() {
>     GROFF_NO_SGR=1 \
>     LESS_TERMCAP_md=$'\e[1;31m' \
>     LESS_TERMCAP_me=$'\e[0m' \
>     LESS_TERMCAP_us=$'\e[1;34m' \
>     LESS_TERMCAP_ue=$'\e[0m' \
>     LESS_TERMCAP_so=$'\e[1;35m' \
>     LESS_TERMCAP_se=$'\e[0m' \
>     command man "$@"
>   }
>
> Hopefully some of you might find this useful.
>
> Cheers.
>
> [1] https://lore.kernel.org/git/[email-masked]/

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