morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

man: improve Description= documentation

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

Fixes: #36165
This commit is contained in:
Lennart Poettering
2025-07-07 10:10:29 +02:00
parent d03714e4e4
commit 172dd81e92
1 changed files with 18 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
man/systemd.unit.xml
View File

@@ -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