From: "brian m. carlson" <firstname.lastname@example.org> To: "Ævar Arnfjörð Bjarmason" <email@example.com> Cc: Felipe Contreras <firstname.lastname@example.org>, email@example.com, Junio C Hamano <firstname.lastname@example.org>, "Randall S. Becker" <email@example.com> Subject: Re: [PATCH] help: colorize man pages Date: Thu, 20 May 2021 01:55:01 +0000 [thread overview] Message-ID: <YKXBdQ36MYz2YG8s@camp.crustytoothpaste.net> (raw) In-Reply-To: <firstname.lastname@example.org> [-- 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, so reading the documentation is > > obligatory. > > I replied about NO_COLOR in > <email@example.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 --]
next prev parent reply other threads:[~2021-05-20 1:56 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 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 [this message] 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=YKXBdQ36MYz2YG8s@camp.crustytoothpaste.net \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.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).