Merge pull request #2575 from poettering/manfixes

A variety of man page fixes

6 files changed, 67 insertions, 58 deletions

diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml
index 859bec29e3..251bdecbad 100644
--- a/man/nss-myhostname.xml
+++ b/man/nss-myhostname.xml
@@ -71,9 +71,9 @@
       is on the local loopback) and the IPv6 address ::1 (which is the
       local host).</para></listitem>
 
-      <listitem><para>The hostname <literal>localhost</literal> is
-      resolved to the IP addresses 127.0.0.1 and
-      ::1.</para></listitem>
+      <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in
+      <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is
+      resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
 
       <listitem><para>The hostname <literal>gateway</literal> is
       resolved to all current default routing gateway addresses,
diff --git a/man/systemctl.xml b/man/systemctl.xml
index cce7861139..50eb939313 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1134,7 +1134,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
                 <tbody>
                   <row>
                     <entry><literal>enabled</literal></entry>
-                    <entry morerows='1'>Enabled through creating symlinks encoded in the <literal>[Install]</literal> section (permanently or just in <filename>/run</filename>).</entry>
+                    <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry>
                     <entry morerows='1'>0</entry>
                   </row>
                   <row>
@@ -1703,7 +1703,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
       unit specifications (designated as
       <replaceable>PATTERN</replaceable>...). In the first case, the
       unit name with or without a suffix must be given. If the suffix
-      is not specified, systemctl will append a suitable suffix,
+      is not specified ("abbreviated"), systemctl will append a suitable suffix,
       <literal>.service</literal> by default, and a type-specific
       suffix in case of commands which operate only on specific unit
       types. For example,
@@ -1740,9 +1740,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
       loaded are not considered for glob expansion.
       </para>
 
-      <para>For unit file commands, the specified
-      <replaceable>NAME</replaceable> should be the full name of the
-      unit file, or the absolute path to the unit file:
+      <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file
+      (possibly abbreviated, see above), or the absolute path to the unit file:
       <programlisting># systemctl enable foo.service</programlisting>
       or
       <programlisting># systemctl link /path/to/foo.service</programlisting>
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 1b63afdded..4b4ea52aba 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -87,9 +87,9 @@
       is on the local loopback) and the IPv6 address ::1 (which is the
       local host).</para></listitem>
 
-      <listitem><para>The hostname <literal>localhost</literal> is
-      resolved to the IP addresses 127.0.0.1 and
-      ::1.</para></listitem>
+      <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in
+      <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is
+      resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>
 
       <listitem><para>The hostname <literal>gateway</literal> is
       resolved to all current default routing gateway addresses,
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 2145e33d05..d7760d4f2c 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -371,7 +371,7 @@
         with a <literal>-</literal> exit successfully.</para>
 
         <para><varname>ExecStartPost=</varname> commands are only run after
-        the service has started, as determined by <varname>Type=</varname>
+        the service has started successfully, as determined by <varname>Type=</varname>
         (i.e. the process has been started for <varname>Type=simple</varname>
         or <varname>Type=idle</varname>, the process exits successfully for
         <varname>Type=oneshot</varname>, the initial process exits successfully
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 0a37f65956..055d854555 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -204,12 +204,22 @@
       <varlistentry>
         <term><filename>emergency.target</filename></term>
         <listitem>
-          <para>A special target unit that starts an emergency shell
-          on the main console. This unit is supposed to be used with
-          the kernel command line option
-          <varname>systemd.unit=</varname> and has otherwise little
-          use.
-          </para>
+          <para>A special target unit that starts an emergency shell on the main console. This target does not pull in
+          any serices or mounts. It is the most minimal version of starting the system in order to acquire an
+          interactive shell; the only processes running are usually just the system manager (PID 1) and the shell
+          process. This unit is supposed to be used with the kernel command line option
+          <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails,
+          and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose,
+          but also starts the most basic services and mounts all file systems.</para>
+
+          <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this
+          mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility
+          with SysV.</para>
+
+          <para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting
+          with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with
+          the full system and service manager, and allows starting individual units in order to continue the boot
+          process in steps.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -440,11 +450,18 @@
       <varlistentry>
         <term><filename>rescue.target</filename></term>
         <listitem>
-          <para>A special target unit for setting up the base system
-          and a rescue shell.</para>
+          <para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue
+          shell. Isolate to this target in order to administer the system in single-user mode with all file systems
+          mounted but with no services running, except for the most basic. Compare with
+          <filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or
+          most basic services.</para>
 
-          <para><filename>runlevel1.target</filename> is an alias for
-          this target unit, for compatibility with SysV.</para>
+          <para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with
+          SysV.</para>
+
+          <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this
+          mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with
+          SysV.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 46b288f20b..16aded89d1 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -178,18 +178,14 @@
     directory suffix is <filename>.requires/</filename> in this
     case.</para>
 
-    <para>Along with a unit file <filename>foo.service</filename>, a
-    directory <filename>foo.service.d/</filename> may exist. All files
-    with the suffix <literal>.conf</literal> from this directory will
-    be parsed after the file itself is parsed. This is useful to alter
-    or add configuration settings to a unit, without having to modify
-    their unit files. Make sure that the file that is included has the
-    appropriate section headers before any directive. Note that, for
-    instanced units, this logic will first look for the instance
-    <literal>.d/</literal> subdirectory and read its
-    <literal>.conf</literal> files, followed by the template
-    <literal>.d/</literal> subdirectory and reads its
-    <literal>.conf</literal> files.</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
+    directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings to
+    a unit, without having to modify their unit files. Make sure that the file that is included has the appropriate
+    section headers before any directive. Note that for instanced units, this logic will first look for the instance
+    <literal>.d/</literal> subdirectory and read its <literal>.conf</literal> files, followed by the template
+    <literal>.d/</literal> subdirectory and reads its <literal>.conf</literal> files. Also note that settings from the
+    <literal>[Install]</literal> section are not available in drop-in unit files, and have no effect.</para>
 
     <para>In addition to <filename>/etc/systemd/system</filename>,
     the drop-in <literal>.conf</literal> files for system services
@@ -827,13 +823,14 @@
              useful and probably just
              confusing. -->
 
-        <listitem><para>Before starting a unit verify that the
-        specified condition is true. If it is not true, the starting
-        of the unit will be skipped, however all ordering dependencies
-        of it are still respected. A failing condition will not result
-        in the unit being moved into a failure state. The condition is
-        checked at the time the queued start job is to be
-        executed.</para>
+        <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
+        starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
+        respected. A failing condition will not result in the unit being moved into a failure state. The condition is
+        checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
+        units that do not apply to the local running system, for example because the kernel or runtime environment
+        doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
+        <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
+        state and logs about the failed check (see below).</para>
 
         <para><varname>ConditionArchitecture=</varname> may be used to
         check whether the system is running on a specific
@@ -1067,14 +1064,12 @@
         <term><varname>AssertFileNotEmpty=</varname></term>
         <term><varname>AssertFileIsExecutable=</varname></term>
 
-        <listitem><para>Similar to the
-        <varname>ConditionArchitecture=</varname>,
-        <varname>ConditionVirtualization=</varname>, etc., condition
-        settings described above, these settings add assertion checks
-        to the start-up of the unit. However, unlike the conditions
-        settings, any assertion setting that is not met results in
-        failure of the start job it was triggered
-        by.</para></listitem>
+        <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
+        <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
+        assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
+        that is not met results in failure of the start job it was triggered by (which means this is logged about
+        loudly). Use assertion expressions for units that cannot operate when specific requirements are not met, and
+        where this is something the administrator or user should look into.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -1094,15 +1089,13 @@
   <refsect1>
     <title>[Install] Section Options</title>
 
-    <para>Unit file may include an <literal>[Install]</literal>
-    section, which carries installation information for the unit. This
-    section is not interpreted by
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    during runtime. It is used exclusively by the
-    <command>enable</command> and <command>disable</command> commands
-    of the
-    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    tool during installation of a unit:</para>
+    <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for
+    the unit. This section is not interpreted by
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
+    used by the <command>enable</command> and <command>disable</command> commands of the
+    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
+    installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in
+    <filename>.d/*.conf</filename> unit file drop-ins (see above).</para>
 
     <variablelist class='unit-directives'>
       <varlistentry>