Man pages have colors? A deep dive into groff

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/20210515115653.922902-2-felipe.contreras@gmail.com/

-- 
Felipe Contreras

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/20210515115653.922902-2-felipe.contreras@gmail.com/

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

On 2021-05-17 at 16:48:04, Ævar Arnfjörð Bjarmason wrote:

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 I mentioned on the patch itself, I'd prefer if Git didn't do this.  I
have my own colors configured and don't want Git to render its man
output differently from what I have.  Even if I didn't, I wouldn't want
Git to change the output of man(1) to be different from what's on the
system.

I should point out that I have my shell configuration set up to use
different colors depending on the capability of the terminal, such as
using a 256-color palette when that's supported and a 16-color palette
when it's not, so there is literally no configuration that Git can
provide here that matches my existing settings.

Additionally, colors tend to pose accessibility problems for a lot of
people.  I have normal color vision, but because I use a transparent
background which renders as grey, the standard terminal red is nearly
illegible for me.  I also know people with colorblindness who have
problems with various colors or any colors at all.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

brian m. carlson wrote:

On 2021-05-17 at 16:48:04, Ævar Arnfjörð Bjarmason wrote:

quoted

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 I mentioned on the patch itself, I'd prefer if Git didn't do this.  I
have my own colors configured and don't want Git to render its man
output differently from what I have.

It won't.

Even if I didn't, I wouldn't want Git to change the output of man(1)
to be different from what's on the system.

That's a preference others don't share.

I should point out that I have my shell configuration set up to use
different colors depending on the capability of the terminal, such as
using a 256-color palette when that's supported and a 16-color palette
when it's not, so there is literally no configuration that Git can
provide here that matches my existing settings.

Once again; your configuration is not going to be overridden.

Additionally, colors tend to pose accessibility problems for a lot of
people.  I have normal color vision, but because I use a transparent
background which renders as grey, the standard terminal red is nearly
illegible for me.  I also know people with colorblindness who have
problems with various colors or any colors at all.

Their configuration won't be overridden either.

-- 
Felipe Contreras