<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
-
- This file is part of systemd.
-
- Copyright 2015 Zbigniew Jędrzejewski-Szmek
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.generator">
<refentryinfo>
<title>systemd.generator</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<refsynopsisdiv>
<cmdsynopsis>
- <command>/path/to/generator</command>
+ <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>
</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>
<para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
converts <filename>/etc/fstab</filename> into native mount units. It uses
argv[1] as location to place the generated unit files in order to allow the
- user to override <filename>/etc/fstab</filename> with her own native unit
+ user to override <filename>/etc/fstab</filename> with their own native unit
files, but also to ensure that <filename>/etc/fstab</filename> overrides any
vendor default from <filename>/usr</filename>.</para>
<citerefentry><refentrytitle>systemd-rc-local-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-xdg-autostart-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>