From e1ff780485ca9ff0d2db3cd716b63557fc6ae5e5 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Sun, 29 Mar 2020 11:13:27 +0200
Subject: [PATCH] Document color support

Add a documentation appendix that explains the PG_COLOR and PG_COLORS
environment variables.

Discussion: https://www.postgresql.org/message-id/flat/bbdcce43-bd2e-5599-641b-9b44b9e0add4@2ndquadrant.com
---
 doc/src/sgml/color.sgml    | 101 +++++++++++++++++++++++++++++++++++++
 doc/src/sgml/filelist.sgml |   1 +
 doc/src/sgml/postgres.sgml |   1 +
 3 files changed, 103 insertions(+)
 create mode 100644 doc/src/sgml/color.sgml

diff --git a/doc/src/sgml/color.sgml b/doc/src/sgml/color.sgml
new file mode 100644
index 0000000000..a01a0c778f
--- /dev/null
+++ b/doc/src/sgml/color.sgml
@@ -0,0 +1,101 @@
+<!-- doc/src/sgml/color.sgml -->
+
+<appendix id="color">
+ <title>Color Support</title>
+
+ <indexterm zone="color">
+  <primary>color</primary>
+ </indexterm>
+
+ <para>
+  Most programs in the PostgreSQL package can produce colorized console
+  output.  This appendix describes how that is configured.
+ </para>
+
+ <sect1 id="color-when">
+  <title>When Color is Used</title>
+
+  <para>
+   To use colorized output, set the environment variable
+   <envar>PG_COLOR</envar><indexterm><primary>PG_COLOR</primary></indexterm>
+   as follows:
+
+   <orderedlist>
+    <listitem>
+     <para>
+      If the value is <literal>always</literal>, then color is used.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      If the value is <literal>auto</literal> and the standard error stream
+      is associated with a terminal device, then color is used.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Otherwise, color is not used.
+     </para>
+    </listitem>
+   </orderedlist>
+  </para>
+ </sect1>
+
+ <sect1 id="color-which">
+  <title>Configuring the Colors</title>
+
+  <para>
+   The actual colors to be used are configured using the environment variable
+   <envar>PG_COLORS</envar><indexterm><primary>PG_COLORS</primary></indexterm>
+   (note plural).  The value is a colon-separated list of
+   <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
+   pairs.  The keys specify what the color is to be used for.  The values are
+   SGR (Select Graphic Rendition) specifications, which are interpreted by the
+   terminal.
+  </para>
+
+  <para>
+   The following keys are currently in use:
+   <variablelist>
+    <varlistentry>
+     <term><literal>error</literal></term>
+     <listitem>
+      <para>used to highlight the text <quote>error</quote> in error messages</para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>warning</literal></term>
+     <listitem>
+      <para>used to highlight the text <quote>warning</quote> in warning
+      messages</para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>locus</literal></term>
+     <listitem>
+      <para>used to highlight location information (e.g., program name and
+      file name) in messages</para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+  <para>
+   The default value is <literal>error=01;31:warning=01;35:locus=01</literal>
+   (<literal>01;31</literal> = bold red, <literal>01;35</literal> = bold
+   magenta, <literal>01</literal> = bold default color).
+  </para>
+
+  <tip>
+   <para>
+    This color specification format is also used by other software packages
+    such as <productname>GCC</productname>, <productname>GNU
+    coreutils</productname>, and <productname>GNU grep</productname>.
+   </para>
+  </tip>
+ </sect1>
+</appendix>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea9..1043d0f7ab 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
 
 <!ENTITY limits     SYSTEM "limits.sgml">
 <!ENTITY acronyms   SYSTEM "acronyms.sgml">
+<!ENTITY color      SYSTEM "color.sgml">
 
 <!ENTITY features-supported   SYSTEM "features-supported.sgml">
 <!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..1f7bd32878 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
   &docguide;
   &limits;
   &acronyms;
+  &color;
 
  </part>