man: Factor out a common snippet for .d directories and precedence

Several manpages contain duplicate text describing a standard set of .d
configuration directories, with the usual sorting, precedence,
overrides, and so on.  Factor this common text out using XInclude before
proliferating it even further.

6 files changed, 68 insertions, 120 deletions

diff --git a/man/binfmt.d.xml b/man/binfmt.d.xml
index 227016616a..55a3df0b73 100644
--- a/man/binfmt.d.xml
+++ b/man/binfmt.d.xml
@@ -19,7 +19,8 @@
   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
-<refentry id="binfmt.d" conditional='ENABLE_BINFMT'>
+<refentry id="binfmt.d" conditional='ENABLE_BINFMT'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
         <refentryinfo>
                 <title>binfmt.d</title>
@@ -74,33 +75,10 @@
                 <para>Empty lines and lines beginning with ; and # are
                 ignored. Note that this means you may not use ; and #
                 as delimiter in binary format rules.</para>
-
-                <para>Each configuration file shall be named in the
-                style of <filename><replaceable>program</replaceable>.conf</filename>.
-                Files in <filename>/etc/</filename> override files
-                with the same name in <filename>/usr/lib/</filename>
-                and <filename>/run/</filename>. Files in
-                <filename>/run/</filename> override files with the
-                same name in <filename>/usr/lib/</filename>. Packages
-                should install their configuration files in
-                <filename>/usr/lib/</filename>, files in
-                <filename>/etc/</filename> are reserved for the local
-                administrator, who may use this logic to override the
-                configuration files installed from vendor
-                packages. All files are sorted by their filename in
-                lexicographic order, regardless of which of the
-                directories they reside in. If multiple files specify
-                the same binary type name, the entry in the file with
-                the lexicographically latest name will be applied.</para>
-
-                <para>If the administrator wants to disable a
-                configuration file supplied by the vendor, the
-                recommended way is to place a symlink to
-                <filename>/dev/null</filename> in
-                <filename>/etc/binfmt.d/</filename> bearing the
-                same filename.</para>
         </refsect1>
 
+        <xi:include href="standard-conf.xml" xpointer="confd" />
+
         <refsect1>
                 <title>Example</title>
                 <example>
diff --git a/man/logind.conf.xml b/man/logind.conf.xml
index ca7525f31a..e927cf4451 100644
--- a/man/logind.conf.xml
+++ b/man/logind.conf.xml
@@ -22,7 +22,8 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="logind.conf" conditional='ENABLE_LOGIND'>
+<refentry id="logind.conf" conditional='ENABLE_LOGIND'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
         <refentryinfo>
                 <title>logind.conf</title>
                 <productname>systemd</productname>
@@ -59,29 +60,11 @@
                 <title>Description</title>
 
                 <para>These files configure various parameters of the systemd login manager, <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
-
-                <para>Each configuration file shall be named in the style of
-                <filename><replaceable>filename</replaceable>.conf</filename>.
-                Files in <filename>/etc/</filename> override files with the
-                same name in <filename>/usr/lib/</filename> and
-                <filename>/run/</filename>.  Files in
-                <filename>/run/</filename> override files with the same name in
-                <filename>/usr/lib/</filename>. Packages should install their
-                configuration files in <filename>/usr/lib/</filename>. Files in
-                <filename>/etc/</filename> are reserved for the local
-                administrator, who may use this logic to override the
-                configuration files installed by vendor packages. All
-                configuration files are sorted by their filename in
-                lexicographic order, regardless of which of the directories
-                they reside in. If multiple files specify the same option, the
-                entry in the file with the lexicographically latest name will
-                be applied; entries in any <filename>logind.conf.d</filename>
-                file override entries in
-                <filename>/etc/systemd/logind.conf</filename>. It is
-                recommended to prefix all filenames with a two-digit number and
-                a dash, to simplify the ordering of the files.</para>
         </refsect1>
 
+        <xi:include href="standard-conf.xml" xpointer="confd" />
+        <xi:include href="standard-conf.xml" xpointer="conf" />
+
         <refsect1>
                 <title>Options</title>
 
diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml
index 33c466f926..4b578d714c 100644
--- a/man/modules-load.d.xml
+++ b/man/modules-load.d.xml
@@ -19,7 +19,8 @@
   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
-<refentry id="modules-load.d" conditional='HAVE_KMOD'>
+<refentry id="modules-load.d" conditional='HAVE_KMOD'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
         <refentryinfo>
                 <title>modules-load.d</title>
@@ -74,29 +75,10 @@
                 list of kernel module names to load, separated by
                 newlines. Empty lines and lines whose first
                 non-whitespace character is # or ; are ignored.</para>
-
-                <para>Each configuration file shall be named in the
-                style of <filename><replaceable>program</replaceable>.conf</filename>.
-                Files in <filename>/etc/</filename> override files
-                with the same name in <filename>/usr/lib/</filename>
-                and <filename>/run/</filename>. Files in
-                <filename>/run/</filename> override files with the
-                same name in <filename>/usr/lib/</filename>. Packages
-                should install their configuration files in
-                <filename>/usr/lib/</filename>, files in
-                <filename>/etc/</filename> are reserved for the local
-                administrator, who may use this logic to override the
-                configuration files installed from vendor
-                packages.</para>
-
-                <para>If the administrator wants to disable a
-                configuration file supplied by the vendor, the
-                recommended way is to place a symlink to
-                <filename>/dev/null</filename> in
-                <filename>/etc/modules-load.d/</filename> bearing the
-                same filename.</para>
         </refsect1>
 
+        <xi:include href="standard-conf.xml" xpointer="confd" />
+
         <refsect1>
                 <title>Example</title>
                 <example>
diff --git a/man/standard-conf.xml b/man/standard-conf.xml
new file mode 100644
index 0000000000..b87d7e955b
--- /dev/null
+++ b/man/standard-conf.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+          "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<refsection>
+  <refsection id='confd'>
+    <title>Configuration Directories and Precedence</title>
+
+    <para>Configuration files are read from directories in
+    <filename>/etc/</filename>, <filename>/run/</filename>, and
+    <filename>/usr/lib/</filename>, in order of precedence.
+    Each configuration file in these configuration directories shall be named in
+    the style of <filename><replaceable>filename</replaceable>.conf</filename>.
+    Files in <filename>/etc/</filename> override files with the same name in
+    <filename>/run/</filename> and <filename>/usr/lib/</filename>. Files in
+    <filename>/run/</filename> override files with the same name in
+    <filename>/usr/lib/</filename>.</para>
+
+    <para>Packages should install their configuration files in
+    <filename>/usr/lib/</filename>. Files in <filename>/etc/</filename> are
+    reserved for the local administrator, who may use this logic to override the
+    configuration files installed by vendor packages. All configuration files
+    are sorted by their filename in lexicographic order, regardless of which of
+    the directories they reside in. If multiple files specify the same option,
+    the entry in the file with the lexicographically latest name will take
+    precedence. It is recommended to prefix all filenames with a two-digit number
+    and a dash, to simplify the ordering of the files.</para>
+
+    <para>If the administrator wants to disable a configuration file supplied by
+    the vendor, the recommended way is to place a symlink to
+    <filename>/dev/null</filename> in the configuration directory in
+    <filename>/etc/</filename>, with the same filename as the vendor
+    configuration file.</para>
+  </refsection>
+
+  <refsection id='conf'>
+    <title>Configuration File</title>
+
+    <para>Configuration is also read from a single configuration file in
+    <filename>/etc/</filename>. This file is read before any of the
+    configuration directories, and has the lowest precedence; entries in a file
+    in any configuration directory override entries in the single configuration
+    file.</para>
+  </refsection>
+</refsection>
diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml
index 922b5c4eaa..c67a199fb5 100644
--- a/man/sysctl.d.xml
+++ b/man/sysctl.d.xml
@@ -18,7 +18,8 @@
   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
-<refentry id="sysctl.d">
+<refentry id="sysctl.d"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
         <refentryinfo>
                 <title>sysctl.d</title>
@@ -70,27 +71,6 @@
                 is <literal>#</literal> or <literal>;</literal> are
                 ignored.</para>
 
-                <para>Each configuration file shall be named in the
-                style of <filename><replaceable>program</replaceable>.conf</filename>.
-                Files in <filename>/etc/</filename> override files
-                with the same name in <filename>/usr/lib/</filename>
-                and <filename>/run/</filename>.  Files in
-                <filename>/run/</filename> override files with the same
-                name in <filename>/usr/lib/</filename>. Packages
-                should install their configuration files in
-                <filename>/usr/lib/</filename>. Files in
-                <filename>/etc/</filename> are reserved for the local
-                administrator, who may use this logic to override the
-                configuration files installed by vendor packages. All
-                configuration files are sorted by their filename in
-                lexicographic order, regardless of which of the
-                directories they reside in. If multiple files specify the
-                same variable name, the entry in the file with the
-                lexicographically latest name will be applied. It is
-                recommended to prefix all filenames with a two-digit
-                number and a dash, to simplify the ordering of the
-                files.</para>
-
                 <para>Note that either <literal>/</literal> or
                 <literal>.</literal> may be used as separators within
                 sysctl variable names. If the first separator is a
@@ -109,13 +89,6 @@
                 <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>.
                 </para>
 
-                <para>If the administrator wants to disable a
-                configuration file supplied by the vendor, the
-                recommended way is to place a symlink to
-                <filename>/dev/null</filename> in
-                <filename>/etc/sysctl.d/</filename> bearing the
-                same filename.</para>
-
                 <para>The settings configured with
                 <filename>sysctl.d</filename> files will be applied
                 early on boot. The network interface-specific options
@@ -142,6 +115,8 @@
                 example below).</para>
         </refsect1>
 
+        <xi:include href="standard-conf.xml" xpointer="confd" />
+
         <refsect1>
                 <title>Examples</title>
                 <example>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index 18c71db63e..ac2db98853 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -19,7 +19,8 @@
   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
-<refentry id="sysusers.d">
+<refentry id="sysusers.d"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
         <refentryinfo>
                 <title>sysusers.d</title>
@@ -239,8 +240,10 @@ u root 0 "Superuser" /root</programlisting>
 
         </refsect1>
 
+        <xi:include href="standard-conf.xml" xpointer="confd" />
+
         <refsect1>
-                <title>Overriding vendor configuration</title>
+                <title>Idempotence</title>
 
                 <para>Note that <command>systemd-sysusers</command>
                 will do nothing if the specified users or groups
@@ -248,31 +251,13 @@ u root 0 "Superuser" /root</programlisting>
                 <filename>sysusers.d</filename> vendor configuration,
                 except to block certain users or groups from being
                 created.</para>
-
-                <para>Files in <filename>/etc/sysusers.d</filename>
-                override files with the same name in
-                <filename>/usr/lib/sysusers.d</filename> and
-                <filename>/run/sysusers.d</filename>. Files in
-                <filename>/run/sysusers.d</filename> override files
-                with the same name in
-                <filename>/usr/lib/sysusers.d</filename>. The scheme is the same as for
-                <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                except for the directory name.</para>
-
-                <para>If the administrator wants to disable a
-                configuration file supplied by the vendor, the
-                recommended way is to place a symlink to
-                <filename>/dev/null</filename> in
-                <filename>/etc/sysusers.d/</filename> bearing the
-                same filename.</para>
         </refsect1>
 
         <refsect1>
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                 </para>
         </refsect1>