man: document that separate /usr/local/ must not be used for config

Since we document /usr/local/lib/systemd/ and other paths for various things,
add notes that this is not supported if /usr/local is a separate partition. In
systemd.unit, I tried to add the footnote in the table where
/usr/local/lib/systemd/ is listed, but that get's rendered as '[sup]a[/sup]'
with a mangled footnote at the bottom of the table :( .

Also, split paragraphs in one place where the subject changes without any
transition.

Follow-up for 02f35b1.
Replaces systemd/systemd#33231.

Author: keszybz

man/standard-conf.xml

@@ -7,7 +7,7 @@
   Copyright © 2014 Josh Triplett
 -->
 
-<refentry>
+<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
   <refnamediv>
     <refname/>
     <refpurpose/>
@@ -32,13 +32,16 @@
     that is ordered later).</para>
 
     <para>Packages should install their configuration files in <filename>/usr/lib/</filename> (distribution
-    packages) or <filename>/usr/local/lib/</filename> (local installs). 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. It is recommended to prefix all filenames with a two-digit number and a
-    dash, to simplify the ordering of the files. It is recommended to use the range 10-40 for configuration
-    files in <filename>/usr/</filename> and the range 60-90 for configuration files in
-    <filename>/etc/</filename> and <filename>/run/</filename>, to make sure that local and transient
-    configuration files will always take priority over configuration files shipped by the OS vendor.</para>
+    packages) or <filename>/usr/local/lib/</filename> (local installs)
+    <xi:include xpointer="usr-local-footnote" />.
+    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.</para>
+
+    <para>It is recommended to prefix all filenames with a two-digit number and a dash to simplify the
+    ordering. It is recommended to use the range 10-40 for configuration files in <filename>/usr/</filename>
+    and the range 60-90 for configuration files in <filename>/etc/</filename> and <filename>/run/</filename>,
+    to make sure that local and transient configuration files will always take priority over configuration
+    files shipped by the OS vendor.</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
@@ -54,7 +57,7 @@
     listed directories in order of priority, only the first file found is used:
     <filename>/etc/systemd/</filename>,
     <filename>/run/systemd/</filename>,
-    <filename>/usr/local/lib/systemd/</filename>,
+    <filename>/usr/local/lib/systemd/</filename> <xi:include xpointer="usr-local-footnote" />,
     <filename>/usr/lib/systemd/</filename>.
     The vendor version of the file contains commented out entries showing the defaults as a guide to the
     administrator. Local overrides can also be created by creating drop-ins, as described below. The main
@@ -76,15 +79,28 @@
     who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to
     be used to override package drop-ins, since the main configuration file has lower precedence. It is
     recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to
-    simplify the ordering of the files. This also defines a concept of drop-in priorities to allow
-    OS vendors to ship drop-ins within a specific range lower than the range used by users. This should
-    lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended
-    to use the range 10-40 for drop-ins in <filename>/usr/</filename> and the range 60-90 for drop-ins in
+    simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship
+    drop-ins within a specific range lower than the range used by users. This should lower the risk of
+    package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range
+    10-40 for drop-ins in <filename>/usr/</filename> and the range 60-90 for drop-ins in
     <filename>/etc/</filename> and <filename>/run/</filename>, to make sure that local and transient drop-ins
     take priority over drop-ins shipped by the OS vendor.</para>
 
     <para>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>
   </refsect1>
+
+  <refsect1>
+    <title>Extras</title>
+
+    <para><filename>/usr/local/lib/systemd</filename>
+    <footnote id='usr-local-footnote'>
+      <para>💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
+      <filename>/usr/local/</filename> is a separate partition, it may not be available during early boot,
+      and must not be used for configuration.</para>
+    </footnote>
+    </para>
+  </refsect1>
+
 </refentry>

man/systemd.environment-generator.xml

@@ -61,11 +61,12 @@
     above. System and user environment generators are loaded from directories with names ending in
     <filename>system-environment-generators/</filename> and
     <filename>user-environment-generators/</filename>, respectively. Generators found in directories
-    listed earlier override the ones with the same name in directories lower in the list. A symlink
-    to <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby
-    preventing it from running. Please note that the order of the two directories with the highest
-    priority is reversed with respect to the unit load path, and generators in
-    <filename>/run/</filename> overwrite those in <filename>/etc/</filename>.</para>
+    listed earlier override the ones with the same name in directories lower in the list
+    <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
+    A symlink to <filename>/dev/null</filename> or an empty file can be used to mask a generator,
+    thereby preventing it from running. Please note that the order of the two directories with the highest
+    priority is reversed with respect to the unit load path, and generators in <filename>/run/</filename>
+    overwrite those in <filename>/etc/</filename>.</para>
 
     <para>After installing new generators or updating the configuration, <command>systemctl
     daemon-reload</command> may be executed. This will re-run all generators, updating environment

man/systemd.generator.xml

@@ -77,10 +77,11 @@
     and user generators are loaded from directories with names ending in
     <filename>system-generators/</filename> and <filename>user-generators/</filename>,
     respectively. Generators found in directories listed earlier override the ones with the same name in
-    directories lower in the list. A symlink to <filename>/dev/null</filename> or an empty file can be used
-    to mask a generator, thereby preventing it from running. Please note that the order of the two
-    directories with the highest priority is reversed with respect to the unit load path, and generators in
-    <filename>/run/</filename> overwrite those in <filename>/etc/</filename>.</para>
+    directories lower in the list <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
+    A symlink to <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby
+    preventing it from running. Please note that the order of the two directories with the highest priority
+    is reversed with respect to the unit load path, and generators in <filename>/run/</filename> overwrite
+    those in <filename>/etc/</filename>.</para>
 
     <para>After installing new generators or updating the configuration, <command>systemctl
     daemon-reload</command> may be executed. This will delete the previous configuration created by

man/systemd.link.xml

@@ -35,7 +35,9 @@
 
     <para>The <filename>.link</filename> files are read from the files located in the system network
     directory <filename>/usr/lib/systemd/network</filename> and
-    <filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory
+    <filename>/usr/local/lib/systemd/network</filename>
+    <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />,
+    the volatile runtime network directory
     <filename>/run/systemd/network</filename>, and the local administration network directory
     <filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
     processed in alphanumeric order, regardless of the directories in which they live. However, files

man/systemd.network.xml

@@ -39,13 +39,14 @@
 
     <para>The <filename>.network</filename> files are read from the files located in the system network
     directories <filename>/usr/lib/systemd/network</filename> and
-    <filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory
-    <filename>/run/systemd/network</filename> and the local administration network directory
-    <filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
-    processed in alphanumeric order, regardless of the directories in which they live. However, files
-    with identical filenames replace each other. It is recommended that each filename is prefixed with
-    a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>). Otherwise, the
-    default <filename>.network</filename> files or those generated by
+    <filename>/usr/local/lib/systemd/network</filename>
+    <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />,
+    the volatile runtime network directory <filename>/run/systemd/network</filename> and the local
+    administration network directory <filename>/etc/systemd/network</filename>. All configuration files are
+    collectively sorted and processed in alphanumeric order, regardless of the directories in which they
+    live. However, files with identical filenames replace each other. It is recommended that each filename is
+    prefixed with a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>).
+    Otherwise, the default <filename>.network</filename> files or those generated by
     <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     may take precedence over user configured files. Files in <filename>/etc/</filename> have the highest
     priority, files in <filename>/run/</filename> take precedence over files with the same name under

man/systemd.unit.xml

@@ -353,7 +353,9 @@
     <para>Unit files are loaded from a set of paths determined during
     compilation, described in the two tables below. Unit files found
     in directories listed earlier override files with the same name in
-    directories lower in the list.</para>
+    directories lower in the list
+    <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
+    </para>
 
     <para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set,
     the contents of this variable overrides the unit load path. If
@@ -407,7 +409,7 @@
           </row>
           <row>
             <entry><filename>/usr/local/lib/systemd/system</filename></entry>
-            <entry>System units installed by the administrator </entry>
+            <entry>System units installed by the administrator</entry>
           </row>
           <row>
             <entry><filename>/usr/lib/systemd/system</filename></entry>
@@ -2687,5 +2689,4 @@ OnFailure=failure-handler@%N.service
       <member><citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
-
 </refentry>