From bc478a0a85bc8660bfa251866f85c673e4be84ac Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 12 May 2023 16:11:14 -0400
Subject: Tighten usage of PSQL_WATCH_PAGER.

Don't use PSQL_WATCH_PAGER when stdin/stdout are not a terminal.
This corresponds to the restrictions on when other commands will
use [PSQL_]PAGER.  There isn't a lot of sense in trying to use a
pager in non-interactive cases, and doing so allows an environment
setting to break our tests.

Also, ignore PSQL_WATCH_PAGER if it is set but empty or all-blank,
for the same reasons we ignore such settings of [PSQL_]PAGER (see
commit 18f8f784c).

No documentation change is really needed, since there is nothing
suggesting that these constraints on [PSQL_]PAGER didn't already
apply to PSQL_WATCH_PAGER too.  But I rearranged the text
a little to make it read more naturally (IMHO anyway).

Per report from Pavel Stehule.  Back-patch to v15 where
PSQL_WATCH_PAGER was introduced.

Discussion: https://postgr.es/m/CAFj8pRDTwFzmEWdA-gdAcUh0ZnxUioSfTMre71WyB_wNJy-8gw@mail.gmail.com
---
 doc/src/sgml/ref/psql-ref.sgml | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 36a1ba46d5b..dceb8cdfd43 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3039,8 +3039,21 @@ lo_import 152801
           <listitem>
           <para>
           Controls use of a pager program for query and <application>psql</application>
-          help output.  If the environment variable <envar>PSQL_PAGER</envar>
-          or <envar>PAGER</envar> is set, the output is piped to the
+          help output.
+          When the <literal>pager</literal> option is <literal>off</literal>, the pager
+          program is not used. When the <literal>pager</literal> option is
+          <literal>on</literal>, the pager is used when appropriate, i.e., when the
+          output is to a terminal and will not fit on the screen.
+          The <literal>pager</literal> option can also be set to <literal>always</literal>,
+          which causes the pager to be used for all terminal output regardless
+          of whether it fits on the screen.  <literal>\pset pager</literal>
+          without a <replaceable class="parameter">value</replaceable>
+          toggles pager use on and off.
+          </para>
+
+          <para>
+          If the environment variable <envar>PSQL_PAGER</envar>
+          or <envar>PAGER</envar> is set, output to be paged is piped to the
           specified program.  Otherwise a platform-dependent default program
           (such as <filename>more</filename>) is used.
           </para>
@@ -3054,18 +3067,6 @@ lo_import 152801
           <application>psql</application>'s output format (such as
           <filename>pspg --stream</filename>).
           </para>
-
-          <para>
-          When the <literal>pager</literal> option is <literal>off</literal>, the pager
-          program is not used. When the <literal>pager</literal> option is
-          <literal>on</literal>, the pager is used when appropriate, i.e., when the
-          output is to a terminal and will not fit on the screen.
-          The <literal>pager</literal> option can also be set to <literal>always</literal>,
-          which causes the pager to be used for all terminal output regardless
-          of whether it fits on the screen.  <literal>\pset pager</literal>
-          without a <replaceable class="parameter">value</replaceable>
-          toggles pager use on and off.
-          </para>
           </listitem>
           </varlistentry>
 
@@ -4775,7 +4776,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
       pager-related options of the <command>\pset</command> command.
       These variables are examined in the order listed;
       the first that is set is used.
-      If none of them is set, the default is to use <literal>more</literal> on most
+      If neither of them is set, the default is to use <literal>more</literal> on most
       platforms, but <literal>less</literal> on Cygwin.
      </para>
 
-- 
cgit v1.2.3