Copy-edit dh_runit(1) documentation. (Closes: #920963)

2 files changed, 48 insertions, 38 deletions

diff --git a/debian/changelog b/debian/changelog
index 5facc36..2d4d990 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,10 @@
+dh-runit (2.8.4) UNRELEASED; urgency=medium
+
+  * Copy-edit dh_runit(1) documentation. (Closes: #920963)
+    + Thanks: Jonathan Nieder <jrnieder@gmail.com>
+
+ -- Dmitry Bogatov <KAction@debian.org>  Wed, 30 Jan 2019 15:44:58 -0800
+
 dh-runit (2.8.3) unstable; urgency=medium
 
   * Document runit:Breaks substitution variable
diff --git a/dh_runit b/dh_runit
index 447ae70..7baad5f 100755
--- a/dh_runit
+++ b/dh_runit
@@ -122,77 +122,80 @@ B<dh_runit> [S<I<debhelper options>>] [I<path> I<options>] ...
 =head1 DESCRIPTION
 
 B<dh_runit> is a debhelper program that is responsible for
-installing and enabling I<runit> runscripts. If file named
-F<debian/I<package>.runit> exists, then different actions
-are performed, depending on its format.
-
-For runit, every unit of supervision, simply speaking program, is
-represented by directory under F</etc/sv>, containing at least F<run>
-executable file. Every enabled program is represented by symbolic link
-under F</etc/services> (which itself is symbolic link to
+installing and enabling I<runit> runscripts. If a file named
+F<debian/I<package>.runit> exists, then it ensures appropriate actions
+are performed based on its content.
+
+For runit, each unit of supervision (or, simply speaking, program) is
+represented by a directory under F</etc/sv>, containing at least a F<run>
+executable file. Each enabled unit of supervision is represented by a
+symbolic link under F</etc/services> (which itself is a symbolic link to
 F</etc/runit/runsvdir/default>) pointing to some directory under
 F</etc/sv>.
 
-B<dh_runit> reads it's arguments from command line and
-F<debian/I<package>.runit> by two, with first one being an
-file/directory and second one is options. If first argument is file,
-it is considered 'run' script, and it is installed under
-F</etc/sv/*/run>, executable bit is added. If first argument is
-directory, it is copied as whole under F</etc/sv>.
+B<dh_runit> reads arguments from the command line and
+F<debian/I<package>.runit> in pairs, with the first item being the
+path to a file or directory and the second being a set of options.
+If the first argument names a file, it is treated as a 'run' script
+to be installed at F</etc/sv/*/run> as an executable file. If the first
+argument names a directory, that directory is copied as a whole to
+F</etc/sv>.
 
-Options are comma-separated, like to mount. Unsupported option
-is error, following are supported:
+Options are comma separated, like mount options. Unrecognized options
+are errors. The following options are recognized:
 
 =over
 
 =item I<disable>
 
-    With this option, runscript is installed, but not enabled by
-    default. It means that corresponding service will not be started.
-    System administrator can always do it manually or via
-    update-service(8).
+Install the runscript but do not enable it by default.
+This means that the corresponding service will not be started.
+The service can be enabled manually by the system administrator or
+automatically using update-service(8).
 
 =item I<name>=preferred-name
 
-    By default, name of directory under F</etc/sv> for given runscript
-    is basename of first argument of pair. This option allows you to
-    be explicit about it.
+By default, the name of the directory under F</etc/sv> for a given
+runscript is the basename of the path argument naming it. This
+option allows overriding that default with an explicitly chosen
+directory name.
 
 =item I<logscript>
 
-    Install standard F<log/run> script, which invokes svlogd(8) with
-    rights of dedicated user. It is error, if first argument in pair
-    is directory, which already contains F</log/run> script.
+Install a standard F<log/run> script that invokes svlogd(8) with
+the rights of the dedicated user. Specifying this option produces
+an error if the path argument names a directory that already
+contains a F</log/run> script.
 
 =item I<defaults>
 
-    If you need no other options, put this one.
+If you don't need other options, specify this one.
 
 =back
 
 =head1 SUBSTITUTION VARIABLES
 
-Package, created with help of B<dh_runit> does not depends on B<runit>,
-but should add I<runit:Breaks> variable into I<Breaks> field in I<debian/control>
-to ensure, that no breakages are caused by too old version of B<runit> package.
+Packages using B<dh_runit> do not depend on B<runit> but should include the
+I<runit:Breaks> variable in their I<Breaks> field in I<debian/control>
+to ensure that no breakages are caused by a too-old version of B<runit> package.
 
 =head1 EXAMPLES
 
-This section contains several example snippets from F<I<package>.runit>
+This section contains several example F<I<package>.runit> snippets.
 
-  # In this case file is installed as 'run' script. Directory name under
-  # /etc/sv is derived from file basename
+  # In this case, a file is installed as a 'run' script. The directory
+  # name under /etc/sv is derived from the file's basename (/etc/sv/script).
   path/to/file/to/be/installed/as/run/script defaults
 
-  # Same, but install directory as whole. It is your responsibility
-  # to ensure is contains everything required.
+  # Similar, but installs a directory as a whole. It is the package's
+  # responsibility to ensure this directory contains everything required.
   path/to/directory defaults
 
-  # Same as above, but do not create symlink under /etc/service
+  # Similar, but without creating a symlink under /etc/service.
   path/to/directory disable
 
-  # You can explicitly specify name of directory under /etc/sv.
-  # Standard log/run script will be created.
+  # Explicitly specifying a name to use for the directory under /etc/sv.
+  # A standard log/run script will be created.
   path/to/directory name=my-preferred-name,logscript
 
 =cut