git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: git@vger.kernel.org, "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Junio C Hamano" <gitster@pobox.com>,
	"Randall S. Becker" <rsbecker@nexbridge.com>
Subject: Re: [PATCH] help: colorize man pages
Date: Tue, 18 May 2021 23:49:40 +0000	[thread overview]
Message-ID: <YKRSlFcFAcHcR3uY@camp.crustytoothpaste.net> (raw)
In-Reply-To: <60a332fd22dad_14c8d4208ed@natae.notmuch>

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

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?

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

For similar reasons, colorizing help output in general is unhelpful
because users cannot find the options to disable it.

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.

> > Even users who want to use them might find some colors to be too
> > similar, and this patch doesn't permit them to be configured.
> 
> Yes it does:
> 
>   LESS_TERMCAP_md=$'\e[01;38;5;33m' git help git

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.

> > In my particular case, despite having normal color vision, because I use
> > a transparent terminal which often results in a grey background, I find
> > the standard terminal red to be difficult to read, and so this patch
> > would result in a significant decrease in the readability of the manual
> > pages for me.
> 
> If you have LESS_TERMCAP_md set in your environment, it won't.

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.

[0] https://no-color.org/
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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

  reply	other threads:[~2021-05-18 23:49 UTC|newest]

Thread overview: 33+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-18  1:01 Felipe Contreras
2021-05-18  1:19 ` brian m. carlson
2021-05-18  3:22   ` Felipe Contreras
2021-05-18 23:49     ` brian m. carlson [this message]
2021-05-19  1:08       ` Junio C Hamano
2021-05-19  2:07         ` brian m. carlson
2021-05-19  6:09           ` Junio C Hamano
2021-05-19  8:41             ` Ævar Arnfjörð Bjarmason
2021-05-19 10:36               ` Felipe Contreras
2021-05-21  0:58               ` brian m. carlson
2021-05-21 18:09                 ` Felipe Contreras
2021-05-21 19:48                   ` Igor Djordjevic
2021-05-21 21:20                     ` Felipe Contreras
2021-05-21 22:10                       ` Igor Djordjevic
2021-05-21 23:04                         ` Felipe Contreras
2021-05-22 18:38                           ` Igor Djordjevic
2021-05-22 21:48                             ` Felipe Contreras
2021-05-23 11:25                               ` Igor Djordjevic
2021-05-23 14:48                                 ` Felipe Contreras
2021-05-21 22:47                     ` Igor Djordjevic
2021-05-21 23:32                     ` Junio C Hamano
2021-05-19  9:26       ` Ævar Arnfjörð Bjarmason
2021-05-19 10:10         ` Jeff King
2021-05-19 11:45           ` Felipe Contreras
2021-05-19 11:19         ` Felipe Contreras
2021-05-19 12:21           ` Felipe Contreras
2021-05-20  1:55         ` brian m. carlson
2021-05-20  2:23           ` Junio C Hamano
2021-05-20  3:05             ` Felipe Contreras
2021-05-20  3:28               ` Junio C Hamano
2021-05-20  3:48                 ` Felipe Contreras
2021-05-20  2:45           ` Felipe Contreras
2021-05-19 10:25       ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YKRSlFcFAcHcR3uY@camp.crustytoothpaste.net \
    --to=sandals@crustytoothpaste.net \
    --cc=avarab@gmail.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=rsbecker@nexbridge.com \
    --subject='Re: [PATCH] help: colorize man pages' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).