man: rework the description of Aliases and .wants/.requires directories

The description of Alias= wasn't incorrect, but it sounded like Alias= creates
a different type of dependency, while it's just a glorified way to create
symlinks. Also recommend 'preset' in addition to 'enable'.

Describe .wants/.requires dirs as equals, without implying that the [Install]
section can only be used for .wants.

The text was partially out of date (systemd-networkd.service now creates as
alias in /etc, not /usr/lib, let's just not say anything about the full path).

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 0ac9ff4882212d97b6c05d7ad282f384a203101b..8307be1d33f66118f549d5df2a96f71f578018f1 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -123,34 +123,40 @@
     do not need the prefix. Applications may use this to include
     additional information in the unit files.</para>
 
-    <para>Units can be aliased (have an alternative name), by creating a symlink from the new name
-    to the existing name in one of the unit search paths. For example,
-    <filename>systemd-networkd.service</filename> has the alias
-    <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the
-    symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In
-    addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the
-    [Install] section; those aliases are only effective when the unit is enabled. When the unit is
-    enabled, symlinks will be created for those names, and removed when the unit is disabled. For
-    example, <filename>reboot.target</filename> specifies
-    <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever
-    CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>,
-    <command>disable</command>, <command>start</command>, <command>stop</command>,
-    <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>,
-    <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the
-    limitation that aliases specified through <varname>Alias=</varname> are only effective when the
-    unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para>
+    <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the
+    existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename>
+    has the alias <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as
+    a symlink, so when <command>systemd</command> is asked through D-Bus to load
+    <filename>dbus-org.freedesktop.network1.service</filename>, it'll load
+    <filename>systemd-networkd.service</filename>. Alias names may be used in commands like
+    <command>enable</command>, <command>disable</command>, <command>start</command>, <command>stop</command>,
+    <command>status</command>, and similar, and in all unit dependency directives, including
+    <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>,
+    <varname>After=</varname>. Aliases cannot be used with the <command>preset</command> command.</para>
+
+    <para>Unit files may specify aliases through the <varname>Alias=</varname> directive in the [Install]
+    section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is
+    disabled. For example, <filename>reboot.target</filename> specifies
+    <varname>Alias=ctrl-alt-del.target</varname>, so when enabled, the symlink
+    <filename>/etc/systemd/systemd/ctrl-alt-del.service</filename> pointing to the
+    <filename>reboot.target</filename> file will be created, and when
+    <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap></keycombo> is invoked,
+    <command>systemd</command> will look for the <filename>ctrl-alt-del.service</filename> and execute
+    <filename>reboot.service</filename>. <command>systemd</command> does not look at the [Install] section at
+    all during normal operation, so any directives in that section only have an effect through the symlinks
+    created during enablement.</para>
 
     <para>Along with a unit file <filename>foo.service</filename>, the directory
-    <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a
-    directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit.
-    This is useful to hook units into the start-up of other units, without having to modify their
-    unit files. For details about the semantics of <varname>Wants=</varname>, see below. The
-    preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is
-    with the <command>enable</command> command of the
-    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    tool which reads information from the [Install] section of unit files (see below). A similar
-    functionality exists for <varname>Requires=</varname> type dependencies as well, the directory
-    suffix is <filename>.requires/</filename> in this case.</para>
+    <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a directory are
+    implicitly added as dependencies of type <varname>Wants=</varname> to the unit. Similar functionality
+    exists for <varname>Requires=</varname> type dependencies as well, the directory suffix is
+    <filename>.requires/</filename> in this case. This functionality is useful to hook units into the
+    start-up of other units, without having to modify their unit files. For details about the semantics of
+    <varname>Wants=</varname>, see below. The preferred way to create symlinks in the
+    <filename>.wants/</filename> or <filename>.requires/</filename> directory of a unit file is by embedding
+    the dependency in [Install] section of the target unit, and creating the symlink in the file system with
+    the with the <command>enable</command> or <command>preset</command> commands of
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 
     <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
     <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this