Re: [PATCH] help: colorize man pages

["brian m. carlson" <sandals@crustytoothpaste.net>]

[-- Attachment #1: Type: text/plain, Size: 7583 bytes --]

On 2021-05-19 at 09:26:12, Ævar Arnfjörð Bjarmason wrote:
> 
> On Tue, May 18 2021, brian m. carlson wrote:
> 
> > 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, it's a question of whether we invoke "man" invoked by "git help
> <whatever>" with the exact same paramaters/options a user would get with
> "man git-<whatever>".

Yes.  I would expect that if the man option is chosen, then we invoke
man without modification.  If I wanted different options, I would have
specified a custom viewer with different options.  For example, I would
be equally annoyed if Git decided to use a completely different pager
for man output than I would normally use to make it "fancy".

The documentation says, "use the man program as usual".  "As usual"
implies the way the user would invoke it.

If we want to add an option for special coloring or modifications, then
we should add an option --fancy-man, where we do something other than
invoking man as normal.

If we were doing our own man-like documentation and not specifically
using man, then I would agree that we'd be free to color it without
relying on the user's expectations about how man works otherwise
(although other objections still apply).

> I don't think it's confusing in that context if we learn to do some "man
> with fancy on top" in this mode.

I think it's confusing if Git does fancy one way, and other projects
which invoke man like cargo do it another way.  It's pretty obvious that
"git help commit" and "cargo help build" both are intended to invoke man
when used in the normal way.

> >> > Additionally, using colors poses accessibility problems.  I know someone
> >> > who, due to his colorblindness, finds terminal colors distracting and
> >> > hard to read, and prefers not to use them at all.
> >> 
> >>   git -c color.ui=never help git
> >
> > Yes, but unfortunately, since you've colored the manual pages, they may
> > be hard to read for the user who needs to read them to learn about your
> > configuration.  This is great for you and me, who are already very
> > familiar with Git and know how to do that without looking, but not great
> > for the novice colorblind user.
> 
> Is the objection here against the use of color, or that we e.g. replace
> grey bold underline with blue bold, as opposed to blue bold underline?
> 
> 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 if colors only add, but don't substract information by default
> that's not an issue for the color blind, correct? Or at least that's
> been my understanding in helping color blind user in the past (and not
> being color blind myself).

The problem becomes if the color is indistinguishable from other
elements.  For example, I have a friend who has deuteranopia who sees
green as very similar to grey.  Therefore, an environment where a text
is green and the background is grey, without significant differences in
lightness, will likely be illegible for him.

It is _also_ a problem if we have two colors with sufficient contrast
between the foreground and background but those colors look the same and
there is no other distinguishing factor.

So, yes, if the colors only add information and they can otherwise be
distinguished, then it's fine.  However, we're not setting the
background here, only the foreground, and we don't know how the user has
configured their terminal background.

In my particular case, I have a semi-transparent background, which,
because my terminal is often in front of a web browser and many web
pages have light backgrounds is often a medium grey, so a dark red is
illegible here because of poor contrast.  That is true regardless of the
fact that I don't have colorblindness; people with colorblindness just
have more colors (depending on the type) where contrast is poor.

> I.e. issue isn't colors per-se, or even a UI that would make an
> egregious of coloring, rather it's if that UI uses color as a
> *replacement* for showing the same information in another way.

Terminals with colored foregrounds color text, which is the relevant
part, because that's the part people need to read.  I'm less concerned
about us losing the bold or italic nature of text, since that can
usually be ignored without much loss of information.  For example, if a
person viewed all roman, bold, and italic text as uniform but legible,
I'm not worried.

It is fine for accessibility reasons if we color both the foreground and
the background and we ensure they have reasonable distinctiveness.
However, that also results in us breaking the transparent nature of
terminals people have configured that way.

> > For similar reasons, colorizing help output in general is unhelpful
> > because users cannot find the options to disable it.
> 
> This seems to just be a re-hash of the old argument that git does
> coloring by default, not specifically about "git help <xyz>".
> 
> 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.

No, I don't think that's the same thing.  I like that Git does coloring
by default.  I use coloring extensively in Git, and especially the zebra
coloring of diffs.  I also use coloring in my prompt and my editor, and
I like all of that.  I think all of this adds a lot of value, and I like
that Git allows a great deal of customization over this.

What I don't like is when a program colors text in a certain way, I
can't read it, and then I can't read the help output or documentation to
turn it off.  I am specifically arguing against coloring our
documentation and help output because it leaves users with little
recourse to fix the problem.

> > In general, this is made worse because Git doesn't honor the unofficial
> > but widely supported NO_COLOR[0], so reading the documentation is
> > obligatory.
> 
> I replied about NO_COLOR in
> <87lf8bqdv0.fsf@evledraar.gmail.com>.
> 
> Regardless of whether or not that's a good idea I don't see how it's
> relevant here. We'd support TERM=dumb, which is *the* standard way to
> tweak this for all programs.

TERM=dumb breaks all addressable cursor support, all use of bold and
standout functionality, and functionality like readline and editline.
Setting TERM=dumb and then invoking man will result in an inability to
page backwards, so that's not a suitable alternative; similarly, it
breaks any sort of interactive prompt (e.g., the shell).

> > The problem is, I don't always.  I am on call for a set of hundreds of
> > servers, only one of which has my shell configuration set up, so
> > defaults here matter.  Moreover, because there are many novice users of
> > Git, we should consider that for a decent number of users, they
> > literally won't know where to look in our documentation to make
> > changes, and therefore the defaults matter for them, too.
> 
> These servers don't have TERM in their list of AcceptEnv variables, or
> equivalent?

They do support TERM.  I can't set TERM=dumb because then basic prompt
editing doesn't work.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]