[PATCH 1/5] doc: document colorized diagnostics

[Akim Demaille]

* src/getargs.c (argmatch_color_group): New.
(usage): Document --color and --style.
* doc/bison.texi (Bison Options): Split into three subsections.
Document --color and --style.
---
 doc/bison.texi | 54 +++++++++++++++++++++++++++++++++++++++++++-------
 src/getargs.c  | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+), 7 deletions(-)

diff --git a/doc/bison.texi b/doc/bison.texi
index 73c29f65..92254f9f 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -377,6 +377,12 @@ Invoking Bison
 * Option Cross Key::  Alphabetical list of long options.
 * Yacc Library::      Yacc-compatible @code{yylex} and @code{main}.
 
+Bison Options
+
+* Operation Modes::    Options controling the global behavior of 
@command{bison}
+* Tuning the Parser::  Options changing the generated parsers
+* Adjust the Output::  Options controling the output
+
 Parsers Written In Other Languages
 
 * C++ Parsers::                 The interface to generate C++ parser classes
@@ -10290,9 +10296,16 @@ Here is a list of options that can be used with Bison, 
alphabetized by
 short option.  It is followed by a cross key alphabetized by long
 option.
 
+@menu
+* Operation Modes::    Options controling the global behavior of 
@command{bison}
+* Tuning the Parser::  Options changing the generated parsers
+* Adjust the Output::  Options controling the output
+@end menu
+
+@node Operation Modes
+@subsection Operation Modes
+
 @c Please, keep this ordered as in 'bison --help'.
-@noindent
-Operations modes:
 @table @option
 @item -h
 @itemx --help
@@ -10522,9 +10535,34 @@ they are explicitly enabled by 
@option{-Werror=@var{category}}.
 Deactivate the error treatment for this @var{category}. However, the warning
 itself won't be disabled, or enabled, by this option.
 
+@item --color[=@var{when}]
+Control whether diagnostics are colorized, depending on @var{when}:
+@table @code
+@item always
+@itemx yes
+Enable colorized diagnostics.
+
+@item never
+@itemx no
+Disable colorized diagnostics.
+
+@item auto @rm{(default)}
+@itemx tty
+Diagnostics will be colorized if the output device is a tty, i.e. when the
+output goes directly to a text screen or terminal emulator window.
+@end table
+@option{--color} is equivalent to @option{--color=always}.
+
+@item --style=@var{file}
+Specifies the CSS style @var{file} to use when colorizing. It has an effect
+only when the @option{--color} option is effective.  The
+@file{bison-default.css} file provide a good example from which to define
+your own style file.  See the documentation of libtextstyle for more
+details.
+
 @item -f [@var{feature}]
 @itemx --feature[=@var{feature}]
-Activate miscellaneous @var{feature}. @var{feature} can be one of:
+Activate miscellaneous @var{feature}s. @var{Feature} can be one of:
 @table @code
 @item caret
 @itemx diagnostics-show-caret
@@ -10649,9 +10687,10 @@ the output files.
 @end table
 @end table
 
-@noindent
-Tuning the parser:
+@node Tuning the Parser
+@subsection Tuning the Parser
 
+@c Please, keep this ordered as in 'bison --help'.
 @table @option
 @item -t
 @itemx --debug
@@ -10734,9 +10773,10 @@ This is similar to how most shells resolve commands.
 Pretend that @code{%token-table} was specified.  @xref{Decl Summary}.
 @end table
 
-@noindent
-Adjust the output:
+@node Adjust the Output
+@subsection Adjust the Output
 
+@c Please, keep this ordered as in 'bison --help'.
 @table @option
 @item --defines[=@var{file}]
 Pretend that @code{%defines} was specified, i.e., write an extra output
diff --git a/src/getargs.c b/src/getargs.c
index 0e6b1d60..d87241c5 100644
--- a/src/getargs.c
+++ b/src/getargs.c
@@ -154,6 +154,49 @@ flags_argmatch (const char *opt,
                   argmatch_## FlagName ## _usage,                       \
                   All, &FlagName ## _flag, Args)
 
+/*---------------------.
+| --color's handling.  |
+`---------------------*/
+
+enum color
+  {
+    color_always,
+    color_never,
+    color_auto
+  };
+
+ARGMATCH_DEFINE_GROUP(color, enum color);
+
+static const argmatch_color_doc argmatch_color_docs[] =
+{
+  { "always",     N_("colorize the output") },
+  { "never",      N_("don't colorize the output") },
+  { "auto",       N_("colorize if the output device is a tty") },
+  { NULL, NULL },
+};
+
+static const argmatch_color_arg argmatch_color_args[] =
+{
+  { "always",   color_always },
+  { "yes",      color_always },
+  { "never",    color_never },
+  { "no",       color_never },
+  { "auto",     color_auto },
+  { "tty",      color_auto },
+  { NULL, color_always },
+};
+
+const argmatch_color_group_type argmatch_color_group =
+{
+  argmatch_color_args,
+  argmatch_color_docs,
+  /* TRANSLATORS: Use the same translation for WHEN as in the
+     --color=WHEN help message.  */
+  N_("WHEN can be one of the following:"),
+  NULL
+};
+
+
 /*----------------------.
 | --report's handling.  |
 `----------------------*/
@@ -187,6 +230,8 @@ const argmatch_report_group_type argmatch_report_group =
 {
   argmatch_report_args,
   argmatch_report_docs,
+  /* TRANSLATORS: Use the same translation for THINGS as in the
+     --report=THINGS help message.  */
   N_("THINGS is a list of comma separated words that can include:"),
   NULL
 };
@@ -282,6 +327,8 @@ const argmatch_feature_group_type argmatch_feature_group =
 {
   argmatch_feature_args,
   argmatch_feature_docs,
+  /* TRANSLATORS: Use the same translation for FEATURES as in the
+     --feature=FEATURES help message.  */
   N_("FEATURES is a list of comma separated words that can include:"),
   NULL
 };
@@ -331,6 +378,8 @@ Operation modes:\n\
   -u, --update               apply fixes to the source grammar file and exit\n\
   -y, --yacc                 emulate POSIX Yacc\n\
   -W, --warnings[=CATEGORY]  report the warnings falling in CATEGORY\n\
+      --color[=WHEN]         whether to colorize the diagnostics\n\
+      --style=FILE           specify the CSS FILE for colorizer diagnostics\n\
   -f, --feature[=FEATURES]   activate miscellaneous features\n\
 \n\
 "), stdout);
@@ -367,6 +416,9 @@ Output:\n\
 "), stdout);
       putc ('\n', stdout);
 
+      argmatch_color_usage (stdout);
+      putc ('\n', stdout);
+
       warning_usage (stdout);
       putc ('\n', stdout);
 
@@ -600,6 +652,8 @@ getargs_colors (int argc, char *argv[])
           else
             handle_color_option (color);
         }
+      else if (STREQ ("--color", arg))
+        handle_color_option (NULL);
       else if (STRPREFIX_LIT ("--style=", arg))
         {
           const char *style = arg + strlen ("--style=");
-- 
2.22.0