man: improve Description= documentation

This is an attempt to address the issues raised in #36165.

Fixes: #36165

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 04ba9e95ed5dd01f070c81f9cb2ffa19bec220b1..7f552a687f1028d7d68b6a5ba9913d69a546d811 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -597,19 +597,21 @@
     <variablelist class='unit-directives'>
       <varlistentry>
         <term><varname>Description=</varname></term>
-        <listitem><para>A short human-readable title of the unit. This may be used by
-        <command>systemd</command> (and other UIs) as a user-visible label for the unit, so this string
-        should identify the unit rather than describe it, despite the name. This string also should not just
-        repeat the unit name. <literal>Apache2 Web Server</literal> is a good example. Bad examples are
-        <literal>high-performance lightweight HTTP server</literal> (too generic) or
-        <literal>Apache2</literal> (meaningless for people who do not know Apache, duplicates the unit
-        name). <command>systemd</command> may use this string as a noun in status messages (<literal>Starting
-        <replaceable>description</replaceable>...</literal>, <literal>Started
-        <replaceable>description</replaceable>.</literal>, <literal>Reached target
-        <replaceable>description</replaceable>.</literal>, <literal>Failed to start
-        <replaceable>description</replaceable>.</literal>), so it should be capitalized, and should not be a
-        full sentence, or a phrase with a continuous verb. Bad examples include <literal>exiting the
-        container</literal> or <literal>updating the database once per day.</literal>.</para>
+        <listitem><para>A brief, meaningful, human-readable text identifying the unit. This may be used by
+        <command>systemd</command> (and suitable UIs) as a user-visible label for the unit, so this string
+        should identify the unit rather than just describe it, despite the name. This string also should not
+        just repeat the unit name. <literal>Apache HTTP Server</literal> or <literal>Postfix Mail
+        Server</literal> are good examples. Bad examples are <literal>high-performance lightweight HTTP
+        server</literal> (too generic) or <literal>Apache</literal> (meaningless for people who do not know
+        the Apache HTTP server project, duplicates the unit name). <command>systemd</command> may use this
+        string as a noun in status messages (<literal>Starting
+        <replaceable>Description</replaceable>...</literal>, <literal>Started
+        <replaceable>Description</replaceable>.</literal>, <literal>Reached target
+        <replaceable>Description</replaceable>.</literal>, <literal>Failed to start
+        <replaceable>Description</replaceable>.</literal>), so it should be capitalized, and should not be a
+        full sentence, or a phrase with a verb conjugated in the present continuous, or end in a full
+        stop. Bad examples include <literal>exiting the container</literal>, <literal>updating the database
+        once per day.</literal>, or <literal>OpenSSH server second instance daemon</literal>.</para>
 
         <xi:include href="version-info.xml" xpointer="v201"/>
         </listitem>
@@ -2563,7 +2565,7 @@ ExecStart=/usr/sbin/foo-daemon
       the following contents:</para>
 
       <programlisting>[Unit]
-Description=Some HTTP server
+Description=Some HTTP Server
 After=remote-fs.target sqldb.service
 Requires=sqldb.service
 AssertPathExists=/srv/webserver
@@ -2595,7 +2597,7 @@ WantedBy=multi-user.target</programlisting>
       change the chosen settings:</para>
 
       <programlisting>[Unit]
-Description=Some HTTP server
+Description=Some HTTP Server
 After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
 Requires=sqldb.service <emphasis>memcached.service</emphasis>
 AssertPathExists=<emphasis>/srv/www</emphasis>
@@ -2653,7 +2655,7 @@ PrivateTmp=yes</programlisting>
       <filename index='false'>/etc/systemd/system/failure-handler@.service</filename>:</para>
 
       <programlisting>[Unit]
-Description=My failure handler for %i
+Description=My Failure Handler For %i
 
 [Service]
 Type=oneshot