man: extend Before=/After= documentation a bit

let's clarify what the order actually means for service units.

Fixes: #6097

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 3a3d26e..dedeb6c 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -546,26 +546,29 @@
         <term><varname>Before=</varname></term>
         <term><varname>After=</varname></term>
 
-        <listitem><para>A space-separated list of unit names.  Configures ordering dependencies between units. If a
-        unit <filename>foo.service</filename> contains a setting <option>Before=bar.service</option> and both units are
-        being started, <filename>bar.service</filename>'s start-up is delayed until <filename>foo.service</filename> is
-        started up.  Note that this setting is independent of and orthogonal to the requirement dependencies as
-        configured by <varname>Requires=</varname>, <varname>Wants=</varname> or <varname>BindsTo=</varname>. It is a
-        common pattern to include a unit name in both the <varname>After=</varname> and <varname>Requires=</varname>
-        option, in which case the unit listed will be started before the unit that is configured with these
-        options. This option may be specified more than once, in which case ordering dependencies for all listed names
-        are created. <varname>After=</varname> is the inverse of <varname>Before=</varname>, i.e. while
-        <varname>After=</varname> ensures that the configured unit is started after the listed unit finished starting
-        up, <varname>Before=</varname> ensures the opposite, i.e. that the configured unit is fully started up before
-        the listed unit is started. Note that when two units with an ordering dependency between them are shut down,
-        the inverse of the start-up order is applied. i.e. if a unit is configured with <varname>After=</varname> on
-        another unit, the former is stopped before the latter if both are shut down. Given two units with any ordering
-        dependency between them, if one unit is shut down and the other is started up, the shutdown is ordered before
-        the start-up. It doesn't matter if the ordering dependency is <varname>After=</varname> or
-        <varname>Before=</varname>, in this case. It also doesn't matter which of the two is shut down, as long as one
-        is shut down and the other is started up. The shutdown is ordered before the start-up in all cases. If two
-        units have no ordering dependencies between them, they are shut down or started up simultaneously, and no
-        ordering takes place.  </para></listitem>
+        <listitem><para>These two settings expect a space-separated list of unit names. They configure ordering
+        dependencies between units. If a unit <filename>foo.service</filename> contains a setting
+        <option>Before=bar.service</option> and both units are being started, <filename>bar.service</filename>'s
+        start-up is delayed until <filename>foo.service</filename> has finished starting up.  Note that this setting is
+        independent of and orthogonal to the requirement dependencies as configured by <varname>Requires=</varname>,
+        <varname>Wants=</varname> or <varname>BindsTo=</varname>. It is a common pattern to include a unit name in both
+        the <varname>After=</varname> and <varname>Requires=</varname> options, in which case the unit listed will be
+        started before the unit that is configured with these options. This option may be specified more than once, in
+        which case ordering dependencies for all listed names are created. <varname>After=</varname> is the inverse of
+        <varname>Before=</varname>, i.e. while <varname>After=</varname> ensures that the configured unit is started
+        after the listed unit finished starting up, <varname>Before=</varname> ensures the opposite, that the
+        configured unit is fully started up before the listed unit is started. Note that when two units with an
+        ordering dependency between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is
+        configured with <varname>After=</varname> on another unit, the former is stopped before the latter if both are
+        shut down. Given two units with any ordering dependency between them, if one unit is shut down and the other is
+        started up, the shutdown is ordered before the start-up. It doesn't matter if the ordering dependency is
+        <varname>After=</varname> or <varname>Before=</varname>, in this case. It also doesn't matter which of the two
+        is shut down, as long as one is shut down and the other is started up. The shutdown is ordered before the
+        start-up in all cases. If two units have no ordering dependencies between them, they are shut down or started
+        up simultaneously, and no ordering takes place. It depends on the unit type when precisely a unit has finished
+        starting up. Most importantly, for service units start-up is considered completed for the purpose of
+        <varname>Before=</varname>/<varname>After=</varname> when all its configured start-up commands have been
+        invoked and they either failed or reported start-up success.</para></listitem>
       </varlistentry>
 
       <varlistentry>