[PATCH v2] help: colorize man pages

[Felipe Contreras <felipe.contreras@gmail.com>]

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.

If the user already has LESS_TERMCAP variables set in his/her
environment, those are respected and not overwritten.

A new color configuration is added: `color.man`, otherwise `color.ui` is
respected, and in addition color.pager needs to turned on.

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.

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

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>
---
Range-diff against v1:
1:  a943dedab8 ! 1:  9e34a49fa9 help: colorize man pages
    @@ Commit message
         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.
    +    This only works when the pager is less.
    +
    +    If the user already has LESS_TERMCAP variables set in his/her
    +    environment, those are respected and not overwritten.
    +
    +    A new color configuration is added: `color.man`, otherwise `color.ui` is
    +    respected, and in addition color.pager needs to turned on.
    +
    +    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.
     
         [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
     
    +    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>
     
    + ## Documentation/config/color.txt ##
    +@@ Documentation/config/color.txt: color.interactive.<slot>::
    + 	or `error`, for four distinct types of normal output from
    + 	interactive commands.
    + 
    ++color.man::
    ++	When set to `always`, always colorize the man pages. When `false`
    ++	(or `never`), never.  When set to `true` or `auto`, use color only
    ++	when the output is written to the terminal. If unset, then the
    ++	value of `color.ui` is used (`auto` by default).
    ++
    + color.pager::
    + 	A boolean to enable/disable colored output when the pager is in
    + 	use (default is true).
    +
      ## builtin/help.c ##
     @@
      #include "config-list.h"
    @@ builtin/help.c
      
      #ifndef DEFAULT_HELP_FORMAT
      #define DEFAULT_HELP_FORMAT "man"
    +@@ builtin/help.c: 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 = GIT_COLOR_UNKNOWN;
    + 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")),
     @@ builtin/help.c: 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))
    ++	if (!want_color(man_color) || !pager_use_color)
     +		return;
     +
     +	/* Disable groff colors */
    @@ builtin/help.c: static void exec_man_man(const char *path, const char *page)
      	execl(SHELL_PATH, SHELL_PATH, "-c", shell_cmd.buf, (char *)NULL);
      	warning(_("failed to exec '%s'"), cmd);
     @@ builtin/help.c: 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_colorbool(var, value);
    ++		return 0;
    ++	}
      
     -	return git_default_config(var, value, cb);
     +	return git_color_default_config(var, value, cb);

 Documentation/config/color.txt |  6 ++++++
 builtin/help.c                 | 32 +++++++++++++++++++++++++++++++-
 color.h                        |  1 +
 3 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
index d5daacb13a..02019a612c 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.txt
@@ -126,6 +126,12 @@ color.interactive.<slot>::
 	or `error`, for four distinct types of normal output from
 	interactive commands.
 
+color.man::
+	When set to `always`, always colorize the man pages. When `false`
+	(or `never`), never.  When set to `true` or `auto`, use color only
+	when the output is written to the terminal. If unset, then the
+	value of `color.ui` is used (`auto` 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..05c758ca1b 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 = GIT_COLOR_UNKNOWN;
 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,33 @@ static void exec_man_konqueror(const char *path, const char *page)
 	}
 }
 
+static void colorize_man(void)
+{
+	if (!want_color(man_color) || !pager_use_color)
+		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 +289,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 +397,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_colorbool(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;
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