In psql, use PSQL_PAGER in preference to PAGER, if it's set.

This allows the user's environment to set up a psql-specific choice
of pager, in much the same way that we provide PSQL_EDITOR to allow
a psql-specific override of the more widely known EDITOR variable.

Pavel Stehule, reviewed by Thomas Munro

Discussion: https://postgr.es/m/CAFj8pRD3RRk9S1eRbnGm_T6brc3Ss5mohraNzTSJquzx+pmtKA@mail.gmail.com

doc/src/sgml/ref/psql-ref.sgml

@@ -2665,10 +2665,10 @@ lo_import 152801
           <listitem>
           <para>
           Controls use of a pager program for query and <application>psql</>
-          help output. If the environment variable <envar>PAGER</envar>
-          is set, the output is piped to the specified program.
-          Otherwise a platform-dependent default (such as
-          <filename>more</filename>) is used.
+          help output.  If the environment variable <envar>PSQL_PAGER</envar>
+          or <envar>PAGER</envar> is set, the output is piped to the
+          specified program.  Otherwise a platform-dependent default program
+          (such as <filename>more</filename>) is used.
           </para>
 
           <para>
@@ -4106,21 +4106,6 @@ $endif
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term><envar>PAGER</envar></term>
-
-    <listitem>
-     <para>
-      If the query results do not fit on the screen, they are piped
-      through this command.  Typical values are
-      <literal>more</literal> or <literal>less</literal>.  The default
-      is platform-dependent.  Use of the pager can be disabled by setting
-      <envar>PAGER</envar> to empty, or by using pager-related options of
-      the <command>\pset</command> command.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term><envar>PGDATABASE</envar></term>
     <term><envar>PGHOST</envar></term>
@@ -4145,11 +4130,8 @@ $endif
       and <command>\ev</command> commands.
       These variables are examined in the order listed;
       the first that is set is used.
-     </para>
-
-     <para>
-      The built-in default editors are <filename>vi</filename> on Unix
-      systems and <filename>notepad.exe</filename> on Windows systems.
+      If none of them is set, the default is to use <filename>vi</filename>
+      on Unix systems or <filename>notepad.exe</filename> on Windows systems.
      </para>
     </listitem>
    </varlistentry>
@@ -4192,6 +4174,27 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><envar>PSQL_PAGER</envar></term>
+    <term><envar>PAGER</envar></term>
+
+    <listitem>
+     <para>
+      If a query's results do not fit on the screen, they are piped
+      through this command. Typical values are <literal>more</literal>
+      or <literal>less</literal>.
+      Use of the pager can be disabled by setting <envar>PSQL_PAGER</envar>
+      or <envar>PAGER</envar> to an empty string, or by adjusting the
+      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</> on most
+      platforms, but <literal>less</> on Cygwin.
+     </para>
+
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><envar>PSQLRC</envar></term>
 

src/bin/psql/help.c

@@ -459,8 +459,6 @@ helpVariables(unsigned short int pager)
 
 	fprintf(output, _("  COLUMNS\n"
 					  "    number of columns for wrapped format\n"));
-	fprintf(output, _("  PAGER\n"
-					  "    name of external pager program\n"));
 	fprintf(output, _("  PGAPPNAME\n"
 					  "    same as the application_name connection parameter\n"));
 	fprintf(output, _("  PGDATABASE\n"
@@ -481,6 +479,8 @@ helpVariables(unsigned short int pager)
 					  "    how to specify a line number when invoking the editor\n"));
 	fprintf(output, _("  PSQL_HISTORY\n"
 					  "    alternative location for the command history file\n"));
+	fprintf(output, _("  PSQL_PAGER, PAGER\n"
+					  "    name of external pager program\n"));
 	fprintf(output, _("  PSQLRC\n"
 					  "    alternative location for the user's .psqlrc file\n"));
 	fprintf(output, _("  SHELL\n"

src/fe_utils/print.c

@@ -2870,7 +2870,9 @@ PageOutput(int lines, const printTableOpt *topt)
 			const char *pagerprog;
 			FILE	   *pagerpipe;
 
-			pagerprog = getenv("PAGER");
+			pagerprog = getenv("PSQL_PAGER");
+			if (!pagerprog)
+				pagerprog = getenv("PAGER");
 			if (!pagerprog)
 				pagerprog = DEFAULT_PAGER;
 			else

src/interfaces/libpq/fe-print.c

@@ -165,6 +165,13 @@ PQprint(FILE *fout, const PGresult *res, const PQprintOpt *po)
 			screen_size.ws_row = 24;
 			screen_size.ws_col = 80;
 #endif
+
+			/*
+			 * Since this function is no longer used by psql, we don't examine
+			 * PSQL_PAGER.  It's possible that the hypothetical external users
+			 * of the function would like that to happen, but in the name of
+			 * backwards compatibility, we'll stick to just examining PAGER.
+			 */
 			pagerenv = getenv("PAGER");
 			/* if PAGER is unset, empty or all-white-space, don't use pager */
 			if (pagerenv != NULL &&