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

diff --git a/doc/src/sgml/color.sgml b/doc/src/sgml/color.sgml
new file mode 100644 (file)
index 0000000..a01a0c7
--- /dev/null
+++ b/doc/src/sgml/color.sgml
@@ -0,0 +1,101 @@
+
+
+
+ Color Support
+
+ 
+  color
+ 
+
+ 
+  Most programs in the PostgreSQL package can produce colorized console
+  output.  This appendix describes how that is configured.
+ 
+
+ 
+  When Color is Used
+
+  
+   To use colorized output, set the environment variable
+   PG_COLORPG_COLOR
+   as follows:
+
+   
+    
+     
+      If the value is always, then color is used.
+     
+    
+
+    
+     
+      If the value is auto and the standard error stream
+      is associated with a terminal device, then color is used.
+     
+    
+
+    
+     
+      Otherwise, color is not used.
+     
+    
+   
+  
+ 
+
+ 
+  Configuring the Colors
+
+  
+   The actual colors to be used are configured using the environment variable
+   PG_COLORSPG_COLORS
+   (note plural).  The value is a colon-separated list of
+   key=value
+   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.
+  
+
+  
+   The following keys are currently in use:
+   
+    
+     error
+     
+      used to highlight the text error in error messages
+     
+    
+
+    
+     warning
+     
+      used to highlight the text warning in warning
+      messages
+     
+    
+
+    
+     locus
+     
+      used to highlight location information (e.g., program name and
+      file name) in messages
+     
+    
+   
+  
+
+  
+   The default value is error=01;31:warning=01;35:locus=01
+   (01;31 = bold red, 01;35 = bold
+   magenta, 01 = bold default color).
+  
+
+  
+   
+    This color specification format is also used by other software packages
+    such as GCC, GNU
+    coreutils, and GNU grep.
+   
+  
+ 
+

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea971cf129fb0608730e095f12c831aaa..1043d0f7ab9efa9b4d7bad9017fb91f1f9b2f63c 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
 
 
 
+
 
 
 

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba79975d1538ca6333b4728c4b2043d4ea0e..1f7bd3287848292ee9326d5483b1291af7495621 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
   &docguide;
   &limits;
   &acronyms;
+  &color;