man: tell generator writers to provide authorship and source information

Our generators always put a comment who generated the file, but we didn't
recommend it to others.

Let's also strengthen the advice to use SourcePath=.

diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index 254b0f3181ce29a21eef7aaeeb5426f8f4160d13..c77afda0f2193e16113b7baf79ca987da558cef6 100644 (file)
--- a/man/systemd.generator.xml
+++ b/man/systemd.generator.xml
@@ -193,12 +193,15 @@
       </listitem>
 
       <listitem>
-        <para>It is a good idea to use the <varname>SourcePath=</varname> directive
-        in generated unit files to specify the source configuration file you are
-        generating the unit from. This makes things more easily understood by the
-        user and also has the benefit that systemd can warn the user about
-        configuration files that changed on disk but have not been read yet by
-        systemd.</para>
+        <para>The generator should always include its own name in a comment at the top of the generated file,
+        so that the user can easily figure out which component created or amended a particular unit.</para>
+
+        <para>The <varname>SourcePath=</varname> directive should be used in generated files to specify the
+        source configuration file they are generated from. This makes things more easily understood by the
+        user and also has the benefit that systemd can warn the user about configuration files that changed
+        on disk but have not been read yet by systemd. The <varname>SourcePath=</varname> value does not have
+        to be a file in a physical filesystem. For example, in the common case of the generator looking at
+        the kernel command line, <option>SourcePath=/proc/cmdline</option> should be used.</para>
       </listitem>
 
       <listitem>