Bug#920963: dh-runit: copy-edits to dh_runit(1) manpage
Package: dh-runit
Version: 2.8.3
Severity: minor
Justification: documentation
Reading the dh_runit(1) manpage, I ran into a few small nits that
made it harder to read. Mostly:
- some missing or extra articles ("a" or "the")
- F<> markup showing up in list items
- some word usage nits (e.g. "different" meaning "various" and so on)
A patch follows with some suggested edits. I'm happy to explain any
details that seem unclear and I won't be hurt if you clear up the text
in a different way. I'm cc-ing debian-l10n-english since they tend to
be very good at this kind of editing for readability.
debian-l10n-english: you can find the source file in dh_runit in
https://salsa.debian.org/runit-team/dh-runit.git, and you can preview
the output by running "perldoc ./dh_runit".
Thoughts of all kinds welcome, as always.
diff --git a/debian/changelog b/debian/changelog
index 5facc36..431b3e7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+dh-runit (2.8.4) UNRELEASED; urgency=medium
+
+ * Copy-edit dh_runit(1) documentation.
+
+ -- Jonathan Nieder <jrnieder@gmail.com> 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.
+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, 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
+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
Reply to: