[PATCH 1/6] diagnostics: use hyperlinks to point to the only documentation

[Akim Demaille]

* src/complain.c (begin_hyperlink, end_hyperlink): New.
(warnings_print_categories): Use them.
* tests/local.at (AT_SET_ENV): Disable hyperlinks in the tests, they
contain random id's, and brackets (which is not so nice for M4).
---
 src/complain.c       | 38 +++++++++++++++++++++++++++++++++++---
 tests/diagnostics.at |  4 ++--
 tests/local.at       |  2 +-
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/src/complain.c b/src/complain.c
index 889f0ae6..b17b8e60 100644
--- a/src/complain.c
+++ b/src/complain.c
@@ -35,6 +35,13 @@
 #include "getargs.h"
 #include "quote.h"
 
+// The URL of the manual page about diagnostics.  Use the per-node
+// manual, to avoid downloading repeatedly the whole manual over the
+// Internet.
+static const char *diagnostics_url
+  = "https://www.gnu.org/software/bison/manual/html_node/Diagnostics.html";;
+
+
 err_status complaint_status = status_none;
 
 bool warnings_are_errors = false;
@@ -96,6 +103,20 @@ end_use_class (const char *s, FILE *out)
     }
 }
 
+static void
+begin_hyperlink (FILE *out, const char *ref)
+{
+  if (out == stderr)
+    styled_ostream_set_hyperlink (errstream, ref, NULL);
+}
+
+static void
+end_hyperlink (FILE *out)
+{
+  if (out == stderr)
+    styled_ostream_set_hyperlink (errstream, NULL, NULL);
+}
+
 void
 flush (FILE *out)
 {
@@ -427,9 +448,20 @@ warnings_print_categories (warnings warn_flags, FILE *out)
         const char* style = severity_style (s);
         fputs (" [", out);
         begin_use_class (style, out);
-        fprintf (out, "-W%s%s",
-                 s == severity_error ? "error=" : "",
-                 argmatch_warning_argument (&w));
+        // E.g., "counterexamples".
+        const char *warning = argmatch_warning_argument (&w);
+        char ref[200];
+        snprintf (ref, sizeof ref,
+                  "%s#W%s", diagnostics_url, warning);
+        begin_hyperlink (out, ref);
+        ostream_printf (errstream,
+                        "-W%s%s",
+                        s == severity_error ? "error=" : "",
+                        warning);
+        end_hyperlink (out);
+        // Because we mix stdio with ostream I/O, we need to flush
+        // here for sake of color == debug.
+        flush (out);
         end_use_class (style, out);
         fputc (']', out);
         /* Display only the first match, the second is "-Wall".  */
diff --git a/tests/diagnostics.at b/tests/diagnostics.at
index 75202e10..61803c44 100644
--- a/tests/diagnostics.at
+++ b/tests/diagnostics.at
@@ -51,7 +51,7 @@ if $EGREP ['\^M|\\[0-9][0-9][0-9]'] input.y experr 
>/dev/null; then
   AT_PERL_REQUIRE([-pi -e 's{\^M}{\r}g;s{\\(\d{3}|.)}{$v = $[]1; $v =~ 
/\A\d+\z/ ? chr($v) : $v}ge' input.y experr])
 fi
 
-AT_CHECK([LC_ALL="$locale" $5 bison -fcaret --color=debug -Wall,cex input.y], 
[$3], [], [experr])
+AT_CHECK(AT_SET_ENV [LC_ALL="$locale" $5 bison -fcaret --color=debug -Wall,cex 
input.y], [$3], [], [experr])
 
 # When no style, same messages, but without style.
 # Except for the second display of the counterexample,
@@ -68,7 +68,7 @@ AT_PERL_REQUIRE([-pi -e '
 # Cannot use AT_BISON_CHECK easily as we need to change the
 # environment.
 # FIXME: Enhance AT_BISON_CHECK.
-AT_CHECK([LC_ALL="$locale" $5 bison -fcaret -Wall,cex input.y], [$3], [], 
[experr])
+AT_CHECK(AT_SET_ENV [LC_ALL="$locale" $5 bison -fcaret -Wall,cex input.y], 
[$3], [], [experr])
 
 
 AT_BISON_OPTION_POPDEFS
diff --git a/tests/local.at b/tests/local.at
index b94dd407..5465bd85 100644
--- a/tests/local.at
+++ b/tests/local.at
@@ -1199,7 +1199,7 @@ m4_define([AT_BISON_CHECK_XML],
 # The testsuite verbose output, at least, will be incorrect, but nothing may
 # fail to make sure you notice.
 m4_define([AT_SET_ENV_IF],
-[[[COLUMNS=1000; export COLUMNS;]] m4_null_if($1, [], 
[[[VALGRIND_OPTS="$VALGRIND_OPTS --leak-check=summary --show-reachable=no"; 
export VALGRIND_OPTS; ]]])])
+[[[COLUMNS=1000; export COLUMNS; NO_TERM_HYPERLINKS=1; export 
NO_TERM_HYPERLINKS;]] m4_null_if($1, [], [[[VALGRIND_OPTS="$VALGRIND_OPTS 
--leak-check=summary --show-reachable=no"; export VALGRIND_OPTS; ]]])])
 
 
 # AT_SET_ENV
-- 
2.27.0