Re: Please check these manpages
On Monday, May 26, 2003, at 07:05 PM, Nicolas Boullis wrote:
Hi,
First of all, thanks a lot for your work.
Your welcome. I'm happy to assist in making Debian better.
On Mon, May 26, 2003 at 03:01:21PM -0400, Anthony DeRobertis wrote:
[loadwatch]
loadwatch spawns a child process [prog] with the arguments [args] and
allows it to run while the load average remains below [high_limit].
Every [delay] seconds, loadwatch checks the load average. If it is
above [high_limit], the child is suspended. The child is resumed when
the load falls below [low_limit].
(Wow, that was some serious condensation!)
I changed it slightly:
- put "loadwatch" in bold
Yeah, that's good. If I remember manpage style correctly, the program
name is always set in bold.
- merged the last 2 sentences to:
If it is above [high_limit], the child is suspended; it is
resumed
when the load falls below [low_limit].
This sound better in french, but I'm not really sure for english.
I think the antecedent of "it" becomes unclear when the sentences are
merged like that. Perhaps "If the load is above..." or "... the child
is resumed". I think those are clearer.
\fB\-u\fR \fIfile\fR
a unix domain socket that will be used to contol \fBloadwatch\fR with
\fBlw-ctl\fR.
This needs more detail. Do I need to create this socket myself? Or
will
loadwatch do it?
I rewrote it to:
a unix domain socket that [loadwatch] will create to get controlled
by
[lw-ctl].
Is it better?
That phrasing is awkward... maybe
create a unix domain socket [file] for use by [lw-ctl]
.TP
\fB\-p\fR \fIpid\fR
the pid of the program that should be controlled by \fBloadwatch\fR
(with all its process group).
The rest of the page only mentioned it spawning a child...
You're right. I shall rewrite the DESCRIPTION section...
I think some small changes will do.
.SH BUGS
Currently only one instance of \fBloadwatch\fR should be running at a
given time, as multiple instances will interact in possibly
unexpected
ways.
That's weird. How would they interact, besides through the load
average?
Only through the average load. If two instances of loadwatch are
running
at the same time, they may resume their controlled process at the same
time. Then the average load will raise quickly above 1.25, and both
processes will be suspended, until it drops below 0.25 when both will
be
resumed. Then both processes will be running half the time, while none
would be the other half. This is quite bad...
Do you think I should rephrase the BUGS section?
Yes. Basically, put the above in the BUGS section. Its much more
helpful to the user than "bad things may happen."
.TP
\fBSTOP\fR
the program(s) controlled by \fBloadwatch\fR are stopped whatever the
load is.
Suspend the child process and do not resume even if system load is
below the low threshhold.
Wouldn't it be more consistant to write it as:
Suspend the child process regardless of system load.
Yeah, that would be. Just forget my suggestion and go with that instead.
?
BTW, I think "threshold" has only 2 "h"... ;-)
Damn spellchecker! wonder how I missed the squiggly line underneath
that.
[wmtv]
.SH "USAGE"
This sections describes how to use the application in docked
state. See lower for fullscreen mode usage.
s/lower/the next section/
Would "below" be fine?
Yes.
Anyway, I don't know how to underline in *roff... Perhaps bold may be
enough...
Colin Watson beat me to this one in
<[🔎] 20030527005854.GB26553@riva.ucam.org>
<http://lists.debian.org/debian-l10n-english/2003/debian-l10n-english-
200305/msg00033.html>
AFAICS, this is the first time you add this hyphen to "right-clicking";
I guess I should add it everywhere, and to "left-clicking" as well...
Probably.
Double left-clicking the TV screen launches the application specified
with
--exe. If --exe was not specified, then the built-in full-screen mode
is used instead. Double-clicking with the middle mouse button will
always invoke the built-in full screen mode.
Why "double left-clicking" and "double-clicking with the middle mouse
button"? Why not "double middle-clicking" or "double-clicking with the
left mouse button"? It would sound more consistent...
No good reason, really, other than "three manpages is a lot to edit at
once." Change it to be consistent.
.br
Right - Volume up. (If supported by the v4l device.)
.br
Increase volume. (I'm using decrease here, because we're using the
right arrow key, so saying down is a little confusing. It'd get me
confused enough to try pressing the down key, but that changes
channels. I think the key bindings are backwards, but what the heck?)
Left - Volume down. (If supported.)
.br
Decrease volume.
Do you mean that I should remove the "(If supported by the v4l
device.)"
comments?
Go ahead and leave that comment there.
(About the key bindings being backwards, you may be right, but changing
this would probably confuse the existing users much more... Moreover
real TV sets generally show volume with an horizontal slider, so
left/right is not stupid...)
Depends on the set, in my experience. But, yeah, it'd probably just
confuse people, especially if it were only different on Debian.
.br
m - mute/unmute audio.
mute
??? I'm not sure I understand what you mean here...
I think just the word "mute" is sufficient. At least drop "audio", IMO.
.br
.B %f
is replaced by the current frequency.
I'm not clear what this means. Is it actually a frequency, like
4.56MHz, or do you mean channel number?
I really meant a frequency, but in a strange unit: 1/16th MHz or
1/32th kHz depending on the underlying device... I should probably fix
the program to use better units... ;-)
Eeek, those are weird units. So maybe:
is replaced by the current frequency in either 1/16 MHz or
1/32 kHz, depending on the hardware involved.
/me wonders whats magic about 62,500 Hz and 31.25 Hz.
Reply to: