git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] help: colorize man pages
@ 2021-05-18  1:01 Felipe Contreras
  2021-05-18  1:19 ` brian m. carlson
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-18  1:01 UTC (permalink / raw)
  To: git
  Cc: Ævar Arnfjörð Bjarmason, Junio C Hamano,
	Randall S. Becker, Felipe Contreras

Our man pages don't contain many useful colors (just blue links),
moreover, many people have groff SGR disabled, so they don't see any
colors with man pages.

We can set LESS_TERMCAP variables to render bold and underlined text
with colors in the pager; a common trick[1].

Bold is rendered as red, underlined as blue, and standout (messages and
highlighted search) as inverse magenta.

This only works when the pager is less, and the color.pager
configuration is enabled, as well as color.ui.

[1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 builtin/help.c | 27 ++++++++++++++++++++++++++-
 color.h        |  1 +
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/builtin/help.c b/builtin/help.c
index bb339f0fc8..0119e833a8 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -11,6 +11,7 @@
 #include "config-list.h"
 #include "help.h"
 #include "alias.h"
+#include "color.h"
 
 #ifndef DEFAULT_HELP_FORMAT
 #define DEFAULT_HELP_FORMAT "man"
@@ -253,10 +254,33 @@ static void exec_man_konqueror(const char *path, const char *page)
 	}
 }
 
+static void colorize_man(void)
+{
+	if (!pager_use_color || !want_color(GIT_COLOR_UNKNOWN))
+		return;
+
+	/* Disable groff colors */
+	setenv("GROFF_NO_SGR", "1", 0);
+
+	/* Bold */
+	setenv("LESS_TERMCAP_md", GIT_COLOR_BOLD_RED, 0);
+	setenv("LESS_TERMCAP_me", GIT_COLOR_RESET, 0);
+
+	/* Underline */
+	setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0);
+	setenv("LESS_TERMCAP_ue", GIT_COLOR_RESET, 0);
+
+	/* Standout */
+	setenv("LESS_TERMCAP_so", GIT_COLOR_MAGENTA GIT_COLOR_REVERSE, 0);
+	setenv("LESS_TERMCAP_se", GIT_COLOR_RESET, 0);
+}
+
 static void exec_man_man(const char *path, const char *page)
 {
 	if (!path)
 		path = "man";
+
+	colorize_man();
 	execlp(path, "man", page, (char *)NULL);
 	warning_errno(_("failed to exec '%s'"), path);
 }
@@ -264,6 +288,7 @@ static void exec_man_man(const char *path, const char *page)
 static void exec_man_cmd(const char *cmd, const char *page)
 {
 	struct strbuf shell_cmd = STRBUF_INIT;
+	colorize_man();
 	strbuf_addf(&shell_cmd, "%s %s", cmd, page);
 	execl(SHELL_PATH, SHELL_PATH, "-c", shell_cmd.buf, (char *)NULL);
 	warning(_("failed to exec '%s'"), cmd);
@@ -372,7 +397,7 @@ static int git_help_config(const char *var, const char *value, void *cb)
 	if (starts_with(var, "man."))
 		return add_man_viewer_info(var, value);
 
-	return git_default_config(var, value, cb);
+	return git_color_default_config(var, value, cb);
 }
 
 static struct cmdnames main_cmds, other_cmds;
diff --git a/color.h b/color.h
index 98894d6a17..d012add4e8 100644
--- a/color.h
+++ b/color.h
@@ -51,6 +51,7 @@ struct strbuf;
 #define GIT_COLOR_FAINT		"\033[2m"
 #define GIT_COLOR_FAINT_ITALIC	"\033[2;3m"
 #define GIT_COLOR_REVERSE	"\033[7m"
+#define GIT_COLOR_UNDERLINE	"\033[4m"
 
 /* A special value meaning "no color selected" */
 #define GIT_COLOR_NIL "NIL"
-- 
2.31.1


^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-18  1:01 [PATCH] help: colorize man pages Felipe Contreras
@ 2021-05-18  1:19 ` brian m. carlson
  2021-05-18  3:22   ` Felipe Contreras
  0 siblings, 1 reply; 33+ messages in thread
From: brian m. carlson @ 2021-05-18  1:19 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: git, Ævar Arnfjörð Bjarmason, Junio C Hamano,
	Randall S. Becker

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

On 2021-05-18 at 01:01:21, Felipe Contreras wrote:
> Our man pages don't contain many useful colors (just blue links),
> moreover, many people have groff SGR disabled, so they don't see any
> colors with man pages.
> 
> We can set LESS_TERMCAP variables to render bold and underlined text
> with colors in the pager; a common trick[1].
> 
> Bold is rendered as red, underlined as blue, and standout (messages and
> highlighted search) as inverse magenta.
> 
> This only works when the pager is less, and the color.pager
> configuration is enabled, as well as color.ui.

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.

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

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.

So overall I think I'd prefer if we didn't color manual pages for the
user.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-18  1:19 ` brian m. carlson
@ 2021-05-18  3:22   ` Felipe Contreras
  2021-05-18 23:49     ` brian m. carlson
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-18  3:22 UTC (permalink / raw)
  To: brian m. carlson, Felipe Contreras
  Cc: git, Ævar Arnfjörð Bjarmason, Junio C Hamano,
	Randall S. Becker

brian m. carlson wrote:
> On 2021-05-18 at 01:01:21, Felipe Contreras wrote:
> > Our man pages don't contain many useful colors (just blue links),
> > moreover, many people have groff SGR disabled, so they don't see any
> > colors with man pages.
> > 
> > We can set LESS_TERMCAP variables to render bold and underlined text
> > with colors in the pager; a common trick[1].
> > 
> > Bold is rendered as red, underlined as blue, and standout (messages and
> > highlighted search) as inverse magenta.
> > 
> > This only works when the pager is less, and the color.pager
> > configuration is enabled, as well as color.ui.
> 
> 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

> 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

> 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

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

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-18  3:22   ` Felipe Contreras
@ 2021-05-18 23:49     ` brian m. carlson
  2021-05-19  1:08       ` Junio C Hamano
                         ` (2 more replies)
  0 siblings, 3 replies; 33+ messages in thread
From: brian m. carlson @ 2021-05-18 23:49 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: git, Ævar Arnfjörð Bjarmason, Junio C Hamano,
	Randall S. Becker

[-- 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 --]

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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  9:26       ` Ævar Arnfjörð Bjarmason
  2021-05-19 10:25       ` Felipe Contreras
  2 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2021-05-19  1:08 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Felipe Contreras, git, Ævar Arnfjörð Bjarmason,
	Randall S. Becker

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> 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 vaguely recall that we were contacted by NO_COLOR folks to be
an early supporter of their cause to break the chicken-and-egg
problem they were hagving, and (unhelpfully) answered with "sure,
when we see enough people support it---otherwise we'd end up having
to keep essentially a dead code that supports a convention that is
not all that useful".

> [0] https://no-color.org/

I wonderr if it is just a matter of hooking into want_color(), like this?

 color.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git c/color.c w/color.c
index 64f52a4f93..2516ef7275 100644
--- c/color.c
+++ w/color.c
@@ -373,12 +373,17 @@ int want_color_fd(int fd, int var)
 	 * we always write the same value, but it's still wrong. This function
 	 * is listed in .tsan-suppressions for the time being.
 	 */
-
+	static int no_color = -1;
 	static int want_auto[3] = { -1, -1, -1 };
 
 	if (fd < 1 || fd >= ARRAY_SIZE(want_auto))
 		BUG("file descriptor out of range: %d", fd);
 
+	if (no_color < 0)
+		no_color = !!getenv("NO_COLOR");
+	if (no_color)
+		return 0;
+
 	if (var < 0)
 		var = git_use_color_default;
 

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19  1:08       ` Junio C Hamano
@ 2021-05-19  2:07         ` brian m. carlson
  2021-05-19  6:09           ` Junio C Hamano
  0 siblings, 1 reply; 33+ messages in thread
From: brian m. carlson @ 2021-05-19  2:07 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Felipe Contreras, git, Ævar Arnfjörð Bjarmason,
	Randall S. Becker

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

On 2021-05-19 at 01:08:54, Junio C Hamano wrote:
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> 
> > 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 vaguely recall that we were contacted by NO_COLOR folks to be
> an early supporter of their cause to break the chicken-and-egg
> problem they were hagving, and (unhelpfully) answered with "sure,
> when we see enough people support it---otherwise we'd end up having
> to keep essentially a dead code that supports a convention that is
> not all that useful".

Yeah, I seem to recall you were somewhat negative on it at the time, but
I do personally find it useful, and someone on Twitter reminded me of
it just today.

> I wonderr if it is just a matter of hooking into want_color(), like this?
> 
>  color.c | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git c/color.c w/color.c
> index 64f52a4f93..2516ef7275 100644
> --- c/color.c
> +++ w/color.c
> @@ -373,12 +373,17 @@ int want_color_fd(int fd, int var)
>  	 * we always write the same value, but it's still wrong. This function
>  	 * is listed in .tsan-suppressions for the time being.
>  	 */
> -
> +	static int no_color = -1;
>  	static int want_auto[3] = { -1, -1, -1 };
>  
>  	if (fd < 1 || fd >= ARRAY_SIZE(want_auto))
>  		BUG("file descriptor out of range: %d", fd);
>  
> +	if (no_color < 0)
> +		no_color = !!getenv("NO_COLOR");
> +	if (no_color)
> +		return 0;
> +
>  	if (var < 0)
>  		var = git_use_color_default;
>  

Yeah, that will probably do it.  I hadn't looked at it, but I assumed it
would be pretty easy, and it looks like it is.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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
  0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2021-05-19  6:09 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Felipe Contreras, git, Ævar Arnfjörð Bjarmason,
	Randall S. Becker

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2021-05-19 at 01:08:54, Junio C Hamano wrote:
>> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>> 
>> > 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 vaguely recall that we were contacted by NO_COLOR folks to be
>> an early supporter of their cause to break the chicken-and-egg
>> problem they were hagving, and (unhelpfully) answered with "sure,
>> when we see enough people support it---otherwise we'd end up having
>> to keep essentially a dead code that supports a convention that is
>> not all that useful".
>
> Yeah, I seem to recall you were somewhat negative on it at the time, but
> I do personally find it useful, and someone on Twitter reminded me of
> it just today.
>
>> I wonderr if it is just a matter of hooking into want_color(), like this?
>> 
>>  color.c | 7 ++++++-
>>  1 file changed, 6 insertions(+), 1 deletion(-)
>> 
>> diff --git c/color.c w/color.c
>> index 64f52a4f93..2516ef7275 100644
>> --- c/color.c
>> +++ w/color.c
>> @@ -373,12 +373,17 @@ int want_color_fd(int fd, int var)
>>  	 * we always write the same value, but it's still wrong. This function
>>  	 * is listed in .tsan-suppressions for the time being.
>>  	 */
>> -
>> +	static int no_color = -1;
>>  	static int want_auto[3] = { -1, -1, -1 };
>>  
>>  	if (fd < 1 || fd >= ARRAY_SIZE(want_auto))
>>  		BUG("file descriptor out of range: %d", fd);
>>  
>> +	if (no_color < 0)
>> +		no_color = !!getenv("NO_COLOR");
>> +	if (no_color)
>> +		return 0;
>> +
>>  	if (var < 0)
>>  		var = git_use_color_default;
>>  
>
> Yeah, that will probably do it.  I hadn't looked at it, but I assumed it
> would be pretty easy, and it looks like it is.

Actually I doubt it satisfies the FAQ #2 of no-color.org; we
probably would need to go one level lower, like the original
proposal from 2018 did:

cf. https://lore.kernel.org/git/87efl3emlm.fsf@vuxu.org/


^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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
  0 siblings, 2 replies; 33+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-05-19  8:41 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: brian m. carlson, Felipe Contreras, git, Randall S. Becker,
	Leah Neukirchen


On Wed, May 19 2021, Junio C Hamano wrote:

> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
>> On 2021-05-19 at 01:08:54, Junio C Hamano wrote:
>>> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>>> 
>>> > 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 vaguely recall that we were contacted by NO_COLOR folks to be
>>> an early supporter of their cause to break the chicken-and-egg
>>> problem they were hagving, and (unhelpfully) answered with "sure,
>>> when we see enough people support it---otherwise we'd end up having
>>> to keep essentially a dead code that supports a convention that is
>>> not all that useful".
>>
>> Yeah, I seem to recall you were somewhat negative on it at the time, but
>> I do personally find it useful, and someone on Twitter reminded me of
>> it just today.
>>
>>> I wonderr if it is just a matter of hooking into want_color(), like this?
>>> 
>>>  color.c | 7 ++++++-
>>>  1 file changed, 6 insertions(+), 1 deletion(-)
>>> 
>>> diff --git c/color.c w/color.c
>>> index 64f52a4f93..2516ef7275 100644
>>> --- c/color.c
>>> +++ w/color.c
>>> @@ -373,12 +373,17 @@ int want_color_fd(int fd, int var)
>>>  	 * we always write the same value, but it's still wrong. This function
>>>  	 * is listed in .tsan-suppressions for the time being.
>>>  	 */
>>> -
>>> +	static int no_color = -1;
>>>  	static int want_auto[3] = { -1, -1, -1 };
>>>  
>>>  	if (fd < 1 || fd >= ARRAY_SIZE(want_auto))
>>>  		BUG("file descriptor out of range: %d", fd);
>>>  
>>> +	if (no_color < 0)
>>> +		no_color = !!getenv("NO_COLOR");
>>> +	if (no_color)
>>> +		return 0;
>>> +
>>>  	if (var < 0)
>>>  		var = git_use_color_default;
>>>  
>>
>> Yeah, that will probably do it.  I hadn't looked at it, but I assumed it
>> would be pretty easy, and it looks like it is.
>
> Actually I doubt it satisfies the FAQ #2 of no-color.org; we
> probably would need to go one level lower, like the original
> proposal from 2018 did:
>
> cf. https://lore.kernel.org/git/87efl3emlm.fsf@vuxu.org/

[CC'd the author of that proposal]

It also doesn't seem to me to satisfy their FAQ point #1, i.e. users who
actually want no color at all can just set TERM=dumb, and we support
that. The proposed patch is the same as having TERM=dumb set.

This NO_COLOR=1 actually means something like "I do support colors, so
show them if it's important, but don't color things willy-nilly".

I'm not sure if it matters for git, the FAQ point isn't really clear on
what the distinction is exactly. Users who want to use color for say CLI
emacs/vim/screen/tmux "status" bars, but don't want any "normal" CLI
program to emit them?

But if we gained such a "status" bar feature the proposed 2018 patch
would be actively going against what NO_COLOR users want, since it's our
equivalent of TERM=dumb, not whatever NO_COLOR=1 is supposed to mean. Or
maybe we already have that, I would think that "git add -i"'s UI would
count.

It seems like it really should have been named MOSTLY_NOT_COLOR=1 or
ONLY_COLOR_NCURSES_LIKE_UIS=1 if I'm understanding that FAQ item
correctly.

So it would be incorrect to map it to either color.ui=never or
color.ui=always (as "auto" will implicitly do). We'd need a new knob to
control the granularity of coloring, something like
color.ui=conservative.

I wasn't against NO_COLOR before, but after writing the above I think I
am. I initially assumed that it was some redundant and more "friendly"
way of setting TERM=dumb, but rather it's some entirely subjective way
for every program to decide if their UI elements are "text-editor"-like
or "status bar"-like enough to warrant coloring.

That's "against" in the sense that if git supported it I wouldn't care
much, and wouldn't oppose a patch to implement it.

But it seems to me to just introduce even more confusion to the *nix
coloring landscape. For what it's apparently trying to accomplish I
think it would be a much better thing to:

 1. Have terminals/startup rc'd etc. set a TERM_ACTUAL=<old value>
    before setting TERM=dumb. This is something POSIX et al could
    eventually standardize, i.e. "TERM=dumb" for now, but actually I
    support "TERM=xyz".

 2. Have some "color_this" shell function/alias/wrapper to start things
    like your editor, which would just be a one-line wrapper to start
    that program with TERM=$TERM_ACTUAL, or those programs would learn
    to look at TERM_ACTUAL.

The user would thus get color almost nowhere in "normal" programs like
"git status" or "ls", but would get them in emacs, vim, screet, tmux,
htop or whatever other "big" terminal UI they run.

I.e. the whole point seems to be to support the use-case of wanting
color almost nowhere except a very small whitelist of programs, but
trying to accomplish it with NO_COLOR means that hundreds/thousands of
programs need to support it, as opposed to the much smaller list of
editors/terminal multiplexers etc.

Each of those programs then need to subjectively decide if their UI
elements are "such as [...] a status bar". If they get it wrong the user
is back to inovking them with TERM=dumb anyway.

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-18 23:49     ` brian m. carlson
  2021-05-19  1:08       ` Junio C Hamano
@ 2021-05-19  9:26       ` Ævar Arnfjörð Bjarmason
  2021-05-19 10:10         ` Jeff King
                           ` (2 more replies)
  2021-05-19 10:25       ` Felipe Contreras
  2 siblings, 3 replies; 33+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-05-19  9:26 UTC (permalink / raw)
  To: brian m. carlson; +Cc: Felipe Contreras, git, Junio C Hamano, Randall S. Becker


On Tue, May 18 2021, brian m. carlson wrote:

> [[PGP Signed Part:Undecided]]
> 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?

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

Right now our documentation seems to suggest that we won't do any such
magic, but you can also set man.viewer to e.g. invoke a web browser or
something instead of man(1).

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

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

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.

I may be entirely wrong, but I think it's a point worth bringing up to
find some solution here, i.e. if we find that not losing the underline
(but adding color) is a solution acceptable to everyone.

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

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

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

I'm in vehement agreement about this. If we do invoke "man" differently
based on how we'd do coloring for any other git program we invoke, we
should of course be respecting the same configuration
mechanisms. I.e. it should respect color.ui=auto etc., you shouldn't
need to set LESS_TERMCAP_md or whatever.

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

These servers don't have TERM in their list of AcceptEnv variables, or
equivalent?

In any case, I think for these defaults we need to be considering the
vast majority of users, who are mostly interfacing with one or two
computers in their use of "git", and who are running some modern OS that
supports terminal coloring, which is why color.ui=auto became the
default (to some objections at the time, but I think those have gotten
less prominent as time marched on).

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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-20  1:55         ` brian m. carlson
  2 siblings, 1 reply; 33+ messages in thread
From: Jeff King @ 2021-05-19 10:10 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: brian m. carlson, Felipe Contreras, git, Junio C Hamano,
	Randall S. Becker

On Wed, May 19, 2021 at 11:26:12AM +0200, Ævar Arnfjörð Bjarmason wrote:

> > 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?
> 
> 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>".
> 
> Right now our documentation seems to suggest that we won't do any such
> magic, but you can also set man.viewer to e.g. invoke a web browser or
> something instead of man(1).
> 
> 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 agree that we could explain it as "man with fancy on top". But it
makes me wonder: why is this Git's responsibility to do the fancy at
all?

I.e., if you want colorized manpages, why don't you configure man to do
so? Sure, it's a bit of a pain to do so since it involves setting a
bunch of obscure environment variables. But if that's what you want,
wouldn't you want it for all manpages, whether you ran "git help log" or
"man git-log" or "man ls"?

This seems like a "man" feature and not a "git" feature. And arguably
some of it is really a "less" feature (it is trying to set "standout"
mode for its prompt, so configuring "so" and "se" termcap entries is
just reinterpreting that. If you like, wouldn't you want it on for all
"less" invocations?).

-Peff

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-18 23:49     ` brian m. carlson
  2021-05-19  1:08       ` Junio C Hamano
  2021-05-19  9:26       ` Ævar Arnfjörð Bjarmason
@ 2021-05-19 10:25       ` Felipe Contreras
  2 siblings, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-19 10:25 UTC (permalink / raw)
  To: brian m. carlson, Felipe Contreras
  Cc: git, Ævar Arnfjörð Bjarmason, Junio C Hamano,
	Randall S. Becker

brian m. carlson wrote:
> 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.

Two people feeling in a certain way is not an argument against a feature
that could potentially benefit millions of people.

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

Would you be happier if I implement an entirely new library to render
asciidoc documentation in a pretty way and make `git help` link to that?

That way we wouldn't be using "a separate program".

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

That is one opinion. Again, not shared by everyone.

> Would you consider various projects coloring their respective manual
> pages differently to be a desirable state of affairs?

That is irrelevant, because we are not talking about `man git`, we are
talking about `git help git`, which can render help in a variety of
ways.

You can do for example `git -c man.viewer=woman help git`, and the
result would be *completely* different from what the user sees in `man
git`.

A different thing is different.

Would you be happier if we enable this with `man.viewer=mancolor`?

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

man git

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

If you don't like the colors they can disable them.

They lose absolutely nothing from the state of git 2.31.

> It's my argument that the user doesn't want Git manual pages to be
> colored differently than other manual pages on the system,

/usr/share/man/man1/git.1.gz is not changed.

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

Surely you can live typing `man $x` instead of `git help $x` for a bit.

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

And we are considering them.

But the defaults are for the majority.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19  8:41             ` Ævar Arnfjörð Bjarmason
@ 2021-05-19 10:36               ` Felipe Contreras
  2021-05-21  0:58               ` brian m. carlson
  1 sibling, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-19 10:36 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Junio C Hamano
  Cc: brian m. carlson, Felipe Contreras, git, Randall S. Becker,
	Leah Neukirchen

Ævar Arnfjörð Bjarmason wrote:
> This NO_COLOR=1 actually means something like "I do support colors, so
> show them if it's important, but don't color things willy-nilly".

In my subjective opinion most of git uses color sensibly, so we kind of
already support NO_COLOR (turn it on, and you'd get sensible colors).

Except, my patch to colorize man pages can be considered to be coloring
things willy-nilly.

So perhaps that's the only instance where we should consider caring
about that.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19  9:26       ` Ævar Arnfjörð Bjarmason
  2021-05-19 10:10         ` Jeff King
@ 2021-05-19 11:19         ` Felipe Contreras
  2021-05-19 12:21           ` Felipe Contreras
  2021-05-20  1:55         ` brian m. carlson
  2 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-19 11:19 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, brian m. carlson
  Cc: Felipe Contreras, git, Junio C Hamano, Randall S. Becker

Ævar Arnfjörð Bjarmason wrote:
> 
> On Tue, May 18 2021, brian m. carlson wrote:
> 
> > [[PGP Signed Part:Undecided]]
> > 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?
> 
> I think it's an important distinction that we're not coloring any manual
> pages,

But we *are* coloring man pages. The docbook stylesheets format links as
blue.

Try this:

  GROFF_SGR=1 man git

> Right now our documentation seems to suggest that we won't do any such
> magic, but you can also set man.viewer to e.g. invoke a web browser or
> something instead of man(1).
> 
> I don't think it's confusing in that context if we learn to do some "man
> with fancy on top" in this mode.

But man already does fancy stuff.

You can open a browser:

  man -Hchromium git

You display some shitty X viewer:

  man -X git

You can send the man page to a printer, or generate a DVI file.

The pager mode in man is also just one of many modes.

I think most people have not read man man.

> 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 in my patch you don't lose the underline.

The function version I sent was an updated version of something I've
been using for a long time. But I did more effort in the version for
wide consumption, and the underline is preserved.

This is the equivalent of my latest patch:

  man () {
    GROFF_NO_SGR=1 \
    LESS_TERMCAP_md=$'\e[1;31m' \
    LESS_TERMCAP_me=$'\e[m' \
    LESS_TERMCAP_us=$'\e[1;34m\e[4m' \
    LESS_TERMCAP_ue=$'\e[m' \
    LESS_TERMCAP_so=$'\e[1;35m\e[7m' \
    LESS_TERMCAP_se=$'\e[m' \
    command man "$@"
  }

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

I would say a lot of programs have been doing that, and I like it. The
last one I discovered is jq.

> > 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.
> 
> I'm in vehement agreement about this. If we do invoke "man" differently
> based on how we'd do coloring for any other git program we invoke, we
> should of course be respecting the same configuration
> mechanisms. I.e. it should respect color.ui=auto etc., you shouldn't
> need to set LESS_TERMCAP_md or whatever.

Yes, but good software is developed in stages.

You shouldn't expect a first patch to provide all the functionality in
the world. Not only does it take longer, increase the review burden, and
generate longer disucssions, but it increases the probability of the
feature never been merged.

Plus increases the probability of bugs bein introduced.

More features can be added later.

What is important is that users don't lose anything from what they have
now.

And unconfigurable colors is better than what they have now... Nothing.

> In any case, I think for these defaults we need to be considering the
> vast majority of users, who are mostly interfacing with one or two
> computers in their use of "git", and who are running some modern OS that
> supports terminal coloring, which is why color.ui=auto became the
> default (to some objections at the time, but I think those have gotten
> less prominent as time marched on).

Exactly.

Moreover, if colors are really that bad, then users will complain (I bet
they won't), and then we can switch this off by default.

Easy.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19 10:10         ` Jeff King
@ 2021-05-19 11:45           ` Felipe Contreras
  0 siblings, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-19 11:45 UTC (permalink / raw)
  To: Jeff King, Ævar Arnfjörð Bjarmason
  Cc: brian m. carlson, Felipe Contreras, git, Junio C Hamano,
	Randall S. Becker

Jeff King wrote:
> On Wed, May 19, 2021 at 11:26:12AM +0200, Ævar Arnfjörð Bjarmason wrote:
> 
> > > 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?
> > 
> > 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>".
> > 
> > Right now our documentation seems to suggest that we won't do any such
> > magic, but you can also set man.viewer to e.g. invoke a web browser or
> > something instead of man(1).
> > 
> > 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 agree that we could explain it as "man with fancy on top". But it
> makes me wonder: why is this Git's responsibility to do the fancy at
> all?

It is not.

Just like it is not git's responsibility to display diffs in color.

But it's a nice thing to do.

> I.e., if you want colorized manpages, why don't you configure man to do
> so?

Because this has nothing to do with man.

In the default mode man just takes the output of groff, and passes it to
a pager. That's it.

It doesn't know anything of colors. That's between groff and less.

> Sure, it's a bit of a pain to do so since it involves setting a
> bunch of obscure environment variables.

The environment variables are for less, not man.

If you export those variables into your environment, you could
potentially mess up the output of some programs when viewed through
less.

That's why in my tip I set the variables only for man, inside a man
function wrap: man () { FOO=1 command man "$@"; }

> But if that's what you want, wouldn't you want it for all manpages,
> whether you ran "git help log" or "man git-log" or "man ls"?

How? (without messing up the environment for other programs that use a
pager)

> This seems like a "man" feature and not a "git" feature.

man does not care. It can do many things, dumping data onto a pager is
just one of them.

Where does LESS_TERMCAP_* affect `man -Hchromium git`? For more read man man.

> And arguably some of it is really a "less" feature

It's *all* a less feature.

> (it is trying to set "standout" mode for its prompt, so configuring
> "so" and "se" termcap entries is just reinterpreting that. If you
> like, wouldn't you want it on for all "less" invocations?).

I don't.

Rendering things correctly on a terminal is tricky enough as it is, I
would like to hedge such kinds of changes inside a controlled
environment.

Which is exactly what my patch does.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19 11:19         ` Felipe Contreras
@ 2021-05-19 12:21           ` Felipe Contreras
  0 siblings, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-19 12:21 UTC (permalink / raw)
  To: Felipe Contreras, Ævar Arnfjörð Bjarmason,
	brian m. carlson
  Cc: Felipe Contreras, git, Junio C Hamano, Randall S. Becker

Felipe Contreras wrote:
> This is the equivalent of my latest patch:
> 
>   man () {
>     GROFF_NO_SGR=1 \
>     LESS_TERMCAP_md=$'\e[1;31m' \
>     LESS_TERMCAP_me=$'\e[m' \
>     LESS_TERMCAP_us=$'\e[1;34m\e[4m' \
>     LESS_TERMCAP_ue=$'\e[m' \
>     LESS_TERMCAP_so=$'\e[1;35m\e[7m' \
>     LESS_TERMCAP_se=$'\e[m' \
>     command man "$@"
>   }

Wait a second...

  MANPAGER="less -Dd+r -Du+b -Ds+m" GROFF_NO_SGR=1 command man "$@"

Reading man pages pays off ;)

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-19  9:26       ` Ævar Arnfjörð Bjarmason
  2021-05-19 10:10         ` Jeff King
  2021-05-19 11:19         ` Felipe Contreras
@ 2021-05-20  1:55         ` brian m. carlson
  2021-05-20  2:23           ` Junio C Hamano
  2021-05-20  2:45           ` Felipe Contreras
  2 siblings, 2 replies; 33+ messages in thread
From: brian m. carlson @ 2021-05-20  1:55 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Felipe Contreras, git, Junio C Hamano, Randall S. Becker

[-- 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 --]

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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  2:45           ` Felipe Contreras
  1 sibling, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2021-05-20  2:23 UTC (permalink / raw)
  To: brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason, Felipe Contreras, git,
	Randall S. Becker

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

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

I guess what the documentation says matches what end users expect (I
as an end user certainly do expect that "git help -m foo" is running
the familiar "man" command on something that is related to "foo").

So while making the "less" customization more discoverable and
easily accessible would be a win for users, I have to agree that is
out of scope of this project's mission.

We used to give helpful hints how to configure LESS environment
variable in a way that does not conflict with our use somewhere in
the doc.  I think the hints how to configure these set of environment
variables for "less" users may belong to a similar place in the doc,
if we wanted to do something, but going beyond that would probably
be more confusing and disorienting than helpful to our users (they'll
start wondering why "git help"'s output does not look like the
output from "man ls").

Thanks for discussing this topic.



^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-20  1:55         ` brian m. carlson
  2021-05-20  2:23           ` Junio C Hamano
@ 2021-05-20  2:45           ` Felipe Contreras
  1 sibling, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-20  2:45 UTC (permalink / raw)
  To: brian m. carlson, Ævar Arnfjörð Bjarmason
  Cc: Felipe Contreras, git, Junio C Hamano, Randall S. Becker

brian m. carlson wrote:
> 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.

Do you also expect git to call diff without options?

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

The documentation can be updated.

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

> It's pretty obvious that "git help commit" and "cargo help build" both
> are intended to invoke man when used in the normal way.

And I don't.

I expect the output `foo help $x` to be decided by foo.

If I do `python help len` and I get an error, that's fine.

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

It is not indistiguishable; a blind person would be able to distinguish
them. As much as they can without the patch.

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

There is another distinguising factor: they are *bold*, or _underlined_.

> So, yes, if the colors only add information and they can otherwise be
> distinguished, then it's fine.

We are setting *bold*, _underlined_, and REVERSE.

Exactly in the same way as they are set already.


A truly colorblind person would see no difference at all.

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

If you can't read `man git`, that has absolutely nothing to do with this
patch.

> I am specifically arguing against coloring our documentation

We already already coloring our documentation.

> and help output because it leaves users with little recourse to fix
> the problem.

man git.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-20  2:23           ` Junio C Hamano
@ 2021-05-20  3:05             ` Felipe Contreras
  2021-05-20  3:28               ` Junio C Hamano
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-20  3:05 UTC (permalink / raw)
  To: Junio C Hamano, brian m. carlson
  Cc: Ævar Arnfjörð Bjarmason, Felipe Contreras, git,
	Randall S. Becker

Junio C Hamano wrote:
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> 
> > The documentation says, "use the man program as usual".  "As usual"
> > implies the way the user would invoke it.
> 
> I guess what the documentation says matches what end users expect (I
> as an end user certainly do expect that "git help -m foo" is running
> the familiar "man" command on something that is related to "foo").

Do you also expect that `git diff a b` runs something similar to
`diff a b`?

> So while making the "less" customization more discoverable and
> easily accessible would be a win for users, I have to agree that is
> out of scope of this project's mission.

How is enabling a configuration already present in `man` out of scope,
but running an *ENTIRELY* different program--such as konqueror or
woman--to view man pages is not?

  git help --man git

Doesn't even necessarily run man *already*.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-20  3:05             ` Felipe Contreras
@ 2021-05-20  3:28               ` Junio C Hamano
  2021-05-20  3:48                 ` Felipe Contreras
  0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2021-05-20  3:28 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: brian m. carlson, Ævar Arnfjörð Bjarmason, git,
	Randall S. Becker

Felipe Contreras <felipe.contreras@gmail.com> writes:

> How is enabling a configuration already present in `man` out of scope,
> but running an *ENTIRELY* different program--such as konqueror or
> woman--to view man pages is not?
>
>   git help --man git
>
> Doesn't even necessarily run man *already*.

As an end-user, I do not expect Git to run konqueror or woman with
its own tweaks when it does so.  And I do not see a reason why "man"
should be any different.


^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-20  3:28               ` Junio C Hamano
@ 2021-05-20  3:48                 ` Felipe Contreras
  0 siblings, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-20  3:48 UTC (permalink / raw)
  To: Junio C Hamano, Felipe Contreras
  Cc: brian m. carlson, Ævar Arnfjörð Bjarmason, git,
	Randall S. Becker

Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > How is enabling a configuration already present in `man` out of scope,
> > but running an *ENTIRELY* different program--such as konqueror or
> > woman--to view man pages is not?
> >
> >   git help --man git
> >
> > Doesn't even necessarily run man *already*.
> 
> As an end-user, I do not expect Git to run konqueror or woman with
> its own tweaks when it does so.  And I do not see a reason why "man"
> should be any different.

You skipped the first question: 

Do you also expect that `git diff a b` runs something similar to
`diff a b`?

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  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
  1 sibling, 1 reply; 33+ messages in thread
From: brian m. carlson @ 2021-05-21  0:58 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, Felipe Contreras, git, Randall S. Becker,
	Leah Neukirchen

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

On 2021-05-19 at 08:41:44, Ævar Arnfjörð Bjarmason wrote:
> It also doesn't seem to me to satisfy their FAQ point #1, i.e. users who
> actually want no color at all can just set TERM=dumb, and we support
> that. The proposed patch is the same as having TERM=dumb set.
> 
> This NO_COLOR=1 actually means something like "I do support colors, so
> show them if it's important, but don't color things willy-nilly".

I don't agree.  The way I read it is that it means that if your program
receives colored input, it is not obligated to strip it out, but it is
obligated not to add any.  For example, if less supported NO_COLOR, then
it would render color it received on stdin, but not color its status
bars.

For Git, this means that we shouldn't add color, but if a user has
stuffed some ANSI escape sequences in their formatting string, we'll
pass them through.

> So it would be incorrect to map it to either color.ui=never or
> color.ui=always (as "auto" will implicitly do). We'd need a new knob to
> control the granularity of coloring, something like
> color.ui=conservative.

No, I think in the context of Git it means, "I don't want color."

> I wasn't against NO_COLOR before, but after writing the above I think I
> am. I initially assumed that it was some redundant and more "friendly"
> way of setting TERM=dumb, but rather it's some entirely subjective way
> for every program to decide if their UI elements are "text-editor"-like
> or "status bar"-like enough to warrant coloring.

TERM=dumb turns off having an addressable cursor.  Git uses a pager for
a lot of output, so that's a completely undesirable way to indicate you
don't want color, since it makes scrolling backwards impossible (and may
even disable the pager, but I haven't checked).  For a text editor,
TERM=dumb means you're stuck with ex or ed.

NO_COLOR=1 says, "I don't want color, but I have a fully functional
terminal I would like to use, thank you."

I should point out that I think you've misread the text about status
bars.  It says this:

  It is reasonable to configure certain software such as a text editor
  to use color or other ANSI attributes sparingly (such as the reverse
  attribute for a status bar) while still desiring that other software
  not add color unless configured to. It should be up to the user
  whether color is used, not the software author.

In other words, I think in this case, the user has opted to configure
their editor as they like it and invoke it without NO_COLOR, but has
instructed other programs to not add color with NO_COLOR.

Note also that the explanation specifically mentions the reverse
attribute, which TERM=dumb will suppress.

> That's "against" in the sense that if git supported it I wouldn't care
> much, and wouldn't oppose a patch to implement it.

I will probably send a patch to implement it, just not tonight.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

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

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21  0:58               ` brian m. carlson
@ 2021-05-21 18:09                 ` Felipe Contreras
  2021-05-21 19:48                   ` Igor Djordjevic
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-21 18:09 UTC (permalink / raw)
  To: brian m. carlson, Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, Felipe Contreras, git, Randall S. Becker,
	Leah Neukirchen

brian m. carlson wrote:
> On 2021-05-19 at 08:41:44, Ævar Arnfjörð Bjarmason wrote:
> > It also doesn't seem to me to satisfy their FAQ point #1, i.e. users who
> > actually want no color at all can just set TERM=dumb, and we support
> > that. The proposed patch is the same as having TERM=dumb set.
> > 
> > This NO_COLOR=1 actually means something like "I do support colors, so
> > show them if it's important, but don't color things willy-nilly".
> 
> I don't agree.  The way I read it is that it means that if your program
> receives colored input, it is not obligated to strip it out, but it is
> obligated not to add any.

The very example they give says otherwise:

  It is reasonable to configure certain software such as a text editor
  to use color

They are saying a text editor adding color is *fine*.

> NO_COLOR=1 says, "I don't want color, but I have a fully functional
> terminal I would like to use, thank you."

That's not what it says.

> In other words, I think in this case, the user has opted to configure
> their editor as they like it and invoke it without NO_COLOR, but has
> instructed other programs to not add color with NO_COLOR.

That is a reasonable interpretation... until you read the next
answer:

  A user should be able to export $NO_COLOR in their shell configuration
  file as a default, but configure a specific program in its
  configuration file to specifically enable color.

The whole point is not to configure each program to disable color, but
have a global NO_COLOR.

So I don't think your interpretation is correct.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 18:09                 ` Felipe Contreras
@ 2021-05-21 19:48                   ` Igor Djordjevic
  2021-05-21 21:20                     ` Felipe Contreras
                                       ` (2 more replies)
  0 siblings, 3 replies; 33+ messages in thread
From: Igor Djordjevic @ 2021-05-21 19:48 UTC (permalink / raw)
  To: Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

Hi all,

If I may, NO_COLOR approach seems to be rather straightforward to me, 
as per description on their homepage[1] - make all software supporting 
it behave as colors are an opt-in feature, thus disabled by default.

And that's all there is to it.

Software which is able to but does not show any colors by default does 
not need to care at all, as colors are an opt-in feature there already, 
so NO_COLOR serves no purpose.

On the other hand, software which does enable (at least some) color 
by default, without user explicitly setting anything but requiring 
opt-out to disable color instead, should treat NO_COLOR precisely as 
that user requested opt-out, with an obvious convenience for the user 
being able to set NO_COLOR globally once and have all the programs 
supporting it recognize it as color opt-out exactly, without a need  
for the user to opt-out in each and every program separately 
(and differently).

So, the whole point is make the default value be "no color" for each 
and every application consistently, where user (and _not_ developer) 
needs to opt-in in order to enable colors (in each and every 
application where colors are in fact still desired).

Regards, Buga
--
[1]: https://no-color.org/

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 19:48                   ` Igor Djordjevic
@ 2021-05-21 21:20                     ` Felipe Contreras
  2021-05-21 22:10                       ` Igor Djordjevic
  2021-05-21 22:47                     ` Igor Djordjevic
  2021-05-21 23:32                     ` Junio C Hamano
  2 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-21 21:20 UTC (permalink / raw)
  To: Igor Djordjevic, Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

Igor Djordjevic wrote:
> If I may, NO_COLOR approach seems to be rather straightforward to me, 
> as per description on their homepage[1] - make all software supporting 
> it behave as colors are an opt-in feature, thus disabled by default.

May I ask you how you interpret this?

  It is reasonable to configure certain software such as a text editor
  to use color ... sparingly

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 21:20                     ` Felipe Contreras
@ 2021-05-21 22:10                       ` Igor Djordjevic
  2021-05-21 23:04                         ` Felipe Contreras
  0 siblings, 1 reply; 33+ messages in thread
From: Igor Djordjevic @ 2021-05-21 22:10 UTC (permalink / raw)
  To: Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

On 21/05/2021 23:20, Felipe Contreras wrote:
> Igor Djordjevic wrote:
> > 
> > If I may, NO_COLOR approach seems to be rather straightforward to me, 
> > as per description on their homepage[1] - make all software supporting 
> > it behave as colors are an opt-in feature, thus disabled by default.
> 
> May I ask you how you interpret this?
> 
>   It is reasonable to configure certain software such as a text editor
>   to use color ... sparingly

Sure, but to make the point (hopefully) even more obvious, let me 
quote the whole part:

  It is reasonable to configure certain software such as a text editor 
  to use color or other ANSI attributes sparingly (such as the reverse 
  attribute for a status bar) while still desiring that other software 
  not add color unless configured to. It should be up to the user 
  whether color is used, not the software author.

I understand it exactly as (I think) it says - it is reasonable to 
allow (the user, not developer!) to configure certain software to 
(still) use color (fully or sparingly should not even matter, and it 
may depend on what kind of granular configuration software allows in 
the first place, if any), even if his (user's) general ("default") 
preference is to have no colors.

Thus color should be user opt-in - NO_COLOR turns all of it off by 
default (for all software supporting it), and user decides which color 
to turn back on through each specific software color configuration.

That last sentence should make it clear - "it should be up to the 
user whether color is used, not the software author".

So it shouldn't matter what does software author think about which 
parts of software should be (fully or sparingly) colored (by default) 
- NO_COLOR's idea is to give the ultimate power to the user to 
decide, and on a global level, starting with no colors by default, 
then allowing colors where desired, per each specific software config 
(instead of vice-versa, being required to turn color off per each 
specific software, where color is otherwise used by default).

At least that's how I understand all of it, making sense to me, but I 
don't mind discussing it further, if needed.

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 19:48                   ` Igor Djordjevic
  2021-05-21 21:20                     ` Felipe Contreras
@ 2021-05-21 22:47                     ` Igor Djordjevic
  2021-05-21 23:32                     ` Junio C Hamano
  2 siblings, 0 replies; 33+ messages in thread
From: Igor Djordjevic @ 2021-05-21 22:47 UTC (permalink / raw)
  To: Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

On 21/05/2021 21:48, Igor Djordjevic wrote:
> 
> So, the whole point is make the default value be "no color" for each 
> and every application consistently, where user (and _not_ developer) 
> needs to opt-in in order to enable colors (in each and every 
> application where colors are in fact still desired).

Oh, and might be what NO_COLOR homepage provides as a tip for 
"disabling color in software not supporting NO_COLOR" for Git 
specifically might be a good (and enough of a) clue by itself...?

  git config --global color.ui false

So I'd argue that Git should react to NO_COLOR exactly as it should 
react to `color.ui` set to false - disabling all color.

Do note it's only by default, in case no (other) color configuration is 
specified - any existing user config should take precedence, of course, 
further acting as per user's desire ("... NO_COLOR says I prefer no 
color in general, but I do want color in this specific case, enabled by 
setting this software specific config option explicitly...").

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 22:10                       ` Igor Djordjevic
@ 2021-05-21 23:04                         ` Felipe Contreras
  2021-05-22 18:38                           ` Igor Djordjevic
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-21 23:04 UTC (permalink / raw)
  To: Igor Djordjevic, Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

Igor Djordjevic wrote:
> On 21/05/2021 23:20, Felipe Contreras wrote:
> > Igor Djordjevic wrote:
> > > 
> > > If I may, NO_COLOR approach seems to be rather straightforward to me, 
> > > as per description on their homepage[1] - make all software supporting 
> > > it behave as colors are an opt-in feature, thus disabled by default.
> > 
> > May I ask you how you interpret this?
> > 
> >   It is reasonable to configure certain software such as a text editor
> >   to use color ... sparingly
> 
> Sure, but to make the point (hopefully) even more obvious, let me 
> quote the whole part:
> 
>   It is reasonable to configure certain software such as a text editor 
>   to use color or other ANSI attributes sparingly (such as the reverse 
>   attribute for a status bar) while still desiring that other software 
>   not add color unless configured to. It should be up to the user 
>   whether color is used, not the software author.
> 
> I understand it exactly as (I think) it says - it is reasonable to 
> allow (the user, not developer!) to configure certain software to 
> (still) use color

This does not follow.

The contraposition of that statement is that if a text editor doesn't
use color sparingly, then the user should not be allowed to configure
such software.

Do you really think that's what they are saying? The user should not
have a choice? (with certain software) That's color fascism.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 19:48                   ` Igor Djordjevic
  2021-05-21 21:20                     ` Felipe Contreras
  2021-05-21 22:47                     ` Igor Djordjevic
@ 2021-05-21 23:32                     ` Junio C Hamano
  2 siblings, 0 replies; 33+ messages in thread
From: Junio C Hamano @ 2021-05-21 23:32 UTC (permalink / raw)
  To: Igor Djordjevic
  Cc: Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason, git, Randall S. Becker,
	Leah Neukirchen

Igor Djordjevic <igor.d.djordjevic@gmail.com> writes:

> Hi all,
>
> If I may, NO_COLOR approach seems to be rather straightforward to me, 
> as per description on their homepage[1] - make all software supporting 
> it behave as colors are an opt-in feature, thus disabled by default.

Yes, that is correct and this was discussed already in detail a few
days ago.  You can start from here:

  https://lore.kernel.org/git/YKRSlFcFAcHcR3uY@camp.crustytoothpaste.net/

and read two or three messages.

Note that you probably want to take generic NO_COLOR support
(i.e. teaching the "now we know the user wants the 'default'
behaviour by not having an explicit 'yes/no'; do we want to color
the output?" helper function to pay attention to the environment
variable) as taken by somebody already:

  https://lore.kernel.org/git/YKcFrbuuJrWAxXgm@camp.crustytoothpaste.net/

Thanks.

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-21 23:04                         ` Felipe Contreras
@ 2021-05-22 18:38                           ` Igor Djordjevic
  2021-05-22 21:48                             ` Felipe Contreras
  0 siblings, 1 reply; 33+ messages in thread
From: Igor Djordjevic @ 2021-05-22 18:38 UTC (permalink / raw)
  To: Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen


On 22/05/2021 01:04, Felipe Contreras wrote:
> Igor Djordjevic wrote:
> >
> > ... to make the point (hopefully) even more obvious, let me 
> > quote the whole part:
> >
> >   It is reasonable to configure certain software such as a text editor 
> >   to use color or other ANSI attributes sparingly (such as the reverse 
> >   attribute for a status bar) while still desiring that other software 
> >   not add color unless configured to. It should be up to the user 
> >   whether color is used, not the software author.
> >
> > I understand it exactly as (I think) it says - it is reasonable to 
> > allow (the user, not developer!) to configure certain software to 
> > (still) use color
> 
> This does not follow.

Sure, if that is the only part you read ("followed"), taking it out 
of context while chopping the rest...

> The contraposition of that statement is that if a text editor doesn't
> use color sparingly, then the user should not be allowed to configure
> such software.
> 
> Do you really think that's what they are saying? The user should not
> have a choice? (with certain software) That's color fascism.

What I really think is that my message which you replied to - but 
decided to quote only _sparingly_ ;) - already addressed both use of 
"sparingly" and who should have the choice (not to say all the power) 
in a very clear and explicit manner (hint: user exactly), so I'm afraid 
I'd have nothing more to add, sorry.

Regards, Buga

p.s. Oh, and please do allow me to _opt-in_ the missing part of my 
message back :) (for whatever that will be worth, eh):

> > I understand it exactly as (I think) it says - it is reasonable to 
> > allow (the user, not developer!) to configure certain software to 
> > (still) use color (fully or sparingly should not even matter, and it 
> > may depend on what kind of granular configuration software allows in 
> > the first place, if any), even if his (user's) general ("default") 
> > preference is to have no colors.
> > 
> > Thus color should be user opt-in - NO_COLOR turns all of it off by 
> > default (for all software supporting it), and user decides which color 
> > to turn back on through each specific software color configuration.
> > 
> > That last sentence should make it clear - "it should be up to the 
> > user whether color is used, not the software author".
> > 
> > So it shouldn't matter what does software author think about which 
> > parts of software should be (fully or sparingly) colored (by default) 
> > - NO_COLOR's idea is to give the ultimate power to the user to 
> > decide, and on a global level, starting with no colors by default, 
> > then allowing colors where desired, per each specific software config 
> > (instead of vice-versa, being required to turn color off per each 
> > specific software, where color is otherwise used by default).

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-22 18:38                           ` Igor Djordjevic
@ 2021-05-22 21:48                             ` Felipe Contreras
  2021-05-23 11:25                               ` Igor Djordjevic
  0 siblings, 1 reply; 33+ messages in thread
From: Felipe Contreras @ 2021-05-22 21:48 UTC (permalink / raw)
  To: Igor Djordjevic, Felipe Contreras, brian m. carlson,
	Ævar Arnfjörð Bjarmason
  Cc: Junio C Hamano, git, Randall S. Becker, Leah Neukirchen

Igor Djordjevic wrote:
> 
> On 22/05/2021 01:04, Felipe Contreras wrote:
> > Igor Djordjevic wrote:
> > >
> > > ... to make the point (hopefully) even more obvious, let me 
> > > quote the whole part:
> > >
> > >   It is reasonable to configure certain software such as a text editor 
> > >   to use color or other ANSI attributes sparingly (such as the reverse 
> > >   attribute for a status bar) while still desiring that other software 
> > >   not add color unless configured to. It should be up to the user 
> > >   whether color is used, not the software author.
> > >
> > > I understand it exactly as (I think) it says - it is reasonable to 
> > > allow (the user, not developer!) to configure certain software to 
> > > (still) use color
> > 
> > This does not follow.
> 
> Sure, if that is the only part you read ("followed"), taking it out 
> of context while chopping the rest...

Language is understood bit by bit. To properly understand the sentences
that follow you first need to understand the sentences that preceed.

> > The contraposition of that statement is that if a text editor doesn't
> > use color sparingly, then the user should not be allowed to configure
> > such software.
> > 
> > Do you really think that's what they are saying? The user should not
> > have a choice? (with certain software) That's color fascism.
> 
> What I really think is that my message which you replied to - but 
> decided to quote only _sparingly_ ;) - already addressed both use of 
> "sparingly" and who should have the choice (not to say all the power) 
> in a very clear and explicit manner (hint: user exactly), so I'm afraid 
> I'd have nothing more to add, sorry.

I know what you said in the rest of the message, which is precisely why
it does not follow, and since you ignored my argument, let me state it
with logic symbols for the record.

  It is reasonable to configure certain software such as a text editor
  to use color or other ANSI attributes sparingly (such as the reverse
  attribute for a status bar)

We extract part of the message:

  It is reasonable to configure a text editor to use color sparingly

The first sentence implies the second, no information is changed.

---

You interpret that as:

  It is reasonable to allow the user to configure a text editor to use
  color sparingly

This is obviously a different sentence. You introduced a part that was
not there.

Now we use logic symbols to transform your sentence:

  p = the user configures a text editor to use color sparingly
  q = it is reasonable to allow the user

This is what you said: if p -> q. The contraposition is: ~q -> ~p.

Therefore you said:

  It is not reasonable to allow the user to configure a text editor to
  not use color sparingly.

This is a fact.

What you said doesn't make sense.

---

This what no-color.org said:

  It is reasonable to configure a text editor to use color sparingly

By doing the same contraposition as above we get that it's the same as:

  It is not reasonale to configure a text editor to not use color
  sparingly.

Or in other words.

  It is not reasonable to configure a text editor to use colors heavily.

If it's the developers doing that, then that statement is correct.

This is my interpretation. My interpretation holds to scrutiny; yours
does not.

They meant the developers. They are not trying to tell users what to do.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-22 21:48                             ` Felipe Contreras
@ 2021-05-23 11:25                               ` Igor Djordjevic
  2021-05-23 14:48                                 ` Felipe Contreras
  0 siblings, 1 reply; 33+ messages in thread
From: Igor Djordjevic @ 2021-05-23 11:25 UTC (permalink / raw)
  To: Felipe Contreras; +Cc: git


On 22/05/2021 23:48, Felipe Contreras wrote:
> 
> Language is understood bit by bit. To properly understand the sentences
> that follow you first need to understand the sentences that preceed.

Except you can't deliberately chop and butcher mentioned sentences in 
order to "understand" them in isolation, as the meaning is largely 
determined by context - and yes, the following sentences as well.

You focus on seeing the trees, but you're missing the forest.

> I know what you said in the rest of the message, which is precisely why
> it does not follow, and since you ignored my argument, let me state it
> with logic symbols for the record.
> 
>   It is reasonable to configure certain software such as a text editor
>   to use color or other ANSI attributes sparingly (such as the reverse
>   attribute for a status bar)
> 
> We extract part of the message:
> 
>   It is reasonable to configure a text editor to use color sparingly
> 
> The first sentence implies the second, no information is changed.
> 
> ---
> 
> You interpret that as:
> 
>   It is reasonable to allow the user to configure a text editor to use
>   color sparingly
> 
> This is obviously a different sentence. You introduced a part that was
> not there.
> 
> Now we use logic symbols to transform your sentence:
> 
>   p = the user configures a text editor to use color sparingly
>   q = it is reasonable to allow the user
> 
> This is what you said: if p -> q. The contraposition is: ~q -> ~p.
> 
> Therefore you said:
> 
>   It is not reasonable to allow the user to configure a text editor to
>   not use color sparingly.
> 
> This is a fact.
> 
> What you said doesn't make sense.
> 
> ---
> 
> This what no-color.org said:
> 
>   It is reasonable to configure a text editor to use color sparingly
> 
> By doing the same contraposition as above we get that it's the same as:
> 
>   It is not reasonale to configure a text editor to not use color
>   sparingly.
> 
> Or in other words.
> 
>   It is not reasonable to configure a text editor to use colors heavily.
> 
> If it's the developers doing that, then that statement is correct.
> 
> This is my interpretation. My interpretation holds to scrutiny; yours
> does not.
> 
> They meant the developers. They are not trying to tell users what to do.
> 
> Cheers.

You are overthinking the whole thing (or the piece(s) you focused on, in 
fact missing the thing as a whole completely), making it unnecessarily 
complicated for yourself.

The NO_COLOR[1] homepage text, read in its entirety and even if not 
perfect, seems clear enough for everyone who wants to understand it. 
I'm sorry if it's not clear for you, I'm afraid I can't help any 
further.

And while I find your armchair analysis amusing, you'll pardon me for 
not taking any more part in it as, unfortunately, I don't have that 
much time at my hands to waste.

Cheers, Buga
--
[1]: https://no-color.org/

^ permalink raw reply	[flat|nested] 33+ messages in thread

* Re: [PATCH] help: colorize man pages
  2021-05-23 11:25                               ` Igor Djordjevic
@ 2021-05-23 14:48                                 ` Felipe Contreras
  0 siblings, 0 replies; 33+ messages in thread
From: Felipe Contreras @ 2021-05-23 14:48 UTC (permalink / raw)
  To: Igor Djordjevic, Felipe Contreras; +Cc: git

Igor Djordjevic wrote:
> 
> On 22/05/2021 23:48, Felipe Contreras wrote:
> > 
> > Language is understood bit by bit. To properly understand the sentences
> > that follow you first need to understand the sentences that preceed.
> 
> Except you can't deliberately chop and butcher mentioned sentences in 
> order to "understand" them in isolation, as the meaning is largely 
> determined by context - and yes, the following sentences as well.

Please explain the context that makes this sentense makes ense:

  It is not reasonable to allow the user to configure a text editor to
  not use color heavily.

> The NO_COLOR[1] homepage text, read in its entirety and even if not 
> perfect, seems clear enough for everyone who wants to understand it. 

Yes, it is clear: software who use colors heavily should respect
NO_COLOR.

Others on this list agree.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 33+ messages in thread

end of thread, other threads:[~2021-05-23 14:48 UTC | newest]

Thread overview: 33+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-18  1:01 [PATCH] help: colorize man pages 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
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

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