man: fix grammatical errors and other formatting issues

* standardize capitalization of STDIN, STDOUT, and STDERR
* reword some sentences for clarity
* reflow some very long lines to be shorter than ~80 characters
* add some missing <literal>, <constant>, <varname>, <option>, and <filename> tags

1 files changed, 103 insertions, 98 deletions

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 6e9b6696fc..be9bdcaf99 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -103,7 +103,7 @@
                 script. This is useful for compatibility with
                 SysV. Note that this compatibility is quite
                 comprehensive but not 100%. For details about the
-                incompatibilities see the <ulink
+                incompatibilities, see the <ulink
                 url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
                 with SysV</ulink> document.
                 </para>
@@ -172,13 +172,13 @@
                                 <varname>PIDFile=</varname> option, so
                                 that systemd can identify the main
                                 process of the daemon. systemd will
-                                proceed starting follow-up units as
-                                soon as the parent process
+                                proceed with starting follow-up units
+                                as soon as the parent process
                                 exits.</para>
 
                                 <para>Behavior of
                                 <option>oneshot</option> is similar
-                                to <option>simple</option>, however
+                                to <option>simple</option>; however,
                                 it is expected that the process has to
                                 exit before systemd starts follow-up
                                 units. <varname>RemainAfterExit=</varname>
@@ -187,13 +187,13 @@
 
                                 <para>Behavior of
                                 <option>dbus</option> is similar to
-                                <option>simple</option>, however it is
+                                <option>simple</option>; however, it is
                                 expected that the daemon acquires a
                                 name on the D-Bus bus, as configured
                                 by
                                 <varname>BusName=</varname>. systemd
-                                will proceed starting follow-up units
-                                after the D-Bus bus name has been
+                                will proceed with starting follow-up
+                                units after the D-Bus bus name has been
                                 acquired. Service units with this
                                 option configured implicitly gain
                                 dependencies on the
@@ -204,12 +204,12 @@
 
                                 <para>Behavior of
                                 <option>notify</option> is similar to
-                                <option>simple</option>, however it is
+                                <option>simple</option>; however, it is
                                 expected that the daemon sends a
                                 notification message via
                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                                or an equivalent call when it finished
-                                starting up. systemd will proceed
+                                or an equivalent call when it has finished
+                                starting up. systemd will proceed with
                                 starting follow-up units after this
                                 notification message has been sent. If
                                 this option is used,
@@ -227,7 +227,7 @@
 
                                 <para>Behavior of
                                 <option>idle</option> is very similar
-                                to <option>simple</option>, however
+                                to <option>simple</option>; however,
                                 actual execution of the service
                                 binary is delayed until all jobs are
                                 dispatched. This may be used to avoid
@@ -260,7 +260,7 @@
                                 is set and <option>PIDFile=</option>
                                 is unset because for the other types
                                 or with an explicitly configured PID
-                                file the main PID is always known. The
+                                file, the main PID is always known. The
                                 guessing algorithm might come to
                                 incorrect conclusions if a daemon
                                 consists of more than one process. If
@@ -292,14 +292,13 @@
                                 <term><varname>BusName=</varname></term>
 
                                 <listitem><para>Takes a D-Bus bus
-                                name, that this service is reachable
+                                name that this service is reachable
                                 as. This option is mandatory for
                                 services where
                                 <varname>Type=</varname> is set to
                                 <option>dbus</option>, but its use
-                                is otherwise recommended as well if
-                                the process takes a name on the D-Bus
-                                bus.</para>
+                                is otherwise recommended if the process
+                                takes a name on the D-Bus bus.</para>
                                 </listitem>
                         </varlistentry>
 
@@ -318,7 +317,7 @@
                                 <varname>Type=oneshot</varname> is
                                 used, more than one command may be
                                 specified. Multiple command lines may
-                                be concatenated in a single directive,
+                                be concatenated in a single directive
                                 by separating them with semicolons
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
@@ -362,12 +361,12 @@
 
                                 <para>If more than one command is
                                 specified, the commands are invoked
-                                one by one sequentially in the order
-                                they appear in the unit file. If one
-                                of the commands fails (and is not
-                                prefixed with <literal>-</literal>),
-                                other lines are not executed and the
-                                unit is considered failed.</para>
+                                sequentially in the order they appear
+                                in the unit file. If one of the
+                                commands fails (and is not prefixed
+                                with <literal>-</literal>), other lines
+                                are not executed, and the unit is
+                                considered failed.</para>
 
                                 <para>Unless
                                 <varname>Type=forking</varname> is
@@ -387,7 +386,7 @@
                                 <para>Basic environment variable
                                 substitution is supported. Use
                                 <literal>${FOO}</literal> as part of a
-                                word, or as a word of its own on the
+                                word, or as a word of its own, on the
                                 command line, in which case it will be
                                 replaced by the value of the
                                 environment variable including all
@@ -410,12 +409,12 @@
                                 fashion may be defined through
                                 <varname>Environment=</varname> and
                                 <varname>EnvironmentFile=</varname>.
-                                In addition, variables listed in
+                                In addition, variables listed in the
                                 section "Environment variables in
                                 spawned processes" in
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                                 which are considered "static
-                                configuration" may used (this includes
+                                configuration", may be used (this includes
                                 e.g. <varname>$USER</varname>, but not
                                 <varname>$TERM</varname>).</para>
 
@@ -447,10 +446,10 @@
                                 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
                                 <para>This will execute
                                 <command>/bin/echo</command> two
-                                times, each time with one argument,
+                                times, each time with one argument:
                                 <literal>one</literal> and
                                 <literal>two two</literal>,
-                                respectively. Since two commands are
+                                respectively. Because two commands are
                                 specified,
                                 <varname>Type=oneshot</varname> must
                                 be used.</para>
@@ -512,8 +511,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 here following the same scheme as for
                                 <varname>ExecStart=</varname>.</para>
 
-                                <para>One additional special
-                                environment variables is set: if known
+                                <para>One additional, special
+                                environment variable is set: if known,
                                 <varname>$MAINPID</varname> is set to
                                 the main process of the daemon, and
                                 may be used for command lines like the
@@ -532,15 +531,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 following the same scheme as described
                                 for <varname>ExecStart=</varname>
                                 above. Use of this setting is
-                                optional. All processes remaining for
-                                a service after the commands
-                                configured in this option are run are
+                                optional. After the commands configured
+                                in this option are run, all processes
+                                remaining for a service are
                                 terminated according to the
                                 <varname>KillMode=</varname> setting
                                 (see
                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
                                 this option is not specified, the
-                                process is terminated right-away when
+                                process is terminated immediately when
                                 service stop is requested. Specifier
                                 and environment variable substitution
                                 is supported (including
@@ -586,14 +585,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 daemon service does not signal
                                 start-up completion within the
                                 configured time, the service will be
-                                considered failed and be shut down
-                                again.
+                                considered failed and will be shut
+                                down again.
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
-                                20s". Pass 0 to disable the timeout
-                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
-                                manager configuration file, except when
-                                <varname>Type=oneshot</varname> is
+                                20s". Pass <literal>0</literal> to
+                                disable the timeout logic. Defaults to
+                                <varname>TimeoutStartSec=</varname> from
+                                the manager configuration file, except
+                                when <varname>Type=oneshot</varname> is
                                 used, in which case the timeout
                                 is disabled by default.
                                 </para></listitem>
@@ -603,17 +603,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <term><varname>TimeoutStopSec=</varname></term>
                                 <listitem><para>Configures the time to
                                 wait for stop. If a service is asked
-                                to stop but does not terminate in the
+                                to stop, but does not terminate in the
                                 specified time, it will be terminated
-                                forcibly via <constant>SIGTERM</constant>, and after
-                                another delay of this time with
-                                <constant>SIGKILL</constant> (See
+                                forcibly via <constant>SIGTERM</constant>,
+                                and after another timeout of equal duration
+                                with <constant>SIGKILL</constant> (see
                                 <varname>KillMode=</varname>
                                 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
-                                20s". Pass 0 to disable the timeout
-                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
+                                20s". Pass <literal>0</literal> to disable
+                                the timeout logic. Defaults to
+                                <varname>TimeoutStartSec=</varname> from the
                                 manager configuration file.
                                 </para></listitem>
                         </varlistentry>
@@ -634,11 +635,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 watchdog is activated when the start-up is
                                 completed. The service must call
                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                                regularly with "WATCHDOG=1" (i.e. the
-                                "keep-alive ping"). If the time
+                                regularly with <literal>WATCHDOG=1</literal>
+                                (i.e. the "keep-alive ping"). If the time
                                 between two such calls is larger than
                                 the configured time, then the service
-                                is placed in a failure state. By
+                                is placed in a failed state. By
                                 setting <varname>Restart=</varname> to
                                 <option>on-failure</option> or
                                 <option>always</option>, the service
@@ -669,8 +670,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 service process exits, is killed,
                                 or a timeout is reached. The service
                                 process may be the main service
-                                process, but also one of the processes
-                                specified with
+                                process, but it may also be one of the
+                                processes specified with
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,
                                 <varname>ExecStopPre=</varname>,
@@ -698,12 +699,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 exits cleanly.
                                 In this context, a clean exit means
                                 an exit code of 0, or one of the signals
-                                <constant>SIGHUP</constant>, <constant>SIGINT</constant>, <constant>SIGTERM</constant>, or <constant>SIGPIPE</constant>, and
+                                <constant>SIGHUP</constant>,
+                                <constant>SIGINT</constant>,
+                                <constant>SIGTERM</constant>,
+                                or <constant>SIGPIPE</constant>, and
                                 additionally, exit statuses and signals
                                 specified in <varname>SuccessExitStatus=</varname>.
                                 If set to <option>on-failure</option>,
                                 the service will be restarted when the
-                                process exits with an nonzero exit code,
+                                process exits with a non-zero exit code,
                                 is terminated by a signal (including on
                                 core dump), when an operation (such as
                                 service reload) times out, and when the
@@ -722,7 +726,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <option>always</option>, the service
                                 will be restarted regardless of whether
                                 it exited cleanly or not, got
-                                terminated abnormally by a signal or
+                                terminated abnormally by a signal, or
                                 hit a timeout.</para>
 
                                 <para>In addition to the above settings,
@@ -777,7 +781,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <listitem><para>Takes a list of exit
                                 status definitions that when returned
                                 by the main service process will
-                                prevent automatic service restarts
+                                prevent automatic service restarts,
                                 regardless of the restart setting
                                 configured with
                                 <varname>Restart=</varname>. Exit
@@ -785,19 +789,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 numeric exit codes or termination
                                 signal names, and are separated by
                                 spaces. Defaults to the empty list, so
-                                that by default no exit status is
+                                that, by default, no exit status is
                                 excluded from the configured restart
                                 logic. Example:
                                 <literal>RestartPreventExitStatus=1 6
                                 SIGABRT</literal>, ensures that exit
                                 codes 1 and 6 and the termination
-                                signal SIGABRT will not result in
-                                automatic service restarting. This
-                                option may appear more than once in
-                                which case the list of restart preventing
+                                signal <constant>SIGABRT</constant> will
+                                not result in automatic service
+                                restarting. This
+                                option may appear more than once, in
+                                which case the list of restart-preventing
                                 statuses is merged. If the empty
                                 string is assigned to this option, the
-                                list is reset, all prior assignments
+                                list is reset and all prior assignments
                                 of this option will have no
                                 effect.</para></listitem>
                         </varlistentry>
@@ -805,20 +810,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                         <varlistentry>
                                 <term><varname>PermissionsStartOnly=</varname></term>
                                 <listitem><para>Takes a boolean
-                                argument. If true, the permission
-                                related execution options as
+                                argument. If true, the permission-related
+                                execution options, as
                                 configured with
                                 <varname>User=</varname> and similar
                                 options (see
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for more information) are only applied
+                                for more information), are only applied
                                 to the process started with
                                 <varname>ExecStart=</varname>, and not
                                 to the various other
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,
                                 <varname>ExecReload=</varname>,
-                                <varname>ExecStop=</varname>,
+                                <varname>ExecStop=</varname>, and
                                 <varname>ExecStopPost=</varname>
                                 commands. If false, the setting is
                                 applied to all configured commands the
@@ -829,19 +834,19 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                         <varlistentry>
                                 <term><varname>RootDirectoryStartOnly=</varname></term>
                                 <listitem><para>Takes a boolean
-                                argument. If true, the root directory
+                                argument. If true, the root directory,
                                 as configured with the
                                 <varname>RootDirectory=</varname>
                                 option (see
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for more information) is only applied
+                                for more information), is only applied
                                 to the process started with
                                 <varname>ExecStart=</varname>, and not
                                 to the various other
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,
                                 <varname>ExecReload=</varname>,
-                                <varname>ExecStop=</varname>,
+                                <varname>ExecStop=</varname>, and
                                 <varname>ExecStopPost=</varname>
                                 commands. If false, the setting is
                                 applied to all configured commands the
@@ -851,12 +856,14 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
 
                         <varlistentry>
                                 <term><varname>NonBlocking=</varname></term>
-                                <listitem><para>Set O_NONBLOCK flag
+                                <listitem><para>Set the
+                                <constant>O_NONBLOCK</constant> flag
                                 for all file descriptors passed via
                                 socket-based activation. If true, all
                                 file descriptors >= 3 (i.e. all except
                                 STDIN/STDOUT/STDERR) will have
-                                the O_NONBLOCK flag set and hence are in
+                                the <constant>O_NONBLOCK</constant> flag
+                                set and hence are in
                                 non-blocking mode. This option is only
                                 useful in conjunction with a socket
                                 unit, as described in
@@ -912,8 +919,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 passed to multiple processes at the
                                 same time. Also note that a different
                                 service may be activated on incoming
-                                traffic than inherits the sockets. Or
-                                in other words: the
+                                traffic than that which inherits the
+                                sockets. Or in other words: the
                                 <varname>Service=</varname> setting of
                                 <filename>.socket</filename> units
                                 does not have to match the inverse of
@@ -926,7 +933,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 once, in which case the list of socket
                                 units is merged. If the empty string
                                 is assigned to this option, the list of
-                                sockets is reset, all prior uses of
+                                sockets is reset, and all prior uses of
                                 this setting will have no
                                 effect.</para></listitem>
                         </varlistentry>
@@ -937,10 +944,10 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
 
                                 <listitem><para>Configure service
                                 start rate limiting. By default,
-                                services which are started more often
-                                than 5 times within 10s are not
+                                services which are started more
+                                than 5 times within 10 seconds are not
                                 permitted to start any more times
-                                until the 10s interval ends. With
+                                until the 10 second interval ends. With
                                 these two options, this rate limiting
                                 may be modified. Use
                                 <varname>StartLimitInterval=</varname>
@@ -955,18 +962,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 manager configuration file). These
                                 configuration options are particularly
                                 useful in conjunction with
-                                <varname>Restart=</varname>, however
-                                apply to all kinds of starts
+                                <varname>Restart=</varname>; however,
+                                they apply to all kinds of starts
                                 (including manual), not just those
                                 triggered by the
                                 <varname>Restart=</varname> logic.
                                 Note that units which are configured
                                 for <varname>Restart=</varname> and
                                 which reach the start limit are not
-                                attempted to be restarted anymore,
-                                however they may still be restarted
-                                manually at a later point from which
-                                point on the restart logic is again
+                                attempted to be restarted anymore;
+                                however, they may still be restarted
+                                manually at a later point, from which
+                                point on, the restart logic is again
                                 activated. Note that
                                 <command>systemctl
                                 reset-failed</command> will cause the
@@ -990,18 +997,17 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 hit. Takes one of
                                 <option>none</option>,
                                 <option>reboot</option>,
-                                <option>reboot-force</option> or
+                                <option>reboot-force</option>, or
                                 <option>reboot-immediate</option>. If
                                 <option>none</option> is set,
                                 hitting the rate limit will trigger no
                                 action besides that the start will not
-                                be
-                                permitted. <option>reboot</option>
+                                be permitted. <option>reboot</option>
                                 causes a reboot following the normal
                                 shutdown procedure (i.e. equivalent to
-                                <command>systemctl reboot</command>),
+                                <command>systemctl reboot</command>).
                                 <option>reboot-force</option> causes
-                                an forced reboot which will terminate
+                                a forced reboot which will terminate
                                 all processes forcibly but should
                                 cause no dirty file systems on reboot
                                 (i.e. equivalent to <command>systemctl
@@ -1010,7 +1016,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 causes immediate execution of the
                                 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 system call, which might result in
-                                data loss.  Defaults to
+                                data loss. Defaults to
                                 <option>none</option>.</para></listitem>
                         </varlistentry>
 
@@ -1040,22 +1046,21 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 in relation to SysV services lacking
                                 LSB headers. This option is only
                                 necessary to fix ordering in relation
-                                to legacy SysV services, that have no
+                                to legacy SysV services that have no
                                 ordering information encoded in the
-                                script headers. As such it should only
-                                be used as temporary compatibility
-                                option, and not be used in new unit
-                                files. Almost always it is a better
+                                script headers. As such, it should only
+                                be used as a temporary compatibility
+                                option and should not be used in new unit
+                                files. Almost always, it is a better
                                 choice to add explicit ordering
                                 directives via
                                 <varname>After=</varname> or
                                 <varname>Before=</varname>,
-                                instead. For more details see
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
-                                used, pass an integer value in the
+                                instead. For more details, see
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                If used, pass an integer value in the
                                 range 0-99.</para></listitem>
                         </varlistentry>
-
                 </variablelist>
         </refsect1>