From 7655cd3d587f9496d994f45e0a9d732afbaf0d43 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 16 Nov 2017 03:37:25 +0100
Subject: [PATCH] man: document that generators can generate
 instances+templates and regular unit files (#7342)

This addition is kept brief on purpose, since in order to write a good
generator users don't really need to grok templating/instantiation.

Fixes: #7257
---
 man/systemd.generator.xml | 30 ++++++++++++------------------
 1 file changed, 12 insertions(+), 18 deletions(-)

diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index a6af5f724c..1624e52c4d 100644
--- a/man/systemd.generator.xml
+++ b/man/systemd.generator.xml
@@ -74,17 +74,14 @@
 
   <refsect1>
     <title>Description</title>
-    <para>Generators are small binaries that live in
-    <filename>&usergeneratordir;/</filename> and other directories
-    listed above.
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    will execute those binaries very early at bootup and at
-    configuration reload time — before unit files are loaded.
-    Generators can dynamically generate unit files or create symbolic
-    links to unit files to add additional dependencies, thus extending
-    or overriding existing definitions. Their main purpose is to
-    convert configuration files that are not native unit files
-    dynamically into native unit files.</para>
+    <para>Generators are small executables that live in <filename>&systemgeneratordir;/</filename> and other
+    directories listed above.
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those
+    binaries very early at bootup and at configuration reload time — before unit files are loaded.  Generators may
+    dynamically generate unit files (regular ones, instances as well as templates) and unit file
+    <filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
+    instantiate existing templates, thus extending or overriding existing definitions. Their main purpose is to convert
+    configuration files that are not native unit files dynamically into native unit files.</para>
 
     <para>Generators are loaded from a set of paths determined during
     compilation, as listed above. System and user generators are loaded
@@ -189,13 +186,10 @@
 
         <listitem>
           <para>
-            Generators should only be used to generate unit files, not
-            any other kind of configuration. Due to the lifecycle
-            logic mentioned above, generators are not a good fit to
-            generate dynamic configuration for other services. If you
-            need to generate dynamic configuration for other services,
-            do so in normal services you order before the service in
-            question.
+            Generators should only be used to generate unit files and symlinks to them, not any other kind of
+            configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate
+            dynamic configuration for other services. If you need to generate dynamic configuration for other services,
+            do so in normal services you order before the service in question.
           </para>
         </listitem>