{"thread":{"id":"55723","subject":"[PATCH v2] help: colorize man pages","startedAt":"2021-05-18T13:21:03Z","lastAt":"2021-05-18T20:53:42Z","messageCount":3,"participants":["Felipe Contreras","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"424866","messageId":"20210518132056.2003135-1-felipe.contreras@gmail.com","threadId":"55723","inReplyTo":null,"subject":"[PATCH v2] help: colorize man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T13:20:56Z","receivedAt":"2021-05-18T13:21:03Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Our man pages don't contain many useful colors (just blue links),\nmoreover, many people have groff SGR disabled, so they don't see any\ncolors with man pages.\n\nWe can set LESS_TERMCAP variables to render bold and underlined text\nwith colors in the pager; a common trick[1].\n\nBold is rendered as red, underlined as blue, and standout (messages and\nhighlighted search) as inverse magenta.\n\nThis only works when the pager is less.\n\nIf the user already has LESS_TERMCAP variables set in his/her\nenvironment, those are respected and not overwritten.\n\nA new color configuration is added: `color.man`, otherwise `color.ui` is\nrespected, and in addition color.pager needs to turned on.\n\nNormally check_auto_color() would check the value of `color.pager`, but\nin this particular case it's not git the one executing the pager, but\nman. Therefore we need to check pager_use_color ourselves.\n\n[1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147\n\nSuggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\nComments-by: Jeff King <peff@peff.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\nRange-diff against v1:\n1:  a943dedab8 ! 1:  9e34a49fa9 help: colorize man pages\n    @@ Commit message\n         Bold is rendered as red, underlined as blue, and standout (messages and\n         highlighted search) as inverse magenta.\n     \n    -    This only works when the pager is less, and the color.pager\n    -    configuration is enabled, as well as color.ui.\n    +    This only works when the pager is less.\n    +\n    +    If the user already has LESS_TERMCAP variables set in his/her\n    +    environment, those are respected and not overwritten.\n    +\n    +    A new color configuration is added: `color.man`, otherwise `color.ui` is\n    +    respected, and in addition color.pager needs to turned on.\n    +\n    +    Normally check_auto_color() would check the value of `color.pager`, but\n    +    in this particular case it's not git the one executing the pager, but\n    +    man. Therefore we need to check pager_use_color ourselves.\n     \n         [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147\n     \n    +    Suggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n    +    Comments-by: Jeff King <peff@peff.net>\n         Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n     \n    + ## Documentation/config/color.txt ##\n    +@@ Documentation/config/color.txt: color.interactive.<slot>::\n    + \tor `error`, for four distinct types of normal output from\n    + \tinteractive commands.\n    + \n    ++color.man::\n    ++\tWhen set to `always`, always colorize the man pages. When `false`\n    ++\t(or `never`), never.  When set to `true` or `auto`, use color only\n    ++\twhen the output is written to the terminal. If unset, then the\n    ++\tvalue of `color.ui` is used (`auto` by default).\n    ++\n    + color.pager::\n    + \tA boolean to enable/disable colored output when the pager is in\n    + \tuse (default is true).\n    +\n      ## builtin/help.c ##\n     @@\n      #include \"config-list.h\"\n    @@ builtin/help.c\n      \n      #ifndef DEFAULT_HELP_FORMAT\n      #define DEFAULT_HELP_FORMAT \"man\"\n    +@@ builtin/help.c: static int verbose = 1;\n    + static unsigned int colopts;\n    + static enum help_format help_format = HELP_FORMAT_NONE;\n    + static int exclude_guides;\n    ++static int man_color = GIT_COLOR_UNKNOWN;\n    + static struct option builtin_help_options[] = {\n    + \tOPT_BOOL('a', \"all\", &show_all, N_(\"print all available commands\")),\n    + \tOPT_HIDDEN_BOOL(0, \"exclude-guides\", &exclude_guides, N_(\"exclude guides\")),\n     @@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *page)\n      \t}\n      }\n      \n     +static void colorize_man(void)\n     +{\n    -+\tif (!pager_use_color || !want_color(GIT_COLOR_UNKNOWN))\n    ++\tif (!want_color(man_color) || !pager_use_color)\n     +\t\treturn;\n     +\n     +\t/* Disable groff colors */\n    @@ builtin/help.c: static void exec_man_man(const char *path, const char *page)\n      \texecl(SHELL_PATH, SHELL_PATH, \"-c\", shell_cmd.buf, (char *)NULL);\n      \twarning(_(\"failed to exec '%s'\"), cmd);\n     @@ builtin/help.c: static int git_help_config(const char *var, const char *value, void *cb)\n    + \t}\n      \tif (starts_with(var, \"man.\"))\n      \t\treturn add_man_viewer_info(var, value);\n    ++\tif (!strcmp(var, \"color.man\")) {\n    ++\t\tman_color = git_config_colorbool(var, value);\n    ++\t\treturn 0;\n    ++\t}\n      \n     -\treturn git_default_config(var, value, cb);\n     +\treturn git_color_default_config(var, value, cb);\n\n Documentation/config/color.txt |  6 ++++++\n builtin/help.c                 | 32 +++++++++++++++++++++++++++++++-\n color.h                        |  1 +\n 3 files changed, 38 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config/color.txt b/Documentation/config/color.txt\nindex d5daacb13a..02019a612c 100644\n--- a/Documentation/config/color.txt\n+++ b/Documentation/config/color.txt\n@@ -126,6 +126,12 @@ color.interactive.<slot>::\n \tor `error`, for four distinct types of normal output from\n \tinteractive commands.\n \n+color.man::\n+\tWhen set to `always`, always colorize the man pages. When `false`\n+\t(or `never`), never.  When set to `true` or `auto`, use color only\n+\twhen the output is written to the terminal. If unset, then the\n+\tvalue of `color.ui` is used (`auto` by default).\n+\n color.pager::\n \tA boolean to enable/disable colored output when the pager is in\n \tuse (default is true).\ndiff --git a/builtin/help.c b/builtin/help.c\nindex bb339f0fc8..05c758ca1b 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -11,6 +11,7 @@\n #include \"config-list.h\"\n #include \"help.h\"\n #include \"alias.h\"\n+#include \"color.h\"\n \n #ifndef DEFAULT_HELP_FORMAT\n #define DEFAULT_HELP_FORMAT \"man\"\n@@ -43,6 +44,7 @@ static int verbose = 1;\n static unsigned int colopts;\n static enum help_format help_format = HELP_FORMAT_NONE;\n static int exclude_guides;\n+static int man_color = GIT_COLOR_UNKNOWN;\n static struct option builtin_help_options[] = {\n \tOPT_BOOL('a', \"all\", &show_all, N_(\"print all available commands\")),\n \tOPT_HIDDEN_BOOL(0, \"exclude-guides\", &exclude_guides, N_(\"exclude guides\")),\n@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page)\n \t}\n }\n \n+static void colorize_man(void)\n+{\n+\tif (!want_color(man_color) || !pager_use_color)\n+\t\treturn;\n+\n+\t/* Disable groff colors */\n+\tsetenv(\"GROFF_NO_SGR\", \"1\", 0);\n+\n+\t/* Bold */\n+\tsetenv(\"LESS_TERMCAP_md\", GIT_COLOR_BOLD_RED, 0);\n+\tsetenv(\"LESS_TERMCAP_me\", GIT_COLOR_RESET, 0);\n+\n+\t/* Underline */\n+\tsetenv(\"LESS_TERMCAP_us\", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0);\n+\tsetenv(\"LESS_TERMCAP_ue\", GIT_COLOR_RESET, 0);\n+\n+\t/* Standout */\n+\tsetenv(\"LESS_TERMCAP_so\", GIT_COLOR_MAGENTA GIT_COLOR_REVERSE, 0);\n+\tsetenv(\"LESS_TERMCAP_se\", GIT_COLOR_RESET, 0);\n+}\n+\n static void exec_man_man(const char *path, const char *page)\n {\n \tif (!path)\n \t\tpath = \"man\";\n+\n+\tcolorize_man();\n \texeclp(path, \"man\", page, (char *)NULL);\n \twarning_errno(_(\"failed to exec '%s'\"), path);\n }\n@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)\n static void exec_man_cmd(const char *cmd, const char *page)\n {\n \tstruct strbuf shell_cmd = STRBUF_INIT;\n+\tcolorize_man();\n \tstrbuf_addf(&shell_cmd, \"%s %s\", cmd, page);\n \texecl(SHELL_PATH, SHELL_PATH, \"-c\", shell_cmd.buf, (char *)NULL);\n \twarning(_(\"failed to exec '%s'\"), cmd);\n@@ -371,8 +397,12 @@ static int git_help_config(const char *var, const char *value, void *cb)\n \t}\n \tif (starts_with(var, \"man.\"))\n \t\treturn add_man_viewer_info(var, value);\n+\tif (!strcmp(var, \"color.man\")) {\n+\t\tman_color = git_config_colorbool(var, value);\n+\t\treturn 0;\n+\t}\n \n-\treturn git_default_config(var, value, cb);\n+\treturn git_color_default_config(var, value, cb);\n }\n \n static struct cmdnames main_cmds, other_cmds;\ndiff --git a/color.h b/color.h\nindex 98894d6a17..d012add4e8 100644\n--- a/color.h\n+++ b/color.h\n@@ -51,6 +51,7 @@ struct strbuf;\n #define GIT_COLOR_FAINT\t\t\"\\033[2m\"\n #define GIT_COLOR_FAINT_ITALIC\t\"\\033[2;3m\"\n #define GIT_COLOR_REVERSE\t\"\\033[7m\"\n+#define GIT_COLOR_UNDERLINE\t\"\\033[4m\"\n \n /* A special value meaning \"no color selected\" */\n #define GIT_COLOR_NIL \"NIL\"\n-- \n2.31.1\n\n"},{"id":"424882","messageId":"xmqqa6os2j05.fsf@gitster.g","threadId":"55723","inReplyTo":"20210518132056.2003135-1-felipe.contreras@gmail.com","subject":"Re: [PATCH v2] help: colorize man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-18T14:50:50Z","receivedAt":"2021-05-18T14:50:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> +color.man::\n> +\tWhen set to `always`, always colorize the man pages. When `false`\n> +\t(or `never`), never.  When set to `true` or `auto`, use color only\n> +\twhen the output is written to the terminal. If unset, then the\n> +\tvalue of `color.ui` is used (`auto` by default).\n\nMakes sense and is more in line with the rest of the system to have\nsubcommand specific color.* variable.\n\nThere are two things that make me wonder in the above description,\nthough.\n\n> +static void colorize_man(void)\n> +{\n> +\tif (!want_color(man_color) || !pager_use_color)\n> +\t\treturn;\n> +\n> +\t/* Disable groff colors */\n> +\tsetenv(\"GROFF_NO_SGR\", \"1\", 0);\n> +\n> +\t/* Bold */\n> +\tsetenv(\"LESS_TERMCAP_md\", GIT_COLOR_BOLD_RED, 0);\n> +\tsetenv(\"LESS_TERMCAP_me\", GIT_COLOR_RESET, 0);\n> +\n> +\t/* Underline */\n> +\tsetenv(\"LESS_TERMCAP_us\", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0);\n> +\tsetenv(\"LESS_TERMCAP_ue\", GIT_COLOR_RESET, 0);\n> +\n> +\t/* Standout */\n> +\tsetenv(\"LESS_TERMCAP_so\", GIT_COLOR_MAGENTA GIT_COLOR_REVERSE, 0);\n> +\tsetenv(\"LESS_TERMCAP_se\", GIT_COLOR_RESET, 0);\n> +}\n\nThis seems very specific to use of \"less\" and hopefully does not do\nanything (bad) when a different pager is used by \"man\".\n\n - Would it help readers to somehow tell that color.man does not\n   apply at all to those whose \"man\" does not \"less\" in the\n   documentation?\n\n - What does it mean to set this variable to \"always\"?  For commands\n   that we control how the various pieces of output are colored (or\n   not), e.g.\n\n   $ git -c color.ui=always log -1 -p >git-log-output.txt\n\n   it is obvious what \"always\" means, but given the implementation\n   that tweaks how \"less\" should behave, a similar command (below)\n   would not colorize its output like the \"git log\" example above\n   does, would it?\n\n   $ git -c color.man=always help -m git >git-help-text.txt\n\nI am just wondering if we are better off not to mention \"always\" in\nthe documentation patch above.  It seems more like that the\nconfiguration variable is to answer this question and nothing else:\n\n    when 'git help' shows manual pages and internally uses 'less' as\n    its pager, do we tell it to colorize the output?\n\nfor which sensible answers are 'true' or 'false'.  For that matter,\nit is not clear what \"auto\" ought to mean, either.\n\nThanks.\n"},{"id":"424902","messageId":"60a429526d3f7_2c1020870@natae.notmuch","threadId":"55723","inReplyTo":"xmqqa6os2j05.fsf@gitster.g","subject":"Re: [PATCH v2] help: colorize man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-18T20:53:38Z","receivedAt":"2021-05-18T20:53:42Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> This seems very specific to use of \"less\" and hopefully does not do\n> anything (bad) when a different pager is used by \"man\".\n> \n>  - Would it help readers to somehow tell that color.man does not\n>    apply at all to those whose \"man\" does not \"less\" in the\n>    documentation?\n\nIndeed it would. Done.\n\n>  - What does it mean to set this variable to \"always\"?  For commands\n>    that we control how the various pieces of output are colored (or\n>    not), e.g.\n> \n>    $ git -c color.ui=always log -1 -p >git-log-output.txt\n> \n>    it is obvious what \"always\" means, but given the implementation\n>    that tweaks how \"less\" should behave, a similar command (below)\n>    would not colorize its output like the \"git log\" example above\n>    does, would it?\n> \n>    $ git -c color.man=always help -m git >git-help-text.txt\n> \n> I am just wondering if we are better off not to mention \"always\" in\n> the documentation patch above.  It seems more like that the\n> configuration variable is to answer this question and nothing else:\n> \n>     when 'git help' shows manual pages and internally uses 'less' as\n>     its pager, do we tell it to colorize the output?\n> \n> for which sensible answers are 'true' or 'false'.  For that matter,\n> it is not clear what \"auto\" ought to mean, either.\n\nTrue. The user most likely is not going to run 'git help $x > output'.\n\nInitially I was making color.man a boolean, but stopped when I found\ncolor.pager. Since Jeff said to use want_color() in the same way all the\nother color.* configurations, I forgot, and used a colorbool.\n\nI've returned back to a bool, and updated the documentation.\n\ncolor.ui=auto is still respected (if stdout is a tty color is disabled),\nbut it doesn't really matter because less seems to be smart and disable\ncolor anyway.\n\nv3 sent.\n\nCheers.\n\n-- \nFelipe Contreras\n"}]}