git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Felipe Contreras <felipe.contreras@gmail.com>
To: git@vger.kernel.org
Cc: "Phillip Wood" <phillip.wood123@gmail.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Jeff King" <peff@peff.net>, "Junio C Hamano" <gitster@pobox.com>,
	"Felipe Contreras" <felipe.contreras@gmail.com>
Subject: [PATCH v5] help: colorize man pages
Date: Fri, 21 May 2021 20:17:18 -0500	[thread overview]
Message-ID: <20210522011718.541986-1-felipe.contreras@gmail.com> (raw)

We already colorize tools traditionally not colorized by default, like
diff and grep. Let's do the same for man.

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 the LESS variable to render bold, underlined, and standout
text with colors in the less pager.

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

Obviously this only works when the less pager is used.

If the user has already set the LESS variable in his/her environment,
that is respected, and nothing changes. The same if any LESS_TERMCAP_*
variables are set.

A new color configuration is added: `color.man` for the people that want
to turn this feature off, otherwise `color.ui` is respected.
Additionally, if color.pager is not enabled, this is disregarded.

Normally check_auto_color() would check the value of `color.pager`, but
in this particular case it's not git the one executing the pager, but
man. Therefore we need to check pager_use_color ourselves.

Also--unlike other color.* configurations--color.man=always does not
make any sense here; `git help` is always run for a tty (it would be very
strange for a user to do `git help $page > output`, but in fact, that
works anyway, we don't even need to check if stdout is a tty, but just
to be consistent we do). So it's simply a boolean in our case.

So, in order for this change to have any effect:

 1. The user must use less
 2. Not have the LESS variable set
 3. Have color.ui enabled
 4. Not have color.pager disabled
 5. Not have color.man disabled
 7. Not have git with stdout directed to a file

Fortunately the vast majority of our users meet all of the above, and
anybody who doesn't would not be affected negatively (plus very likely
comprises a very tiny minority).

Suggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Comments-by: Phillip Wood <phillip.wood123@gmail.com>
Comments-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---

I removed the NO_COLOR check (seems to be contentious, and can be added
later anyway), and added check to make sure the user has no
LESS_TERMCAP_* variables set.

I also fixed the missing color for standout.

Range-diff against v4:
1:  7249785014 ! 1:  a1190a1c67 help: colorize man pages
    @@ Commit message
         Obviously this only works when the less pager is used.
     
         If the user has already set the LESS variable in his/her environment,
    -    that is respected, and nothing changes.
    +    that is respected, and nothing changes. The same if any LESS_TERMCAP_*
    +    variables are set.
     
         A new color configuration is added: `color.man` for the people that want
         to turn this feature off, otherwise `color.ui` is respected.
    @@ Commit message
         Also--unlike other color.* configurations--color.man=always does not
         make any sense here; `git help` is always run for a tty (it would be very
         strange for a user to do `git help $page > output`, but in fact, that
    -    works automatically [probably thanks to less being smart], we don't even
    -    need to check if stdout is a tty, but just to be consistent we do). So
    -    it's simply a boolean in our case.
    -
    -    Moreover, just to be painstakingly comprehensive with people who have
    -    color-aversion; we honour NO_COLOR [1].
    +    works anyway, we don't even need to check if stdout is a tty, but just
    +    to be consistent we do). So it's simply a boolean in our case.
     
         So, in order for this change to have any effect:
     
    @@ Commit message
          3. Have color.ui enabled
          4. Not have color.pager disabled
          5. Not have color.man disabled
    -     6. Not have NO_COLOR set
          7. Not have git with stdout directed to a file
     
         Fortunately the vast majority of our users meet all of the above, and
         anybody who doesn't would not be affected negatively (plus very likely
         comprises a very tiny minority).
     
    -    [1] https://no-color.org/
    -
         Suggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
         Comments-by: Jeff King <peff@peff.net>
         Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
    @@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *pag
     +	if (!man_color || !want_color(GIT_COLOR_UNKNOWN) || !pager_use_color)
     +		return;
     +
    -+	/* See: https://no-color.org/ */
    -+	if (getenv("NO_COLOR"))
    ++	/* User already has configured less colors */
    ++	if (getenv("LESS_TERMCAP_md") ||
    ++		getenv("LESS_TERMCAP_us") ||
    ++		getenv("LESS_TERMCAP_so")) {
     +		return;
    ++	}
     +
     +	/* Disable groff colors */
     +	setenv("GROFF_NO_SGR", "1", 0);
     +
     +	/* Add red to bold, blue to underline, and magenta to standout */
     +	/* No visual information is lost */
    -+	setenv("LESS", "Dd+r$Du+b$Ds", 0);
    ++	setenv("LESS", "Dd+r$Du+b$Ds+m", 0);
     +}
     +
      static void exec_man_man(const char *path, const char *page)

 Documentation/config/color.txt |  5 +++++
 builtin/help.c                 | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index d5daacb13a..11278b7f72 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt
@@ -126,6 +126,11 @@ color.interactive.<slot>::
 	or `error`, for four distinct types of normal output from
 	interactive commands.
 
+color.man::
+	This flag can be used to disable the automatic colorizaton of man
+	pages when using the less pager. It's activated only when color.ui
+	allows it, and also when color.pager is on. (`true` by default).
+
 color.pager::
 	A boolean to enable/disable colored output when the pager is in
 	use (default is true).
diff --git a/builtin/help.c b/builtin/help.c
index bb339f0fc8..f64b1a5aa5 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"
@@ -43,6 +44,7 @@ static int verbose = 1;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static int exclude_guides;
+static int man_color = 1;
 static struct option builtin_help_options[] = {
 	OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
 	OPT_HIDDEN_BOOL(0, "exclude-guides", &exclude_guides, N_("exclude guides")),
@@ -253,10 +255,32 @@ static void exec_man_konqueror(const char *path, const char *page)
 	}
 }
 
+static void colorize_man(void)
+{
+	if (!man_color || !want_color(GIT_COLOR_UNKNOWN) || !pager_use_color)
+		return;
+
+	/* User already has configured less colors */
+	if (getenv("LESS_TERMCAP_md") ||
+		getenv("LESS_TERMCAP_us") ||
+		getenv("LESS_TERMCAP_so")) {
+		return;
+	}
+
+	/* Disable groff colors */
+	setenv("GROFF_NO_SGR", "1", 0);
+
+	/* Add red to bold, blue to underline, and magenta to standout */
+	/* No visual information is lost */
+	setenv("LESS", "Dd+r$Du+b$Ds+m", 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);
@@ -371,8 +396,12 @@ 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);
+	if (!strcmp(var, "color.man")) {
+		man_color = git_config_bool(var, value);
+		return 0;
+	}
 
-	return git_default_config(var, value, cb);
+	return git_color_default_config(var, value, cb);
 }
 
 static struct cmdnames main_cmds, other_cmds;
-- 
2.32.0.rc0


             reply	other threads:[~2021-05-22  1:17 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-22  1:17 Felipe Contreras [this message]
2021-05-22  9:56 ` [PATCH v5] help: colorize man pages Jeff King
2021-05-22 21:15   ` Felipe Contreras

Reply instructions:

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

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

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

  List information: http://vger.kernel.org/majordomo-info.html

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

  git send-email \
    --in-reply-to=20210522011718.541986-1-felipe.contreras@gmail.com \
    --to=felipe.contreras@gmail.com \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    --cc=phillip.wood123@gmail.com \
    /path/to/YOUR_REPLY

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

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

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 read-only IMAP folder(s) and NNTP newsgroup(s).