Merge pull request #24018 from keszybz/generator-cleanups

Make generators easier to test, fix various corner issues

3 files changed, 23 insertions, 21 deletions

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 4a0a7b34dc..31388b9c3d 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -272,13 +272,14 @@
       <varlistentry>
         <term>BARRIER=1</term>
 
-        <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by means of
-        closing the file descriptor sent with this command. The service manager guarantees that the processing of a <varname>
-        BARRIER=1</varname> command will only happen after all previous notification messages sent before this command
-        have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize
-        against reception of all previous status messages. Note that this command cannot be mixed with other notifications,
-        and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that
-        sending 0 or more than 1 file descriptor with this command is a violation of the protocol.</para></listitem>
+        <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by
+        means of closing the file descriptor sent with this command. The service manager guarantees that the
+        processing of a <varname>BARRIER=1</varname> command will only happen after all previous notification
+        messages sent before this command have been processed. Hence, this command accompanied with a single
+        file descriptor can be used to synchronize against reception of all previous status messages. Note
+        that this command cannot be mixed with other notifications, and has to be sent in a separate message
+        to the service manager, otherwise all assignments will be ignored. Note that sending 0 or more than 1
+        file descriptor with this command is a violation of the protocol.</para></listitem>
       </varlistentry>
     </variablelist>
 
@@ -341,7 +342,7 @@
 
     <para><function>sd_notify_barrier()</function> allows the caller to
     synchronize against reception of previously sent notification messages
-    and uses the <literal>BARRIER=1</literal> command. It takes a relative
+    and uses the <varname>BARRIER=1</varname> command. It takes a relative
     <varname>timeout</varname> value in microseconds which is passed to
     <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
     </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.
diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml
index 21fa85da7d..21c3ea94a7 100644
--- a/man/systemd-fstab-generator.xml
+++ b/man/systemd-fstab-generator.xml
@@ -46,7 +46,7 @@
     for more information about special <filename>/etc/fstab</filename>
     mount options this generator understands.</para>
 
-    <para>One special topic is handling of symbolic links.  Historical init
+    <para>One special topic is handling of symbolic links. Historical init
     implementations supported symlinks in <filename>/etc/fstab</filename>.
     Because mount units will refuse mounts where the target is a symbolic link,
     this generator will resolve any symlinks as far as possible when processing
@@ -251,8 +251,8 @@
       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <ulink url="https://systemd.io/ENVIRONMENT/">Known Environment Variables</ulink>
     </para>
   </refsect1>
-
 </refentry>
diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index 1f916ac65e..d837afb6f9 100644
--- a/man/systemd.generator.xml
+++ b/man/systemd.generator.xml
@@ -26,8 +26,8 @@
     <cmdsynopsis>
       <command index='false'>/path/to/generator</command>
       <arg choice="plain"><replaceable>normal-dir</replaceable></arg>
-      <arg choice="plain"><replaceable>early-dir</replaceable></arg>
-      <arg choice="plain"><replaceable>late-dir</replaceable></arg>
+      <arg choice="option"><replaceable>early-dir</replaceable></arg>
+      <arg choice="option"><replaceable>late-dir</replaceable></arg>
     </cmdsynopsis>
 
     <para>
@@ -56,13 +56,13 @@
     that they can extend the unit file hierarchy the service manager subsequently loads and operates
     on.</para>
 
-    <para>Each generator is called with three directory paths that are to be used for generator output. In
-    these three directories, generators may dynamically generate unit files (regular ones, instances, as well
-    as templates), unit file <filename>.d/</filename> drop-ins, and create symbolic links to unit files to
-    add additional dependencies, create aliases, or instantiate existing templates. Those directories are
-    included in the unit load path of
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, allowing
-    generated configuration to extend or override existing definitions.</para>
+    <para><command>systemd</command> will call each generator with three directory paths that are to be used
+    for generator output. In these three directories, generators may dynamically generate unit files (regular
+    ones, instances, as well as templates), unit file <filename>.d/</filename> drop-ins, and create symbolic
+    links to unit files to add additional dependencies, create aliases, or instantiate existing templates.
+    Those directories are included in the unit load path, allowing generated configuration to extend or
+    override existing definitions. For tests, generators may be called with just one argument; the generator
+    should assume that all three paths are the same in that case.</para>
 
     <para>Directory paths for generator output differ by priority: <filename>…/generator.early</filename> has
     priority higher than the admin configuration in <filename>/etc/</filename>, while
@@ -96,7 +96,8 @@
     <para>Generators are invoked with three arguments: paths to directories where generators can place their
     generated unit files or symlinks. By default those paths are runtime directories that are included in the
     search path of <command>systemd</command>, but a generator may be called with different paths for
-    debugging purposes.</para>
+    debugging purposes. If only one argument is provided, the generator should use the same directory as the
+    the three output paths.</para>
 
     <orderedlist>
       <listitem>