From 02e95a5049f7933cbde1dacf401604ea3fc02aa5 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 5 Jul 2019 12:32:36 -0400
Subject: Add \warn command to psql.

This is like \echo except that the text is sent to stderr not stdout.

In passing, fix a pre-existing bug in \echo and \qecho: per documentation
the -n switch should only be recognized when it is the first argument,
but actually any argument matching "-n" was treated as a switch.
(Should we back-patch that?)

David Fetter (bug fix by me), reviewed by Fabien Coelho

Discussion: https://postgr.es/m/20190421183115.GA4311@fetter.org
---
 doc/src/sgml/ref/psql-ref.sgml | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 3cd0a99d079..7789fc61776 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1863,22 +1863,22 @@ testdb=&gt;
         <term><literal>\echo <replaceable class="parameter">text</replaceable> [ ... ]</literal></term>
         <listitem>
         <para>
-        Prints the arguments to the standard output, separated by one
-        space and followed by a newline. This can be useful to
+        Prints the evaluated arguments to standard output, separated by
+        spaces and followed by a newline. This can be useful to
         intersperse information in the output of scripts. For example:
 <programlisting>
 =&gt; <userinput>\echo `date`</userinput>
 Tue Oct 26 21:40:57 CEST 1999
 </programlisting>
         If the first argument is an unquoted <literal>-n</literal> the trailing
-        newline is not written.
+        newline is not written (nor is the first argument).
         </para>
 
         <tip>
         <para>
         If you use the <command>\o</command> command to redirect your
         query output you might wish to use <command>\qecho</command>
-        instead of this command.
+        instead of this command.  See also <command>\warn</command>.
         </para>
         </tip>
         </listitem>
@@ -3226,6 +3226,18 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
       </varlistentry>
 
 
+      <varlistentry>
+        <term><literal>\warn <replaceable class="parameter">text</replaceable> [ ... ]</literal></term>
+        <listitem>
+        <para>
+        This command is identical to <command>\echo</command> except
+        that the output will be written to <application>psql</application>'s
+        standard error channel, rather than standard output.
+        </para>
+        </listitem>
+      </varlistentry>
+
+
       <varlistentry>
         <term><literal>\watch [ <replaceable class="parameter">seconds</replaceable> ]</literal></term>
         <listitem>
-- 
cgit v1.2.3