Re: Please check these manpages
Hi,
First of all, thanks a lot for your work.
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
- 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.
Are those 2 changes correct?
> >\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?
> >.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...
> >.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?
[lw-ctl]
> >
> >.TP
> >\fBRUN\fR
> >the program(s) controlled by \fBloadwatch\fR run whatever the load is.
>
> Allow the child process to run regardless of system load.
>
> >
> >.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.
?
BTW, I think "threshold" has only 2 "h"... ;-)
[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?
> >The 3 modes are described below:
> >
> >.in +5
> >.B "On mode"
> >.br
> >.B "-------"
> >.br
>
> Errm, is this supposed to be underlining?
Well, I guess so... ;-)
I didn't write this manpage myself, and this part was clearly copied
from the upstream-provided README...
Anyway, I don't know how to underline in *roff... Perhaps bold may be
enough...
> >.in -5
> >
> >Right clicking once on the TV Screen would mute/unmute the audio.
>
> Right-clicking the TV screen mutes/unmutes the audio.
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...
> 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...
> >.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?
(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...)
> >.br
> >m - mute/unmute audio.
>
> mute
??? I'm not sure I understand what you mean here...
> >.B %%
> >is replaced by a single raw %.
>
> strike "raw". I've never heard of a cooked %.
;-)
> >.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... ;-)
Anyway, thanks a lot for your work. Those manpages are already much
better, thanks to you.
Regards,
Nicolas
Reply to: