(I am not the maintainer, but I help out with description reviews on
the debian-l10n-english mailinglist, and I noticed this bug report.)
Martin Teufel wrote:
> Important informations are missing in the long package description; the short
> description is (or can be) misleading
> too. This package/program can either be used as a software watchdog and/or
> can be used to "pet" a hardware watchdog. It
> isn't just a software watchdog (can be used otherwise -> bad short
> description) and the functionality to pet hardware
> watchdogs should be mentioned (at least) in the long description.
>
> The new package description in 5.10-1 and later is still unsatisfactory in my
> opinion.
For a start, it's ungrammatical - "trigger" should be "triggers" or
"can trigger"! Plus, DevRef 6.2.2 recommends not capitalising the
first word of a synopsis.
> It *really* should be mentioned that this package also provides an
> opportunity to "pet" hardware watchdogs.
>
> Here is my suggestion:
>
> short description:
>
> ##################
>
> System health checker that also trigger kernel watchdogs and may pet a
> hardware watchdog if available
>
> ##################
That's much too long, too much like jargon, and still ungrammatical.
Is there a general term that could be used to describe both
"triggering" and "petting" a watchdog? I would suggest:
system health checker and watchdog handler
Or you might make it
system health checker and software/hardware watchdog handler
My patch goes for the simpler approach, on the principle that if you
don't specify, the reader can assume it means either kind; but I may
of course be displaying my ignorance of how watchdog functions.
> long description:
>
> #################
>
> The watchdog program writes to /dev/watchdog every ten seconds. If the
> device is opened but not written to within a minute, the machine will
> reboot. This feature is available when the kernel is built with
> 'software watchdog' support (standard in Debian kernels) or if the
> machine is equipped with a hardware watchdog. If a hardware watchdog is
> available, this package can also be used to "pet" it.
Yes, there's room for that term here, and even for an explanation, but
there's no need to repeat the concept of "if a hardware watchdog is
available". I would suggest:
The watchdog program writes to /dev/watchdog every ten seconds. If the
device is opened but not written to within a minute, the machine will
reboot. This feature is available when the kernel is built with
"software watchdog" support (standard in Debian kernels) or if the
machine is equipped with a hardware watchdog (in which case this
package can also be used to "pet" it, resetting its timer).
(Standardising some punctuation details in the direction of the
debian-l10n-english "house style".)
> The ability to reboot will depend on the state of the machine and
> interrupts if the kernel software watchdog is used.
If this is saying
The kernel software watchdog's ability to reboot will depend on the
state of the machine and interrupts.
...then I think it would be clearer expressed that way.
>
> The watchdog tool itself runs several health checks and acts accordingly
> if the system is not in a good shape.
That last paragraph has crept in since the last time this text passed
through d-l-e, and it could do with a couple of tweaks:
The watchdog tool itself runs several health checks and acts
appropriately if the system is not in good shape.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru watchdog-5.11.pristine/debian/control watchdog-5.11/debian/control
--- watchdog-5.11.pristine/debian/control 2012-03-14 23:13:20.000000000 +0000
+++ watchdog-5.11/debian/control 2012-03-14 23:17:42.811395032 +0000
@@ -9,14 +9,16 @@
Package: watchdog
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}, makedev (>= 2.3.1-24) | udev, lsb-base (>= 3.2-14)
-Description: System health checker that also trigger kernel watchdogs
- The watchdog program writes to /dev/watchdog every ten seconds. If
+Description: system health checker and watchdog handler
+ The watchdog program writes to /dev/watchdog every ten seconds. If
the device is opened but not written to within a minute, the machine
will reboot. This feature is available when the kernel is built with
- 'software watchdog' support (standard in Debian kernels).
+ "software watchdog" support (standard in Debian kernels) or if the
+ machine is equipped with a hardware watchdog (in which case this
+ package can also be used to "pet" it, resetting its timer).
.
- The ability to reboot will depend on the state of the machine
- and interrupts if the kernel software watchdog is used.
+ The kernel software watchdog's ability to reboot will depend on the
+ state of the machine and interrupts.
.
- The watchdog tool itself runs several health checks and acts accordingly if
- the system is not in a good shape.
+ The watchdog tool itself runs several health checks and acts
+ appropriately if the system is not in good shape.
