Formatting and other fixes for man pages

doc/manpages/dinit-service.5.m4

@@ -16,9 +16,9 @@ of the file corresponds to the name of the service it describes.
 .LP
 Service description files specify the various attributes of a service. A
 service description file is named after the service it represents, and is
-a plain-text file with simple key-value format. The description files are
-located in a service description directory; by default, the system process
-searches \fI/etc/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR and
+a plain-text file with simple key-value format.
+The description files are located in a service description directory; by default,
+the system process searches \fI/etc/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR and
 \fI/lib/dinit.d\fR, while a user process searches \fI$HOME/.config/dinit.d\fR.
 .LP
 All services have a \fItype\fR and a set of \fIdependencies\fR. These are discussed
@@ -37,16 +37,17 @@ accomplished by stopping the process (via sending it a signal).
 \fBBgprocess\fR services ("background process" services). This kind of
 service is similar to a regular process service, but the process daemonizes
 or otherwise forks from the original process which starts it, and the
-process ID is written to a file. Dinit can read the process ID from the
-file and, if it is running as the system init process, can supervise it.
+process ID is written to a file.
+Dinit can read the process ID from the file and, if it is running as the system
+init process, can supervise it.
 .IP \(bu
 \fBScripted\fR services are services which are started and stopped by a
-command (which need not actually be a script, despite the name). They can
-not be supervised.
+command (which need not actually be a script, despite the name).
+They can not be supervised.
 .IP \(bu
 \fBInternal\fR services do not run as an external process at all. They can
-be started and stopped without any external action. They are useful for
-grouping other services (via service dependencies).
+be started and stopped without any external action.
+They are useful for grouping other services (via service dependencies).
 .LP
 Independent of their type, the state of services can be linked to other
 services via dependency relationships, which are discussed in the next section.
@@ -54,44 +55,44 @@ services via dependency relationships, which are discussed in the next section.
 .SS SERVICE DEPENDENCIES
 .\"
 A service dependency relationship, broadly speaking, specifies that for one
-service to run, another must also be running. The first service is the
-\fIdependent\fR service and the latter is the \fIdependency\fR service (we
-will henceforth generally refer to the the dependency relationship as the
+service to run, another must also be running.
+The first service is the \fIdependent\fR service and the latter is the \fIdependency\fR
+service (we will henceforth generally refer to the the dependency relationship as the
 \fIrelationship\fR and use \fIdependency\fR to refer to the service).
 A dependency relationship is specified via the properties of the dependent.
 There are different relationship types, as follows:
 .IP \(bu
 A \fBneed\fR (or "hard") relationship specifies that the dependent must wait
 for the dependency to be started before it starts, and that the dependency
-must remain started while the dependent is started. Starting the dependent
-will start the dependency, and stopping the dependency will stop the
-dependent. This type of relationship is specified using a
-\fBdepends-on\fR property.
+must remain started while the dependent is started.
+Starting the dependent will start the dependency, and stopping the dependency will stop the
+dependent. This type of relationship is specified using a \fBdepends-on\fR property.
 .IP \(bu
 A \fBmilestone\fR relationship specifies that the dependency must
-start successfully before the dependent starts. Starting the dependent will
-therefore start the dependency. Once started, the relationship is satisfied; if the
-dependency then stops, it has no effect on the dependent. However, if the
-dependency fails to start or has its startup cancelled, the dependent will
-not start (and will return to the stopped state). This type of relationship is
-specified using a \fBdepends-ms\fR property.
+start successfully before the dependent starts.
+Starting the dependent will therefore start the dependency.
+Once started, the relationship is satisfied; if the dependency then stops, it
+has no effect on the dependent.
+However, if the dependency fails to start or has its startup cancelled, the dependent will
+not start (and will return to the stopped state).
+This type of relationship is specified using a \fBdepends-ms\fR property.
 .IP \(bu
 A \fBwaits-for\fR relationship specifies that the dependency must
-start successfully, or fail to start, before the dependent starts. Starting
-the dependent will attempt to first start the dependency, but failure will
-not prevent the dependent from starting. If the dependency starts,
-stopping it will have no effect on the dependent. This type of relationship is
-specified using a \fBwaits-for\fR property.
+start successfully, or fail to start, before the dependent starts.
+Starting the dependent will attempt to first start the dependency, but failure will
+not prevent the dependent from starting.
+If the dependency starts, stopping it will have no effect on the dependent.
+This type of relationship is specified using a \fBwaits-for\fR property.
 .LP
 Note that process-based services always wait for their dependency relationships
 to be satisfied (by the dependency starting, or failing to start in case of a waits-for
-relationship) before their process is launched. Conversely, a termination signal
-will not in general be sent to a service process until the service has no active
-dependents.
+relationship) before their process is launched.
+Conversely, a termination signal will not in general be sent to a service process until
+the service has no active dependents.
 .LP
 Since in general dependencies should remain started so long as their dependent
-does, an attachment forms between the two once both are started. This attachment
-is released when the dependent stops, and the dependency will then stop, unless
+does, an attachment forms between the two once both are started.
+This attachment is released when the dependent stops, and the dependency will then stop, unless
 it has other attachments or it has been explicitly started independently.
 Attachments between a dependent and dependency are re-created if a dependency
 starts (or starts again) while the dependent is still started.
@@ -105,8 +106,8 @@ dependencies of the service, and other service configuration.
 Each line of the file can specify a single
 property value, expressed as `\fIproperty-name\fR = \fIvalue\fR'. Comments
 begin with a hash mark (#) and extend to the end of the line (they must be
-separated from setting values by at least one whitespace character). Values
-are interpreted literally, except that:
+separated from setting values by at least one whitespace character).
+Values are interpreted literally, except that:
 .\"
 .IP \(bu
 White space (comprised of spaces, tabs, etc) is collapsed to a single space, except
@@ -114,16 +115,15 @@ leading or trailing white space around the property value, which is stripped.
 .IP \(bu
 Double quotes (") can be used around all or part of a property value, to
 prevent whitespace collapse and prevent interpretation of other special
-characters (such as "#") inside the quotes. The quote characters are not
-considered part of the property value.
+characters (such as "#") inside the quotes.
+The quote characters are not considered part of the property value.
 .IP \(bu
 A backslash (\\) can be used to escape the next character, causing it to
-lose any special meaning and become part of the property value. A double
-backslash (\\\\) is collapsed to a single backslash within the parameter
-value.
+lose any special meaning and become part of the property value.
+A double backslash (\\\\) is collapsed to a single backslash within the parameter value.
 .LP
-Setting a property generally overrides any previous setting (from prior lines). However
-some properties are set additively; these include dependency relationships and \fBoptions\fR
+Setting a property generally overrides any previous setting (from prior lines).
+However some properties are set additively; these include dependency relationships and \fBoptions\fR
 properties.
 .LP
 The following properties can be specified:
@@ -132,9 +132,8 @@ The following properties can be specified:
 Specifies the service type; see the \fBSERVICE TYPES\fR section.
 .TP
 \fBcommand\fR = \fIcommand-string\fR
-Specifies the command, including command-line arguments, for starting the
-process. Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR
-services.
+Specifies the command, including command-line arguments, for starting the process.
+Applies only to \fBprocess\fR, \fBbgprocess\fR and \fBscripted\fR services.
 .TP
 \fBstop\-command\fR = \fIcommand-string\fR
 Specifies the command to stop the service. Applicable only to \fBscripted\fR
@@ -142,171 +141,180 @@ services (and optional for such services).
 .TP
 \fBworking\-dir\fR = \fIdirectory\fR
 Specifies the working directory for this service. For a scripted service, this
-affects both the start command and the stop command. The value is subject to
-variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
+affects both the start command and the stop command.
+The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
 .TP
 \fBrun\-as\fR = \fIuser-id\fR
-Specifies which user to run the process(es) for this service as. Specify as a
-username or numeric ID. If specified by name, the group for the process will
-also be set to the primary group of the specified user.
+Specifies which user to run the process(es) for this service as.
+Specify as a username or numeric ID.
+If specified by name, the group for the process will also be set to the primary
+group of the specified user.
 .TP
 \fBenv\-file\fR = \fIfile\fR
 Specifies a file containing value assignments for environment variables, in the same
-format recognised by the \fBdinit\fR command's \fB\-\-env\-file\fR option. The file is
-read (or re-read) whenever the service is started; the values read do not
+format recognised by the \fBdinit\fR command's \fB\-\-env\-file\fR option.
+The file is read (or re-read) whenever the service is started; the values read do not
 affect for the processing performed for the \fBsub\-vars\fR load option, which is done
 when the service description is loaded.
-The precise behaviour of this setting may change in the future. It is recommended to avoid
-depending on the specified file contents being reloaded whenever the service process starts.
-
+The precise behaviour of this setting may change in the future.
+It is recommended to avoid depending on the specified file contents being reloaded
+whenever the service process starts.
+.sp
 The path specified is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
 .TP
 \fBrestart\fR = {yes | true | no | false}
 Indicates whether the service should automatically restart if it stops, including due to
-unexpected process termination or a dependency stopping. Note that if a service stops due to
-user request, automatic restart is inhibited.
+unexpected process termination or a dependency stopping.
+Note that if a service stops due to user request, automatic restart is inhibited.
 .TP
 \fBsmooth\-recovery\fR = {yes | true | no | false}
-Applies only to \fBprocess\fR and \fBbgprocess\fR services. When set true/yes,
-an automatic process restart can be performed without first stopping any
-dependent services. This setting is meaningless if the \fBrestart\fR setting
-is set to false.
+Applies only to \fBprocess\fR and \fBbgprocess\fR services.
+When set true/yes, an automatic process restart can be performed without first stopping any
+dependent services.
+This setting is meaningless if the \fBrestart\fR setting is set to false.
 .TP
 \fBrestart\-delay\fR = \fIXXX.YYYY\fR
 Specifies the minimum time (in seconds) between automatic restarts. Enforcing a sensible
-minimum prevents Dinit from consuming a large number of process cycles in
-case a process continuously fails immediately after it is started. The
-default is 0.2 (200 milliseconds).
+minimum prevents Dinit from consuming a large number of process cycles in case a process
+continuously fails immediately after it is started.
+The default is 0.2 (200 milliseconds).
 .TP
 \fBrestart\-limit\-interval\fR = \fIXXX.YYYY\fR
-Sets the interval (in seconds) over which restarts are limited. If a process
-automatically restarts more than a certain number of times (specified by the
-\fBrestart-limit-count\fR setting) in this time interval, it will not be restarted
-again. The default value is 10 seconds.
+Sets the interval (in seconds) over which restarts are limited.
+If a process automatically restarts more than a certain number of times (specified by the
+\fBrestart-limit-count\fR setting) in this time interval, it will not be restarted again.
+The default value is 10 seconds.
 .TP
 \fBrestart\-limit\-count\fR = \fINNN\fR
 Specifies the maximum number of times that a service can automatically restart
-over the interval specified by \fBrestart\-limit\-interval\fR. Specify a value
-of 0 to disable the restart limit. The default value is 3.
+over the interval specified by \fBrestart\-limit\-interval\fR.
+Specify a value of 0 to disable the restart limit.
+The default value is 3.
 .TP
 \fBstart\-timeout\fR = \fIXXX.YYY\fR
-Specifies the time in seconds allowed for the service to start. If the
-service takes longer than this, its process group is sent a SIGINT signal
+Specifies the time in seconds allowed for the service to start.
+If the service takes longer than this, its process group is sent a SIGINT signal
 and enters the "stopping" state (this may be subject to a stop timeout, as
 specified via \fBstop\-timeout\fR, after which the process group will be
-terminated via SIGKILL). The timeout period begins only when all dependencies
-have been stopped. The default timeout is 60 seconds. Specify a value of 0 to
-allow unlimited start time.
+terminated via SIGKILL).
+The timeout period begins only when all dependencies have been stopped.
+The default timeout is 60 seconds.
+Specify a value of 0 to allow unlimited start time.
 .TP
 \fBstop\-timeout\fR = \fIXXX.YYY\fR
-Specifies the time in seconds allowed for the service to stop. If the
-service takes longer than this, its process group is sent a SIGKILL signal
-which should cause it to terminate immediately. The timeout period begins
-only when all dependent services have already stopped. The default
-timeout is 10 seconds. Specify a value of 0 to allow unlimited stop time.
+Specifies the time in seconds allowed for the service to stop.
+If the service takes longer than this, its process group is sent a SIGKILL signal
+which should cause it to terminate immediately.
+The timeout period begins only when all dependent services have already stopped.
+The default timeout is 10 seconds.
+Specify a value of 0 to allow unlimited stop time.
 .TP
 \fBpid\-file\fR = \fIpath-to-file\fR
 For \fBbgprocess\fR type services only; specifies the path of the file where
-daemon will write its process ID before detaching. Dinit will read the
-contents of this file when starting the service, once the initial process
-exits, and will supervise the process with the discovered process ID. Dinit may also
-send signals to the process ID to stop the service; if \fBdinit\fR runs as a
-privileged user the path should therefore not be writable by unprivileged
-users.
-
+daemon will write its process ID before detaching.
+Dinit will read the contents of this file when starting the service, once the initial process
+exits, and will supervise the process with the discovered process ID.
+Dinit may also send signals to the process ID to stop the service; if \fBdinit\fR runs as a
+privileged user the path should therefore not be writable by unprivileged users.
+.sp
 The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
 .TP
 \fBdepends\-on\fR = \fIservice-name\fR
-This service depends on the named service. Starting this service will start
-the named service; the command to start this service will not be executed
-until the named service has started. If the named service is stopped then
-this service will also be stopped.
+This service depends on the named service.
+Starting this service will start the named service; the command to start this service will not be executed
+until the named service has started.
+If the named service is stopped then this service will also be stopped.
 .TP
 \fBdepends\-ms\fR = \fIservice-name\fR
 This service has a "milestone" dependency on the named service. Starting this
 service will start the named service; this service will not start until the
 named service has started, and will fail to start if the named service does
-not start. Once the named service reaches the started state, however, the
-dependency is effectively dropped until this service is next started.
+not start.
+Once the named (dependent) service reaches the started state, however, the
+dependency may stop without affecting the dependent service.
 .TP
 \fBwaits\-for\fR = \fIservice-name\fR
 When this service is started, wait for the named service to finish starting
 (or to fail starting) before commencing the start procedure for this service.
-Starting this service will automatically start the named service. If the
-named service fails to start, this service will start as usual (subject to
+Starting this service will automatically start the named service.
+If the named service fails to start, this service will start as usual (subject to
 other dependencies being met).
 .TP
 \fBwaits\-for.d\fR = \fIdirectory-path\fR
 For each file name in \fIdirectory-path\fR which does not begin with a dot,
-add a \fBwaits-for\fR dependency to the service with the same name. Note that
-contents of files in the specified directory are not significant; expected
+add a \fBwaits-for\fR dependency to the service with the same name.
+Note that contents of files in the specified directory are not significant; expected
 usage is to have symbolic links to the associated service description files,
-but this is not required. Failure to read the directory contents, or to find
-any of the services named within, is not considered fatal.
-
-The directory path, if not absolute, is relative to the directory containing
-the service description file.
+but this is not required.
+Failure to read the directory contents, or to find any of the services named within,
+is not considered fatal.
+.sp
+The directory path, if not absolute, is relative to the directory containing the service
+description file.
 .TP
 \fBchain\-to\fR = \fIservice-name\fR
 When this service terminates (i.e. starts successfully, and then stops of its
-own accord), the named service should be started. Note that the named service
-is not loaded until that time; naming an invalid service will not cause this
-service to fail to load.
-
+own accord), the named service should be started.
+Note that the named service is not loaded until that time; naming an invalid service will
+not cause this service to fail to load.
+.sp
 This can be used for a service that supplies an interactive "recovery mode"
 for another service; once the user exits the recovery shell, the primary
-service (as named via this setting) will then start. It also supports
-multi-stage system startup where later service description files reside on
+service (as named via this setting) will then start.
+It also supports multi-stage system startup where later service description files reside on
 a separate filesystem that is mounted during the first stage; such service
 descriptions will not be found at initial start, and so cannot be started
 directly, but can be chained via this directive.
-
+.sp
 The chain is not executed if the initial service was explicitly stopped,
 stopped due to a dependency stopping (for any reason), if it will restart
 (including due to a dependent restarting), or if its process terminates
-abnormally or with an exit status indicating an error. However, if the
-\fBalways-chain\fR option is set the chain is started regardless of the
+abnormally or with an exit status indicating an error.
+However, if the \fBalways-chain\fR option is set the chain is started regardless of the
 reason and the status of this service termination.
 .TP
 \fBsocket\-listen\fR = \fIsocket-path\fR
 Pre-open a socket for the service and pass it to the service using the
-\fBsystemd\fR activation protocol. This by itself does not give so called
-"socket activation", but does allow any process trying to connect to the
-specified socket to do so immediately after the service is started
-(even before the service process is properly prepared to accept connections).
-
+\fBsystemd\fR activation protocol.
+This by itself does not give so called "socket activation", but does allow any
+process trying to connect to the specified socket to do so immediately after
+the service is started (even before the service process is properly prepared
+to accept connections).
+.sp
 The path value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
 .TP
 \fBsocket\-permissions\fR = \fIoctal-permissions-mask\fR
 Gives the permissions for the socket specified using \fBsocket\-listen\fR.
 Normally this will be 600 (user access only), 660 (user and group
-access), or 666 (all users). The default is 666.
+access), or 666 (all users).
+The default is 666.
 .TP
 \fBsocket\-uid\fR = {\fInumeric-user-id\fR | \fIusername\fR}
-Specifies the user (name or numeric ID) that should own the activation socket. If
-\fBsocket\-uid\fR is specified as a name without also specifying \fBsocket-gid\fR, then
+Specifies the user (name or numeric ID) that should own the activation socket.
+If \fBsocket\-uid\fR is specified as a name without also specifying \fBsocket-gid\fR, then
 the socket group is the primary group of the specified user (as found in the
-system user database, normally \fI/etc/passwd\fR). If the \fBsocket\-uid\fR setting is
-not provided, the socket will be owned by the user id of the \fBdinit\fR process.
+system user database, normally \fI/etc/passwd\fR).
+If the \fBsocket\-uid\fR setting is not provided, the socket will be owned by the user id of the \fBdinit\fR process.
 .TP
 \fBsocket\-gid\fR = {\fInumeric-group-id\fR | \fIgroup-name\fR}
-Specifies the group of the activation socket. See discussion of
-\fBsocket\-uid\fR.
+Specifies the group of the activation socket. See discussion of \fBsocket\-uid\fR.
 .TP
 \fBterm\-signal\fR = {none | HUP | INT | TERM | QUIT | USR1 | USR2 | KILL}
 Specifies the signal to send to the process when requesting it
-to terminate (applies to `process' and `bgprocess' services only). The default is SIGTERM.
+to terminate (applies to `process' and `bgprocess' services only).
+The default is SIGTERM.
 See also \fBstop\-timeout\fR.
 .TP
 \fBready\-notification\fR = {\fBpipefd:\fR\fIfd-number\fR | \fBpipevar:\fR\fIenv-var-name\fR}
 Specifies the mechanism, if any, by which a process service will notify that it is ready
-(successfully started). If not specified, a process service is considered started as soon as it
-has begun execution. The two options are:
+(successfully started).
+If not specified, a process service is considered started as soon as it has begun execution.
+The two options are:
 .RS
 .IP \(bu
 \fBpipefd:\fR\fIfd-number\fR \(em the service will write a message to the specified file descriptor,
-which \fBdinit\fR sets up as the write end of a pipe before execution. This mechanism is compatible
-with the S6 supervision suite.
+which \fBdinit\fR sets up as the write end of a pipe before execution.
+This mechanism is compatible with the S6 supervision suite.
 .IP \(bu
 \fBpipevar:\fR\fIenv-var-name\fR \(em the service will write a message to file descriptor identified
 using the contents of the specified environment variable, which will be set by \fBdinit\fR before
@@ -314,70 +322,80 @@ execution to a file descriptor (chosen arbitrarily) attached to the write end of
 .RE
 .TP
 \fBlogfile\fR = \fIlog-file-path\fR
-Specifies the log file for the service. Output from the service process (standard output and
-standard error streams) will be appended to this file. This setting has no effect if the service
-is set to run on the console (via the \fBruns\-on\-console\fR, \fBstarts\-on\-console\fR, or
-\fBshares\-console\fR options). The value is subject to variable substitution
-(see \fBVARIABLE SUBSTITUTION\fR).
+Specifies the log file for the service.
+Output from the service process (standard output and standard error streams) will be appended to this file.
+This setting has no effect if the service is set to run on the console (via the \fBruns\-on\-console\fR,
+\fBstarts\-on\-console\fR, or \fBshares\-console\fR options).
+The value is subject to variable substitution (see \fBVARIABLE SUBSTITUTION\fR).
 .TP
 \fBoptions\fR = \fIoption\fR...
-Specifies various options for this service. See the \fBOPTIONS\fR section. This
-directive can be specified multiple times to set additional options.
+Specifies various options for this service. See the \fBOPTIONS\fR section.
+This directive can be specified multiple times to set additional options.
 .TP
 \fBload\-options\fR = \fIload_option\fR...
-Specifies options for interpreting other settings when loading this service description. Currently
-there is only one available option, \fBsub\-vars\fR, which specifies that command-line arguments
+Specifies options for interpreting other settings when loading this service description.
+Currently there is only one available option, \fBsub\-vars\fR, which specifies that command-line arguments
 (or parts thereof) in the form of \fB$NAME\fR should be replaced with the contents of the
-environment variable with the specified name. See \fBVARIABLE SUBSTITUTION\fR for details. Note
-command-line variable substitution occurs after splitting the line into separate arguments and so
-a single environment cannot be used to add multiple arguments to a command line. If a designated
-variable is not defined, it is replaced with an empty (zero-length) string, possibly producing a
-zero-length argument. Environment variable variables are taken from the environment of the \fBdinit\fR
-process, and values specified via \fBenv\-file\fR or \fBready\-notification\fR are not available.
+environment variable with the specified name.
+See \fBVARIABLE SUBSTITUTION\fR for details.
+Note command-line variable substitution occurs after splitting the line into separate arguments and so
+a single environment cannot be used to add multiple arguments to a command line.
+If a designated variable is not defined, it is replaced with an empty (zero-length) string, possibly producing a
+zero-length argument.
+Environment variable variables are taken from the environment of the \fBdinit\fR process, and values
+specified via \fBenv\-file\fR or \fBready\-notification\fR are not available.
 This functionality is likely to be re-worked or removed in the future; use of this option should
 be avoided if possible.
 .TP
 \fBinittab\-id\fR = \fIid-string\fR
 When this service is started, if this setting (or the \fBinittab\-line\fR setting) has a
 specified value, an entry will be created in the system "utmp" database which tracks
-processes and logged-in users. Typically this database is used by the "who" command to
-list logged-in users. The entry will be cleared when the service terminates.
-
+processes and logged-in users.
+Typically this database is used by the "who" command to list logged-in users.
+The entry will be cleared when the service terminates.
+.sp
 The \fBinittab\-id\fR setting specifies the "inittab id" to be written in the entry for
-the process. The value is normally quite meaningless. However, it should be distinct
-(or unset) for separate processes. It is typically limited to a very short length.
-
-The "utmp" database is mostly a historical artifact. Access to it on some systems is
-prone to denial-of-service by unprivileged users. It is therefore recommended that this
-setting not be used. However, "who" and similar utilities may not work correctly without
-this setting (or \fBinittab\-line\fR) enabled appropriately.
-
+the process.
+The value is normally quite meaningless.
+However, it should be distinct (or unset) for separate processes.
+It is typically limited to a very short length.
+.sp
+The "utmp" database is mostly a historical artifact.
+Access to it on some systems is prone to denial-of-service by unprivileged users.
+It is therefore recommended that this setting not be used.
+However, "who" and similar utilities may not work correctly without this setting
+(or \fBinittab\-line\fR) enabled appropriately.
+.sp
 This setting has no effect if Dinit was not built with support for writing to the "utmp"
 database.
 .TP
 \fBinittab\-line\fR = \fItty-name-string\fR
 This specifies the tty line that will be written to the "utmp" database when this service
-is started. Normally, for a terminal login service, it would match the terminal device name
-on which the login process runs, without the "/dev/" prefix.
-
+is started.
+Normally, for a terminal login service, it would match the terminal device name on which
+the login process runs, without the "/dev/" prefix.
+.sp
 See the description of the \fBinittab\-id\fR setting for details.
 .TP
 \fBrlimit\-nofile\fR = \fIresource-limits\fR
-Specifies the number of file descriptors that a process may have open simultaneously. See the
-\fBRESOURCE LIMITS\fR section.
+Specifies the number of file descriptors that a process may have open simultaneously.
+See the \fBRESOURCE LIMITS\fR section.
 .TP
 \fBrlimit\-core\fR = \fIresource-limits\fR
 Specifies the maximum size of the core dump file that will be generated for the process if it
-crashes (in a way that would result in a core dump). See the \fBRESOURCE LIMITS\fR section.
+crashes (in a way that would result in a core dump).
+See the \fBRESOURCE LIMITS\fR section.
 .TP
 \fBrlimit\-data\fR = \fIresource-limits\fR
 Specifies the maximum size of the data segment for the process, including statically allocated
-data and heap allocations. Precise meaning may vary between operating systems. See the
-\fBRESOURCE LIMITS\fR section.
+data and heap allocations.
+Precise meaning may vary between operating systems.
+See the \fBRESOURCE LIMITS\fR section.
 .TP
 \fBrlimit\-addrspace\fR = \fIresource-limits\fR
-Specifies the maximum size of the address space of the process. See the \fBRESOURCE LIMITS\fR
-section. Note that some operating systems (notably OpenBSD) do not support this limit; the
+Specifies the maximum size of the address space of the process.
+See the \fBRESOURCE LIMITS\fR section.
+Note that some operating systems (notably, OpenBSD) do not support this limit; the
 setting will be ignored on such systems.
 .\"
 .SS OPTIONS
@@ -388,23 +406,25 @@ These options are specified via the \fBoptions\fR parameter.
 \fBruns\-on\-console\fR
 Specifies that this service uses the console; its input and output should be
 directed to the console (or precisely, to the device to which Dinit's standard
-output stream is connected). A service running on the console prevents other
-services from running on the console (they will queue for the console).
-
+output stream is connected).
+A service running on the console prevents other services from running on the
+console (they will queue for the console).
+.sp
 Proper operation of this option (and related options) assumes that \fBdinit\fR
 is itself attached correctly to the console device (or a terminal, in which case
 that terminal will be used as the "console").
-
+.sp
 The \fIinterrupt\fR key (normally control-C) will be active for process / scripted
-services that run on the console. Handling of an interrupt is determined by
-the service process, but typically will cause it to terminate.
+services that run on the console.
+Handling of an interrupt is determined by the service process, but typically will
+cause it to terminate.
 .TP
 \fBstarts\-on\-console\fR
-Specifies that this service uses the console during service startup. This is identical
-to \fBruns\-on\-console\fR except that the console will be released (available for running
-other services) once the service has started. It is applicable only for \fBbgprocess\fR
-and \fBscripted\fR services.
-
+Specifies that this service uses the console during service startup.
+This is identical to \fBruns\-on\-console\fR except that the console will be released
+(available for running other services) once the service has started.
+It is applicable only for \fBbgprocess\fR and \fBscripted\fR services.
+.sp
 As for the \fBruns\-on\-console\fR option, the \fIinterrupt\fR key will be enabled
 while the service has the console.
 .TP
@@ -413,43 +433,43 @@ Specifies that this service should be given access to the console (input and out
 will be connected to the console), but that it should not exclusively hold the
 console. A service given access to the console in this way will not delay the startup of services
 which require exclusive access to the console (see \fBstarts\-on\-console\fR,
-\fBruns\-on\-console\fR) nor will it be delayed if such services are already running.
-
+\fBruns\-on\-console\fR) nor will it be itself delayed if such services are already running.
+.sp
 This is mutually exclusive with both \fBstarts\-on\-console\fR and \fBruns\-on\-console\fR;
 setting this option unsets both those options, and setting either of those options unsets
 this option.
 .TP
 \fBstarts\-rwfs\fR
 This service mounts the root filesystem read/write (or at least mounts the
-normal writable filesystems for the system). This prompts Dinit to create its
-control socket, if it has not already managed to do so.
+normal writable filesystems for the system).
+This prompts Dinit to create its control socket, if it has not already managed to do so.
 .TP
 \fBstarts\-log\fR
-This service starts the system log daemon. Dinit will begin logging via the
-\fI/dev/log\fR socket.
+This service starts the system log daemon.
+Dinit will begin logging via the \fI/dev/log\fR socket.
 .TP
 \fBpass\-cs\-fd\fR
 Pass an open Dinit control socket to the process when launching it (the
 \fIDINIT_CS_FD\fR environment variable will be set to the file descriptor of
-the socket). This allows the service to issue commands to Dinit even if the
-regular control socket is not available yet.
-
+the socket).
+This allows the service to issue commands to Dinit even if the regular control socket is not available yet.
+.sp
 Using this option has security implications! The service which receives the
-control socket must close it before launching any untrusted processes. You
-should not use this option unless the service is designed to receive a Dinit
+control socket must close it before launching any untrusted processes.
+You should not use this option unless the service is designed to receive a Dinit
 control socket.
 .TP
 \fBstart\-interruptible\fR
 This service can have its startup interrupted (cancelled) if it becomes inactive
-while still starting, by sending it the SIGINT signal. This is meaningful only
-for \fBbgprocess\fR and \fBscripted\fR services.
+while still starting, by sending it the SIGINT signal.
+This is meaningful only for \fBbgprocess\fR and \fBscripted\fR services.
 .TP
 \fBskippable\fR
 For scripted services, indicates that if the service startup process terminates
 via an interrupt signal (SIGINT), then the service should be considered started.
 Note that if the interrupt was issued by Dinit to cancel startup, the service
 will instead be considered stopped.
-
+.sp
 This can be combined with options such as \fBstarts\-on\-console\fR to allow
 skipping certain non-essential services (such as filesystem checks) using the
 \fIinterrupt\fR key (typically control-C).
@@ -470,36 +490,40 @@ parameters and options described above.
 .SS RESOURCE LIMITS
 .\"
 There are several settings for specifying process resource limits: \fBrlimit\-nofile\fR,
-\fBrlimit\-core\fR, \fBrlimit\-data\fR and \fBrlimit\-addrspace\fR. See the descriptions
-of each above. These settings place a limit on resource usage directly by the process.
+\fBrlimit\-core\fR, \fBrlimit\-data\fR and \fBrlimit\-addrspace\fR.
+See the descriptions of each above.
+These settings place a limit on resource usage directly by the process.
 Note that resource limits are inherited by subprocesses, but that usage of a resource
 and subprocess are counted separately (in other words, a process can effectively bypass
 its resource limits by spawning a subprocess and allocating further resources within it).
-
-Resources have both a \fIhard\fR and \fIsoft\fR limit. The soft limit is the effective
-limit, but note that a process can raise its soft limit up to the hard limit for any
-given resource. Therefore the soft limit acts more as a sanity-check; a process can
-exceed the soft limit only by deliberately raising it first.
-
+.sp
+Resources have both a \fIhard\fR and \fIsoft\fR limit.
+The soft limit is the effective limit, but note that a process can raise its soft limit up
+to the hard limit for any given resource.
+Therefore the soft limit acts more as a sanity-check; a process can exceed the soft limit
+only by deliberately raising it first.
+.sp
 Resource limits are specified in the following format:
-
+.sp
 .RS
 \fIsoft-limit\fR:\fIhard-limit\fR
 .RE
-
+.sp
 Either the soft limit or the hard limit can be omitted (in which case it will be unchanged).
-A limit can be specified as a dash, `\fB\-\fR', in which case the limit will be removed. If
-only one value is specified with no colon separator, it affects both the soft and hard limit.
+A limit can be specified as a dash, `\fB\-\fR', in which case the limit will be removed.
+If only one value is specified with no colon separator, it affects both the soft and hard limit.
 .\"
 .SS VARIABLE SUBSTITUTION
 .\"
-Some service properties specify a path to a file or directory, or a command line. For these properties, the specified
-value may contain one or more environment variable names, each preceded by a single `\fB$\fR' character, as in `\fB$NAME\fR'.
-In each case the value of the named environment variable will be substituted. The name must begin with a non-punctuation,
-non-space, non-digit character, and ends before the first control character, space, or punctuation
-character other than `\fB.\fR', `\fB\-\fR' or `\fB_\fR'. To avoid substitution, a single `\fB$\fR'
-can be escaped with a second, as in `\fB$$\fR'.
-
+Some service properties specify a path to a file or directory, or a command line.
+For these properties, the specified value may contain one or more environment
+variable names, each preceded by a single `\fB$\fR' character, as in `\fB$NAME\fR'.
+In each case the value of the named environment variable will be substituted.
+The name must begin with a non-punctuation, non-space, non-digit character, and ends
+before the first control character, space, or punctuation character other than `\fB.\fR',
+`\fB\-\fR' or `\fB_\fR'.
+To avoid substitution, a single `\fB$\fR' can be escaped with a second, as in `\fB$$\fR'.
+.sp
 Variables for substitution come from the \fBdinit\fR environment at the time the service is loaded.
 In particular, variables set via \fBenv\-file\fR are not visible to the substitution function.
 .\"
@@ -508,7 +532,7 @@ In particular, variables set via \fBenv\-file\fR are not visible to the substitu
 Here is an example service description for the \fBmysql\fR database server.
 It has a dependency on the \fBrcboot\fR service (not shown) which is
 expected to have set up the system to a level suitable for basic operation.
-
+.sp
 .RS
 .nf
 .gcolor blue
@@ -526,13 +550,13 @@ depends-on = rcboot # Basic system services must be ready
 .fi
 .LP
 Here is an examples for a filesystem check "service", run by a script
-(\fI/etc/dinit.d/rootfscheck.sh\fR). The script may need to reboot the
-system, but the control socket may not have been created, so it uses the
-\fBpass-cs-fd\fR option to allow the \fBreboot\fR command to issue control
-commands to Dinit. It runs on the console, so that output is visible and
-the process can be interrupted using control-C, in which case the check is
-skipped but dependent services continue to start.
-
+(\fI/etc/dinit.d/rootfscheck.sh\fR).
+The script may need to reboot the system, but the control socket may not have been
+created, so it uses the \fBpass-cs-fd\fR option to allow the \fBreboot\fR command
+to issue control commands to Dinit.
+It runs on the console, so that output is visible and the process can be interrupted
+using control-C, in which case the check is skipped but dependent services continue to start.
+.sp
 .RS
 .nf
 .gcolor blue
@@ -549,7 +573,7 @@ depends-on = device-node-daemon
 .gcolor
 .fi
 .RE
-
+.sp
 More examples are provided with the Dinit distribution.
 .\"
 .SH AUTHOR

doc/manpages/dinit.8.m4

@@ -19,80 +19,81 @@ dinit \- supervise processes and manage services
 .SH DESCRIPTION
 .\"
 \fBDinit\fR is a process supervisor and service manager which can also
-function as a system \fBinit\fR process. It has a small but functional
-feature set, offering service dependency handling, parallel startup,
-automatic rate-limited restart of failing processes, and service control
-functions.
-
+function as a system \fBinit\fR process.
+It has a small but functional feature set, offering service dependency handling, parallel startup,
+automatic rate-limited restart of failing processes, and service control functions.
+.LP
 Dinit can be run as a system instance (when run as the root user or when
-specified via command line parameter) or as a user instance. This affects
-the default paths used to locate certain files.
-
-When run as PID 1, the first process, Dinit acts as a system manager and
-shuts down or reboots the system on request (including on receipt of
-certain signals). This is currently fully supported only on Linux. See
-\fBRUNNING AS SYSTEM MANAGER / PRIMARY INIT\fR.
-
+specified via command line parameter) or as a user instance.
+This affects the default paths used to locate certain files.
+.LP
+When run as PID 1, the first process, Dinit by default acts as a system manager and
+shuts down or reboots the system on request (including on receipt of certain signals).
+This is currently fully supported only on Linux.
+See \fBRUNNING AS SYSTEM MANAGER / PRIMARY INIT\fR.
+.LP
 Dinit reads service descriptions from files located in a service
 description directory, normally one of \fI/etc/dinit.d\fR,
 \fI/usr/local/lib/dinit.d\fR or \fI/lib/dinit.d\fR for the system instance
-or just \fI$HOME/.config/dinit.d\fR when run as a user process. See \fBSERVICE
-DESCRIPTION FILES\fR for details of the service description format.
+or just \fI$HOME/.config/dinit.d\fR when run as a user process.
+See \fBSERVICE DESCRIPTION FILES\fR for details of the service description format.
 .\"
 .SH OPTIONS
 .TP
 \fB\-d\fR \fIdir\fP, \fB\-\-services\-dir\fR \fIdir\fP
-Specifies \fIdir\fP as the directory containing service definition files, can
-be set multiple times. Default directories are not searched for services when
-this option is provided.
-
+Specifies \fIdir\fP as the directory containing service definition files.
+This can be specified multiple times for multiple service directories.
+The default directories are not searched for services when this option is provided.
+.sp
 If not specified, the default is \fI$HOME/.config/dinit.d\fR or, for the
 system service manager, each of \fI/etc/dinit.d\fR, \fI/usr/local/lib/dinit.d\fR,
 and \fI/lib/dinit.d\fR (searched in that order).
 .TP
 \fB\-e\fR \fIfile\fP, \fB\-\-env\-file\fR \fIfile\fP
-Read initial environment from \fIfile\fP. For the system init process, the
-default is \fI/etc/dinit/environment\fR; see \fBFILES\fR.
+Read initial environment from \fIfile\fP.
+For the system init process, the default is \fI/etc/dinit/environment\fR; see \fBFILES\fR.
 .TP
 \fB\-p\fR \fIpath\fP, \fB\-\-socket\-path\fR \fIpath\fP
 Specifies \fIpath\fP as the path to the control socket used to listen for
-commands from the \fBdinitctl\fR program. The default for the system service
-manager is usually \fI/dev/dinitctl\fR (but can be configured at build time).
+commands from the \fBdinitctl\fR program.
+The default for the system service manager is usually \fI/dev/dinitctl\fR (but can be configured at build time).
 For a user service manager the default is either \fI$XDG_RUNTIME_DIR/dinitctl\fR
 or \fI$HOME/.dinitctl\fR, depending on whether \fI$XDG_RUNTIME_DIR\fR is set.
 .TP
 \fB\-l\fR \fIpath\fP, \fB\-\-log\-file\fR \fIpath\fP
 Species \fIpath\fP as the path to the log file, to which Dinit will log status
-and error messages. Note that when running as the system service manager, Dinit
-does not begin logging until the log service has started. Using this option
-inhibits logging via the syslog facility, however, all logging messages are
+and error messages.
+Note that when running as the system service manager, Dinit
+does not begin logging until the log service has started.
+Using this option inhibits logging via the syslog facility, however, all logging messages are
 duplicated as usual to the console (so long as no service owns the console).
 .TP
 \fB\-s\fR, \fB\-\-system\fR
-Run as the system service manager. This is the default if invoked as the root
-user. This option affects the default service definition directory and control
-socket path.
+Run as the system service manager.
+This is the default if invoked as the root user.
+This option affects the default service definition directory and control socket path.
 .TP
 \fB\-m\fR, \fB\-\-system\-mgr\fR
 Run as the system manager (perform operations directly related to machine startup
-and shutdown). This is the default when running as process ID 1. The main user-visible
-effect of this option is to invoke the \fBshutdown\fR program when a shutdown is
+and shutdown).
+This is the default when running as process ID 1.
+The main user-visible effect of this option is to invoke the \fBshutdown\fR program when a shutdown is
 requested (and after all services have stopped), and to provide some basic support
 for system recovery in case the \fBboot\fR service (or other specified service)
 cannot be started.
 .TP
 \fB\-u\fR, \fB\-\-user\fR
-Run as a user. This is the opposite of \fB\-\-system\fR, and is the default if
-not invoked as the root user.
+Run as a user service manager.
+This is the opposite of \fB\-\-system\fR, and is the default if not invoked as the root user.
 .TP
 \fB\-o\fR, \fB\-\-container\fR
 Run in "container mode", i.e. do not perform system management functions (such
-as shutdown/reboot). The \fBdinit\fR daemon will simply exit rather than executing
-the \fBshutdown\fR program.
+as shutdown/reboot).
+The \fBdinit\fR daemon will simply exit rather than executing the \fBshutdown\fR program.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Run with no output to the terminal/console. This disables service status messages
-and sets the log level for the console log to \fBNONE\fR.
+Run with no output to the terminal/console.
+This disables service status messages and sets the log level for the console log to \fBNONE\fR.
 .TP
 \fB\-\-help\fR
 Display brief help text and then exit.
@@ -101,95 +102,96 @@ Display version number and then exit.
 .TP
 \fIservice-name\fR
 Specifies the name of a service that should be started (along with its
-dependencies). If none are specified, defaults to \fIboot\fR (which requires
-that a suitable service description for the \fIboot\fR service exists).
-
+dependencies).
+If none are specified, defaults to \fIboot\fR (which requires that a suitable service description
+for the \fIboot\fR service exists).
+.sp
 \fBNote:\fR on Linux, if \fBdinit\fR is running as PID 1 and with UID 0, it will ignore
 service names provided on the command line, other than "single", unless they appear
-after a "-o" or "-m" options (or their long forms). This is to filter arguments
-that were intended for the kernel and not for \fBinit\fR. If running in a container,
-the "-o" option should be used regardless and will inhibit this filtering for any
-subsequent service names.
+anywhere after the "\-o" or "\-m" options (or their long forms).
+This is to filter arguments that were intended for the kernel and not for \fBinit\fR.
+If running in a container, the "\-o" option should be used regardless and will inhibit this
+filtering for any subsequent service names.
 .\"
 .SH SERVICE DESCRIPTION FILES
 .\"
-Service description files specify the parameters of each service. They are
-named for the service they describe, and are found in \fI/etc/dinit.d\fR
+Service description files specify the parameters of each service.
+They are named for the service they describe, and are found in \fI/etc/dinit.d\fR
 for a system instance or \fI$HOME/.config/dinit.d\fR for a user instance.
-
-Service description files are read by Dinit on an "as needed" basis. Once a
-service description has been read the configuration can be altered in limited
+.LP
+Service description files are read by Dinit on an "as needed" basis.
+Once a service description has been read the configuration can be altered in limited
 ways via the \fBdinitctl\fR(8) program.
-
+.LP
 See \fBdinit-service\fR(5) for details of the format and available parameters.
 .\"
 .SH SPECIAL SERVICE NAMES
 .\"
 There are two service names that are "special" to Dinit.
-
+.LP
 The \fIboot\fR service is the service that Dinit starts by default, if no
 other service names are provided when it is started.
-
+.LP
 The \fIrecovery\fR service is a service that Dinit will offer to start if
 boot appears to fail (that is, if all services stop without a shutdown command
 having been issued), when Dinit is running as system manager.
 .\"
 .SH OPERATION
 .\"
-On starting, Dinit starts the initial service(s) as specified on the command
-line. Starting a service also causes the dependencies of that service to
-start, and any service processes will not be launched until the dependencies
-are satisfied. Similarly, stopping a service first stops any dependent
-services.
-
+On starting, Dinit starts the initial service(s) as specified on the command line.
+Starting a service also causes the dependencies of that service to start, and any service
+processes will not be launched until the dependencies are satisfied.
+Similarly, stopping a service first stops any dependent services.
+.LP
 During execution, Dinit accepts commands via a control socket which is created
-by Dinit when it starts. This can be used to order that a service be started
-or stopped, to determine service status, or to make certain configuration
-changes. See \fBdinitctl\fR(8) for details. Dinit attempts to check for the
-existence of an already-active socket first, and will refuse to start if one
-exists. Unfortunately, this check cannot be done atomically, and should not be
-relied upon generally as a means to avoid starting two instances of dinit.
-
-Process-based services are monitored and, if the process terminates, the
-service may be stopped or the process may be re-started, according to the
-configuration in the service description.
-
+by Dinit when it starts.
+This can be used to order that a service be started or stopped, to determine service status, or to
+make certain configuration changes.
+See \fBdinitctl\fR(8) for details.
+Dinit attempts to check for the existence of an already-active socket first, and will refuse to
+start if one exists.
+Unfortunately, this check cannot be done atomically, and should not be relied upon generally as a
+means to avoid starting two instances of dinit.
+.LP
+Process-based services are monitored and, if the process terminates, the service may be stopped or
+the process may be re-started, according to the configuration in the service description.
+.LP
 Once all services stop, the \fBdinit\fR daemon will itself terminate (or, if
-running as PID 1, will perform the appropriate type of system shutdown).
+running as system manager, will perform the appropriate type of system shutdown).
 .\"
 .SS CHARACTER SET HANDLING
 .\"
-Dinit does no character set translation. Dinit's own output is in the execution
-character set as determined at compilation, as is the interpretation of input.
-Service names (and other user-defined inputs) are interpreted as byte sequences
-and are output as they were read. In general, modern systems use the UTF-8
-character set universally and no problems will arise; however, systems configured
-to use other character sets may see odd behaviour if the input character set does
-not match the output character set, or if either input or output character sets
+Dinit does no character set translation.
+Dinit's own output is in the execution character set as determined at compilation, as is the interpretation of input.
+Service names (and other user-defined inputs) are interpreted as byte sequences and are output as they were read.
+In general, modern systems use the UTF-8 character set universally and no problems will arise;
+however, systems configured to use other character sets may see odd behaviour if the input
+character set does not match the output character set, or if either input or output character sets
 are not a superset of the execution character set.
 .\"
 .SS RUNNING AS SYSTEM MANAGER / PRIMARY INIT
 .\"
 Running as the system manager (primary \fBinit\fR) is currently supported only on
-Linux. When run as process ID 1, the \fBdinit\fR daemon assumes responsibility for
+Linux.
+When run as process ID 1, the \fBdinit\fR daemon by default assumes responsibility for
 system shutdown and restart (partially relying on external utilities which are
 part of the Dinit distribution).
-
-When not running as process ID 1, \fBdinit\fR assumes responsibility only for
-service management. System shutdown or restart need to be handled by the primary
-\fBinit\fR, which should start \fBdinit\fR on normal startup, and terminate
-\fBdinit\fR before shutdown, by signalling it and waiting for it to terminate
-after stopping services (possibly by invoking \fBdinitctl shutdown\fR).
+.LP
+When not running as a system manager, \fBdinit\fR assumes responsibility only for
+service management.
+System shutdown or restart need to be handled by the primary \fBinit\fR, which should start
+\fBdinit\fR on normal startup, and terminate \fBdinit\fR before shutdown, by signalling it and
+waiting for it to terminate after stopping services (possibly by invoking \fBdinitctl shutdown\fR).
 .\"
 .SH FILES
 .\"
 .TP
 \fI/etc/dinit/environment\fR
 Default location of the environment file for Dinit when run as a system
-instance (for user instances there is no default). Values are specified as
-\fINAME\fR=\fIVALUE\fR, one per line, and add to and replace variables present
-in the environment when Dinit started. Lines beginning with a hash character
-(#) are ignored.
+instance (for user instances there is no default).
+Values are specified as \fINAME\fR=\fIVALUE\fR, one per line, and add to and replace variables present
+in the environment when Dinit started.
+Lines beginning with a hash character (#) are ignored.
 .\"
 .SH SIGNALS
 .LP

doc/manpages/dinitcheck.8.m4

@@ -38,7 +38,7 @@ same search paths (for service description files) as \fBdinit\fR.
 Specifies \fIdir\fP as the directory containing service definition files (can
 be given multiple times to specify multiple service directories).
 Default directories are not searched for services when this option is provided.
-
+.sp
 If not specified, the default is \fI$HOME/.config/dinit.d\fR or, for the
 system service manager, each of \fI/etc/dinit.d/fR, \fI/usr/local/lib/dinit.d\fR,
 and \fI/lib/dinit.d\fR (searched in that order).
@@ -48,16 +48,17 @@ Display brief help text and then exit.
 .TP
 \fIservice-name\fR
 Specifies the name of a service that should be checked (along with its
-dependencies). If none are specified, defaults to \fIboot\fR (which requires
-that a suitable service description for the \fIboot\fR service exists).
+dependencies).
+If none are specified, defaults to \fIboot\fR (which requires that a suitable
+service description for the \fIboot\fR service exists).
 .\"
 .SH NOTES
 .\"
 For service properties that are subject to environment variable substitution, including
 \fBsocket\-listen\fR, \fBlogfile\fR, \fBenv\-file\fR, \fBworking\-dir\fR and \fBpid\-file\fR, the
 substitution may have a different result when performed by \fBdinitcheck\fR than when performed by
-\fBdinit\fR if the two processes have a different environment. For this reason \fBdinitcheck\fR will issue a
-warning whenever substitution is used.
+\fBdinit\fR if the two processes have a different environment.
+For this reason \fBdinitcheck\fR will issue a warning whenever substitution is used.
 .\"
 .SH SEE ALSO
 .\"

doc/manpages/dinitctl.8.m4

@@ -62,9 +62,9 @@ dinitctl \- control services supervised by Dinit
 .SH DESCRIPTION
 .\"
 \fBdinitctl\fR is a utility to control services being managed by the
-\fBdinit\fR daemon. It allows starting and stopping services, and listing
-service status, amongst other actions. It functions by issuing commands to the daemon
-via a control socket.
+\fBdinit\fR daemon.
+It allows starting and stopping services, and listing service status, amongst other actions.
+It functions by issuing commands to the daemon via a control socket.
 .\"
 .SH GENERAL OPTIONS
 .TP
@@ -75,13 +75,13 @@ Display brief help text and then exit.
 Display version and then exit.
 .TP
 \fB\-s\fR, \fB\-\-system\fR
-Control the system init process (this is the default when run as root). This option determines
-the default path to the control socket used to communicate with the \fBdinit\fR daemon
+Control the system init process (this is the default when run as root).
+This option determines the default path to the control socket used to communicate with the \fBdinit\fR daemon
 process (it does not override the \fB\-p\fR option).
 .TP
 \fB\-u\fR, \fB\-\-user\fR
-Control the user init process (this is the default when not run as root). This option determines
-the default path to the control socket used to communicate with the \fBdinit\fR daemon process
+Control the user init process (this is the default when not run as root).
+This option determines the default path to the control socket used to communicate with the \fBdinit\fR daemon process
 (it does not override the \fB\-p\fR option).
 .TP
 \fB\-\-socket\-path\fR \fIsocket-path\fR, \fB\-p\fR \fIsocket-path\fR
@@ -99,19 +99,20 @@ Do not wait for issued command to complete; exit immediately.
 .TP
 \fB\-\-pin\fR
 Pin the service in the requested state. The service will not leave the state until it is unpinned.
-
+.sp
 A service that is pinned stopped cannot be marked active, that is, start commands issued to the
-service have no effect. Dependents (via hard dependency relationships) of the pinned service will
-be unable to start.
-
+service have no effect.
+Dependents (via hard dependency relationships) of the pinned service will be unable to start.
+.sp
 A service that is pinned started cannot be stopped, however its explicit activation can be removed
-(eg via the \fBstop\fR or \fBrelease\fR commands). Once unpinned, a service which is not explicitly
-activated, and which has no active dependents, will automatically stop. If a pinned-started service
-fails to start, the pin is removed.
-
+(eg via the \fBstop\fR or \fBrelease\fR commands).
+Once unpinned, a service which is not explicitly activated, and which has no active dependents,
+will automatically stop. If a pinned-started service fails to start, the pin is removed.
+.sp
 Note that a pin takes effect while the service is starting/stopping, before it reaches the target
-state. For example, issuing a stop command to a service which is starting and which is pinned
-started will have no effect other than removing explicit activation.
+state.
+For example, issuing a stop command to a service which is starting and which is pinned started
+will have no effect other than removing explicit activation.
 .TP
 \fB\-\-force\fR
 Stop the service even if it will require stopping other services which depend on the specified service.
@@ -124,28 +125,29 @@ success.
 Specifies the name of the service to which the command applies.
 .TP
 \fBstart\fR
-Start the specified service. The service is marked as explicitly activated and will not be stopped
-automatically if its dependents stop. If the service is currently stopping it will generally continue
-to stop before it is then restarted.
+Start the specified service.
+The service is marked as explicitly activated and will not be stopped automatically if its dependents stop.
+If the service is currently stopping it will generally continue to stop before it is then restarted.
 .TP
 \fBstop\fR
-Stop the specified service, and remove explicit activation. If the service has (non-soft) dependents, an
-error will be displayed unless the \fB\-\-force\fR option is used.
-
+Stop the specified service, and remove explicit activation.
+If the service has (non-soft) dependents, an error will be displayed unless the \fB\-\-force\fR option is used.
+.sp
 The \fBrestart\fR option (see \fBdinit-service\fR(5)) applied to the stopped service will not cause the
 service to restart when it is stopped via this command (that is, this command inhibits automatic restart).
 This also applies to any dependents that must also be stopped at the same time.
-
+.sp
 Any pending \fBstart\fR orders are cancelled,
 though a service which is starting will continue its startup before then stopping (unless the service is
 configured to have an interruptible startup or is otherwise at a stage of startup which can be safely
 interrupted).
 .TP
 \fBstatus\fR
-Give a status report on the specified service. This will show the current state (and target state, if
-different), and information such as process ID (pid) if applicable. If the service is stopped for any reason
-other than a normal stop, the reason for the service stopping will be displayed (along with any further
-relevant information, if available).
+Give a status report on the specified service.
+This will show the current state (and target state, if different), and information such as process
+ID (pid) if applicable.
+If the service is stopped for any reason other than a normal stop, the reason for the service
+stopping will be displayed (along with any further relevant information, if available).
 .TP
 \fBrestart\fR
 Restart the specified service. The service will be stopped and then restarted, without affecting explicit
@@ -153,35 +155,39 @@ activation status or dependency links from dependents.
 .TP
 \fBwake\fR
 Start the specified service after reattaching dependency links from all active dependents of the specified
-service. The service will not be marked explicitly activated, and so will stop if all the dependents stop.
+service.
+The service will not be marked explicitly activated, and so will stop if all the dependents stop.
 .TP
 \fBrelease\fR
 Clear the explicit activation mark from a service (the service will then stop if it has no active dependents).
 .TP
 \fBunpin\fR
-Remove start- and stop- pins from a service. If a started service is not explicitly activated and
-has no active dependents, it will stop. If a started service has a dependency service which is stopping,
-it will stop. If a stopped service has a dependent service which is starting, it will start. Otherwise,
-any pending start/stop commands will be carried out.
+Remove start- and stop- pins from a service.
+If a started service is not explicitly activated and has no active dependents, it will stop.
+If a started service has a dependency service which is stopping, it will stop.
+If a stopped service has a dependent service which is starting, it will start.
+Otherwise, any pending start/stop commands will be carried out.
 .TP
 \fBunload\fR
-Completely unload a service. This can only be done if the service is stopped and has no loaded dependents
-(i.e. dependents must be unloaded before their dependencies).
+Completely unload a service.
+This can only be done if the service is stopped and has no loaded dependents (i.e. dependents must
+be unloaded before their dependencies).
 .TP
 \fBreload\fR
-Attempt to reload a service description. This is intended as a convenience for making simple changes to a
-service, without having to stop, remove dependencies to and unload the service. However it is not completely
-equivalent to doing a proper unload/reload; some altered settings may not take effect until the service is
-restarted, and some cannot be changed at all while the service is running.
-
+Attempt to reload a service description.
+This is intended as a convenience for making simple changes to a service, without having to stop,
+remove dependencies to and unload the service. However it is not completely equivalent to doing a
+proper unload/reload; some altered settings may not take effect until the service is restarted,
+and some cannot be changed at all while the service is running.
+.sp
 In particular, the type of a running service cannot be changed; nor can the \fBinittab-id\fR, \fBinittab-line\fR,
-or \fBpid-file\fR settings, or the \fBruns-on-console\fR or \fBshares-console\fR flags. If any hard dependencies
-are added to a running service, the dependencies must already be started.
+or \fBpid-file\fR settings, or the \fBruns-on-console\fR or \fBshares-console\fR flags.
+If any hard dependencies are added to a running service, the dependencies must already be started.
 .TP
 \fBlist\fR
-List loaded services and their state. Before each service, one of the following state indicators is
-displayed:
-
+List loaded services and their state.
+Before each service, one of the following state indicators is displayed:
+.sp
 .RS
 .nf
 \f[C]\m[blue][{+}\ \ \ \ \ ]\m[]\fR \[em] service has started.
@@ -191,68 +197,73 @@ displayed:
 \f[C]\m[blue][\ \ \ >>{\ }]\m[]\fR \[em] service is stopping.
 \f[C]\m[blue][\ \ \ \ \ {-}]\m[]\fR \[em] service has stopped.
 .fi
-
+.sp
 The << and >> symbols represent a transition state (starting and stopping respectively); curly braces
 indicate the target state (left: started, right: stopped); square brackets are used if the service
 is marked active (target state will always be started if this is the case).
-
+.sp
 An 's' in place of '+' means that the service startup was skipped (possible only if the service is
-configured as skippable). An 'X' in place of '-' means that the service failed to start, or that the
+configured as skippable).
+An 'X' in place of '-' means that the service failed to start, or that the
 service process unexpectedly terminated with an error status or signal while running.
-
+.sp
 Additional information, if available, will be printed after the service name: whether the service owns,
 or is waiting to acquire, the console; the process ID; the exit status or signal that caused termination.
 .RE
 .TP
 \fBshutdown\fR
-Stop all services (without restart) and terminate Dinit. If issued to the system instance of Dinit,
-this will also shut down the system.
+Stop all services (without restart) and terminate Dinit.
+If issued to the system instance of Dinit, this will also shut down the system.
 .TP
 \fBadd-dep\fR
-Add a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
-\fBmilestone\fR or \fBwaits-for\fR. Note that adding a regular dependency requires that the service
-states are consistent with the dependency (i.e. if the "from" service is started, the "to" service
-must also be started). Circular dependency chains may not be created.
+Add a dependency between two services.
+The \fIdependency-type\fR must be one of \fBregular\fR, \fBmilestone\fR or \fBwaits-for\fR.
+Note that adding a regular dependency requires that the service states are consistent with the
+dependency (i.e. if the "from" service is started, the "to" service must also be started).
+Circular dependency chains may not be created.
 .TP
 \fBrm-dep\fR
-Remove a dependency between two services. The \fIdependency-type\fR must be one of \fBregular\fR,
-\fBmilestone\fR or \fBwaits-for\fR. If the "to" service is not otherwise active it may be stopped
-as a result of removing the dependency.  
+Remove a dependency between two services.
+The \fIdependency-type\fR must be one of \fBregular\fR, \fBmilestone\fR or \fBwaits-for\fR.
+If the "to" service is not otherwise active it may be stopped as a result of removing the dependency.
 .TP
 \fBenable\fR
-Persistently enable a \fBwaits-for\fR dependency between two services. This is much like \fBadd-dep\fR
-but it also starts the dependency if the dependent is started (without explicit activation, so the
-dependency will stop if the dependent stops), and it creates a symbolic link in the directory
-specified via the \fBwaits-for.d\fR directive in the service description (there must be only one such
-directive) so that the dependency will survive between sessions.
-
+Persistently enable a \fBwaits-for\fR dependency between two services.
+This is much like \fBadd-dep\fR but it also starts the dependency if the dependent is started
+(without explicit activation, so the dependency will stop if the dependent stops), and it creates
+a symbolic link in the directory specified via the \fBwaits-for.d\fR directive in the service
+description (there must be only one such directive) so that the dependency will survive between
+sessions.
+.sp
 If the \fB--from\fR option is not used to specify the dependent, the dependency is created from the
 \fBboot\fR service by default.
 .TP
 \fBdisable\fR
-Permanently disable a \fBwaits-for\fR dependency between two services. This is the complement of the
-\fBenable\fR command; see the description above for more information.
-
-Note that the \fBdisable\fR command affects only the dependency specified (or implied). It has no
-other effect, and a service that is "disabled" may still be started if it is a dependency of
+Permanently disable a \fBwaits-for\fR dependency between two services.
+This is the complement of the \fBenable\fR command; see the description above for more information.
+.sp
+Note that the \fBdisable\fR command affects only the dependency specified (or implied).
+It has no other effect, and a service that is "disabled" may still be started if it is a dependency of
 another started service.
 .TP
 \fBsetenv\fR
-Export one or more variables into the activation environment. The value can be provided on the command line
-or retrieved from the environment \fBdinitctl\fR is called in. Any subsequently started or restarted
-service will have these environment variables available. This is particularly useful for user services
-that need access to session information.
+Export one or more variables into the activation environment.
+The value can be provided on the command line or retrieved from the environment \fBdinitctl\fR is
+called in.
+Any subsequently started or restarted service will have these environment variables available.
+This is particularly useful for user services that need access to session information.
 .\"
 .SH SERVICE OPERATION
 .\"
 Normally, services are only started if they have been explicitly activated (\fBstart\fR command) or if
-a started service depends on them. Therefore, starting a service also starts all services that the first
-depends on; stopping the same service then also stops the dependency services, unless they are also
-required by another explicitly activated service or have been explicitly activated themselves.
+a started service depends on them.
+Therefore, starting a service also starts all services that the first depends on; stopping the
+same service then also stops the dependency services, unless they are also required by another
+explicitly activated service or have been explicitly activated themselves.
 .LP
-A service can be pinned in either the started or stopped state. This is mainly intended to be used to
-prevent automated stop or start of a service, including via a dependency or dependent service, during
-a manual administrative procedure.
+A service can be pinned in either the started or stopped state.
+This is mainly intended to be used to prevent automated stop or start of a service, including
+via a dependency or dependent service, during a manual administrative procedure.
 .LP
 Stopping a service manually will prevent it (and its dependents) from automatically restarting.
 .\"