doc/src/sgml/color.sgml

   1 <!-- doc/src/sgml/color.sgml -->
   2
   3 <appendix id="color">
   4  <title>Color Support</title>
   5
   6  <indexterm zone="color">
   7   <primary>color</primary>
   8  </indexterm>
   9
  10  <para>
  11   Most programs in the PostgreSQL package can produce colorized console
  12   output.  This appendix describes how that is configured.
  13  </para>
  14
  15  <sect1 id="color-when">
  16   <title>When Color is Used</title>
  17
  18   <para>
  19    To use colorized output, set the environment variable
  20    <envar>PG_COLOR</envar><indexterm><primary>PG_COLOR</primary></indexterm>
  21    as follows:
  22
  23    <orderedlist>
  24     <listitem>
  25      <para>
  26       If the value is <literal>always</literal>, then color is used.
  27      </para>
  28     </listitem>
  29
  30     <listitem>
  31      <para>
  32       If the value is <literal>auto</literal> and the standard error stream
  33       is associated with a terminal device, then color is used.
  34      </para>
  35     </listitem>
  36
  37     <listitem>
  38      <para>
  39       Otherwise, color is not used.
  40      </para>
  41     </listitem>
  42    </orderedlist>
  43   </para>
  44  </sect1>
  45
  46  <sect1 id="color-which">
  47   <title>Configuring the Colors</title>
  48
  49   <para>
  50    The actual colors to be used are configured using the environment variable
  51    <envar>PG_COLORS</envar><indexterm><primary>PG_COLORS</primary></indexterm>
  52    (note plural).  The value is a colon-separated list of
  53    <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
  54    pairs.  The keys specify what the color is to be used for.  The values are
  55    SGR (Select Graphic Rendition) specifications, which are interpreted by the
  56    terminal.
  57   </para>
  58
  59   <para>
  60    The following keys are currently in use:
  61    <variablelist>
  62     <varlistentry>
  63      <term><literal>error</literal></term>
  64      <listitem>
  65       <para>used to highlight the text <quote>error</quote> in error messages</para>
  66      </listitem>
  67     </varlistentry>
  68
  69     <varlistentry>
  70      <term><literal>warning</literal></term>
  71      <listitem>
  72       <para>used to highlight the text <quote>warning</quote> in warning
  73       messages</para>
  74      </listitem>
  75     </varlistentry>
  76
  77     <varlistentry>
  78      <term><literal>note</literal></term>
  79      <listitem>
  80       <para>used to highlight the text <quote>detail</quote> and
  81       <quote>hint</quote> in such messages</para>
  82      </listitem>
  83     </varlistentry>
  84
  85     <varlistentry>
  86      <term><literal>locus</literal></term>
  87      <listitem>
  88       <para>used to highlight location information (e.g., program name and
  89       file name) in messages</para>
  90      </listitem>
  91     </varlistentry>
  92    </variablelist>
  93   </para>
  94
  95   <para>
  96    The default value is
  97    <literal>error=01;31:warning=01;35:note=01;36:locus=01</literal>
  98    (<literal>01;31</literal> = bold red, <literal>01;35</literal> = bold
  99    magenta, <literal>01;36</literal> = bold cyan, <literal>01</literal> = bold
 100    default color).
 101   </para>
 102
 103   <tip>
 104    <para>
 105     This color specification format is also used by other software packages
 106     such as <productname>GCC</productname>, <productname>GNU
 107     coreutils</productname>, and <productname>GNU grep</productname>.
 108    </para>
 109   </tip>
 110  </sect1>
 111 </appendix>