From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Tue, 6 May 2025 09:37:26 +0000 (+0200)
Subject: man: rework the description of $SYSTEMD_PAGER and $PAGER
X-Git-Tag: v256.14~22
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ab19d19d3e89a270e40b9b9cff845581d3d9e3a4;p=thirdparty%2Fsystemd.git

man: rework the description of $SYSTEMD_PAGER and $PAGER

$PAGER wasn't documented, but actually we treat it same as $SYSTEMD_PAGER,
except for lower priority. And the two variables can be used to disable the
pager, even if $SYSTEMD_PAGERSECURE is not set.

Behaviour is (obviously) not changed by this patch, it intentionally just
updates the docs to match the code.

(cherry picked from commit b6b78170e17727ca0ec320d5703b36d0597d0cc9)
(cherry picked from commit affb45d6b2dfdb3a87da2e0241be8c5c5c9a9d8f)
---

diff --git a/man/common-variables.xml b/man/common-variables.xml
index 9f322dbf230..6a6e98d334d 100644
--- a/man/common-variables.xml
+++ b/man/common-variables.xml
@@ -96,17 +96,22 @@
 
     <varlistentry id='pager'>
       <term><varname>$SYSTEMD_PAGER</varname></term>
+      <term><varname>$PAGER</varname></term>
 
-      <listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides
-      <varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a
-      set of well-known pager implementations are tried in turn, including
-      <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
-      <citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If
-      no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
-      or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para>
+      <listitem><para>Pager to use when <option>--no-pager</option> is not given.
+      <varname>$SYSTEMD_PAGER</varname> is used if set; otherwise <varname>$PAGER</varname> is used.
+      If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a set of well-known
+      pager implementations is tried in turn, including
+      <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      and
+      <citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      until one is found. If no pager implementation is discovered, no pager is invoked. Setting those
+      environment variables to an empty string or the value <literal>cat</literal> is equivalent to passing
+      <option>--no-pager</option>.</para>
 
       <para>Note: if <varname>$SYSTEMD_PAGERSECURE</varname> is not set, <varname>$SYSTEMD_PAGER</varname>
-      (as well as <varname>$PAGER</varname>) will be silently ignored.</para></listitem>
+      and <varname>$PAGER</varname> can only be used to disable the pager (with <literal>cat</literal> or
+      <literal></literal>), and are otherwise ignored.</para></listitem>
     </varlistentry>
 
     <varlistentry id='less'>
@@ -205,8 +210,8 @@
       implement "secure mode" will not be used at all.</para>
 
       <para>Note that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to
-      be honoured, <varname>$SYSTEMD_PAGERSECURE</varname> must be set too.</para>
-      </listitem>
+      be honoured, other than to disable the pager, <varname>$SYSTEMD_PAGERSECURE</varname> must be set
+      too.</para></listitem>
     </varlistentry>
 
     <varlistentry id='colors'>