Add "header" to GHC_COLORS

Add "header" to GHC_COLORS and allow colors to be inherited from the
surroundings.

Test Plan: validate

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13718

Differential Revision: https://phabricator.haskell.org/D3599

1 files changed, 19 insertions, 3 deletions

diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index fc19dfd566..84dae9fd0b 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -804,14 +804,30 @@ messages and in GHCi:
 
     .. code-block:: none
 
-        message=1:warning=1;35:error=1;31:fatal=1;31:margin=1;34
+        header=:message=1:warning=1;35:error=1;31:fatal=1;31:margin=1;34
 
     Each value is expected to be a `Select Graphic Rendition (SGR) substring
-    <https://en.wikipedia.org/wiki/ANSI_escape_code#graphics>`_.
+    <https://en.wikipedia.org/wiki/ANSI_escape_code#graphics>`_.  The
+    formatting of each element can inherit from parent elements.  For example,
+    if ``header`` is left empty, it will inherit the formatting of
+    ``message``.  Alternatively if ``header`` is set to ``1`` (bold), it will
+    be bolded but still inherits the color of ``message``.
+
+    Currently, in the primary message, the following inheritance tree is in
+    place:
+
+    - ``message``
+      - ``header``
+        - ``warning``
+        - ``error``
+        - ``fatal``
+
+    In the caret diagnostics, there is currently no inheritance at all between
+    ``margin``, ``warning``, ``error``, and ``fatal``.
 
     The environment variable can also be set to the magical values ``never``
     or ``always``, which is equivalent to setting the corresponding
-    ``-fdiagnostics-color`` flag but has lower precedence.
+    ``-fdiagnostics-color`` flag but with lower precedence.
 
 .. ghc-flag:: -f[no-]diagnostics-show-caret