docs: add a new section about the generator

Add a new section to "Explanation" about the generator behavior.

Update netplan-generate(8) to mention the new generator behavior.

doc/explanation.md

@@ -6,6 +6,12 @@
 structure-id
 ```
 
+## Netplan Generator
+
+```{toctree}
+generator
+```
+
 ## NetworkManager
 
 ```{toctree}

doc/generator.md

@@ -0,0 +1,19 @@
+---
+title: "Netplan Generator"
+---
+
+Netplan uses a [systemd-generator](https://www.freedesktop.org/software/systemd/man/latest/systemd.generator.html)
+to emit network configuration at boot time. This generator is called very early during the boot
+process to ensure that all the configuration needed will be available for the back end
+the user chose to use.
+
+The generator executes the same tool used by the command `netplan generate`. One of the
+differences is that, when called as a systemd generator, parsing errors will be ignored by default.
+That means that errors in the configuration will not prevent Netplan to emit network configuration.
+When executed via the CLI, via `netplan generate` or `netplan apply` for example, errors will not
+be ignored and the user is encouraged to fix them, otherwise the commands will fail.
+
+When an error is ignored, Netplan might end up with network definitions that are not
+fully valid and incomplete. Users are advised to fix any issues present in their
+configuration to avoid having network connectivity problems.
+

doc/netplan-generate.md

@@ -30,6 +30,11 @@ Only if executed during the systemd `initializing` phase
 it attempt to start/apply the newly created service units.
 **Requires feature: `generate-just-in-time*`*
 
+When called as a systemd.generator(7), all the parsing and validation errors
+will be ignored by default. If network definitions are skipped due to
+parsing errors, they might be incomplete. That means that the
+back end configuration emitted might not be fully valid.
+
 For details of the configuration file format, see **`netplan`**(5).
 
 ## OPTIONS