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: v258-rc1~630^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b6b78170e17727ca0ec320d5703b36d0597d0cc9;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.
---

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'>