On 2020-03-23 06:04, Michael Paquier wrote:
On Fri, Mar 20, 2020 at 11:22:07PM -0400, Bruce Momjian wrote:
On Fri, Mar 20, 2020 at 11:15:07PM -0400, Tom Lane wrote:
Yeah, but the point is precisely that pg_logging_init()
also responds to PG_COLORS, which is not documented anywhere.
Oh, I thought it was a typo. OK, so it still an open item.
Yes, I really think that we should have a new section in the docs for
that with more meaningful examples rather than copy-paste that stuff
across more pages of the docs. Note that 5aaa584 has plugged all the
holes related to PG_COLOR I could find, and that pg_ctl and pg_upgrade
initialize logging with pg_logging_init() but these two cannot use
coloring because they have their own idea of what logging should be.
I'm giving up on making color the default, since there is clearly no
consensus.
Attached is the documentation patch reworked.
Should we delete all the repetitive mentions on the man pages?
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>From 7164d4196ace14a1acc9077a7a4d32e57131ff6e Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Mon, 23 Mar 2020 09:22:50 +0100
Subject: [PATCH v2] Document color support
Add a documentation appendix that explains the PG_COLOR and PG_COLORS
environment variables.
---
doc/src/sgml/color.sgml | 71 ++++++++++++++++++++++++++++++++++++++
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 73 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..c30b1942a5
--- /dev/null
+++ b/doc/src/sgml/color.sgml
@@ -0,0 +1,71 @@
+<!-- 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 default value is <literal>error=01;31:warning=01;35:locus=01</literal>.
+ </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 @@ <title>Appendixes</title>
&docguide;
&limits;
&acronyms;
+ &color;
</part>
--
2.25.0
