On Tue, Jul 26, 2022 at 09:18:47PM -0500, Scott Cheloha wrote: > A few improvements I want to make to the sleep(1) manpage. > > DESCRIPTION > > - "for a minimum of" is better said "for at least". >
hi. i can;t really distinguish between one form being better than the other. "until at least" is the posix wording; "for a minimum" the text in net/free/open etc. > - The seconds argument can be zero, so say "non-negative". > > - Specify that the number (the whole thing) is decimal to exclude > e.g. hex numbers. It then follows that the optional fraction > must also be decimal. > > - I don't think we need to inspire the reader to use sleep(1) in any > particular way. We can just demonstrate these patterns in the > Examples provided later. > > ASYNCHRONOUS EVENTS > > - Note that SIGALRM wakes sleep(1) up "early". > > EXAMPLES > > - Simplify the first example. I think parenthetically pointing the > reader to at(1) muddies what ought to be the simplest possible > example. Scheduling jobs is a way more advanced topic, sleep(1) > is more like a shell primitive. > > - Shorten the interval in the first example. A half hour is not > interactive. > > - Get rid of the entire csh(1) example. It's extremely complex and > the bulk of the text is spent explaining things that aren't about > sleep(1) at all. > > Maybe also of note is that very few other manpages offer csh(1) > examples. Is there a rule about that? > i suppose the dominance of sh has led to examples getting written in this style. but that doesn;t mean we have to rewrite all csh examples. i think we usually use sh for script examples, but try to make sure that all examples work regardless of the user shell. you're right that the current section is a bit wordy though. > - Tweak the third example to show the reader that you can sleep > for a fraction of a second, as mentioned in the Description. > > STANDARDS > > - Prefer active voice. > > "The handling of fractional arguments" is better said > "Support for fractional seconds". > > Shorten "is provided as" to "is". > > SEE ALSO > > - Seems logical to point back to nanosleep(2) and sleep(3). > normally we'd try to avoid sending the reader of section1 pages to sections 2/3/9. but if there's stuff there that will help the user (not code writer) then it'd make sense. is there? > - Add echo(1) and ls(1) from the EXAMPLES. > that's not needed. we don;t add every command listed in the page to SEE ALSO. just really pages we think will help people better understand the subject they're reading about. so echo(1) does not really help you understand sleep(1). however you should leave the reference to at(1) - in this case it shows you how to do something like sleep, but better suited to some specific tasks. > ... unsure if we actually need to reference these or if it's > a distraction. The existing examples make use of awk(1) but > do not Xr it in this section, unsure if there is a rule about > this. > > - Add signal(3) because we talk about SIGALRM. > again, i think that's outside the scope of sleep(1). jmc > HISTORY > > - Not merely "appeared": "first appeared". > > -- > > Tweaks? ok? > > Index: sleep.1 > =================================================================== > RCS file: /cvs/src/bin/sleep/sleep.1,v > retrieving revision 1.22 > diff -u -p -r1.22 sleep.1 > --- sleep.1 16 Aug 2016 18:51:25 -0000 1.22 > +++ sleep.1 27 Jul 2022 02:16:18 -0000 > @@ -45,62 +45,35 @@ > .Sh DESCRIPTION > The > .Nm > -utility > -suspends execution for a minimum of the specified number of > -.Ar seconds . > -This number must be positive and may contain a decimal fraction. > -.Nm > -is commonly used to schedule the execution of other commands (see below). > +utility suspends execution until at least the given number of > +.Ar seconds > +have elapsed. > +.Ar seconds > +must be a non-negative decimal value and may contain a fraction. > .Sh ASYNCHRONOUS EVENTS > .Bl -tag -width "SIGALRMXXX" > .It Dv SIGALRM > -Terminate normally, with a zero exit status. > +Terminate early, with a zero exit status. > .El > .Sh EXIT STATUS > .Ex -std sleep > .Sh EXAMPLES > -Wait a half hour before running the script > -.Pa command_file > -(see also the > -.Xr at 1 > -utility): > -.Pp > -.Dl (sleep 1800; sh command_file >& errors)& > -.Pp > -To repetitively run a command (with > -.Xr csh 1 ) : > -.Bd -literal -offset indent > -while (! -r zzz.rawdata) > - sleep 300 > -end > -foreach i (*.rawdata) > - sleep 70 > - awk -f collapse_data $i >> results > -end > -.Ed > +Wait five seconds before running a command: > .Pp > -The scenario for such a script might be: a program currently > -running is taking longer than expected to process a series of > -files, and it would be nice to have another program start > -processing the files created by the first program as soon as it is finished > -(when > -.Pa zzz.rawdata > -is created). > -The script checks every five minutes for this file. > -When it is found, processing is done in several steps > -by sleeping 70 seconds between each > -.Xr awk 1 > -job. > +.Dl $ sleep 5 ; echo Hello, World! > .Pp > -To monitor the growth of a file without consuming too many resources: > +List a file twice per second: > .Bd -literal -offset indent > -while true; do > - ls -l file > - sleep 5 > +while ls -l file; do > + sleep 0.5 > done > .Ed > .Sh SEE ALSO > -.Xr at 1 > +.Xr echo 1 , > +.Xr ls 1 , > +.Xr nanosleep 2 , > +.Xr signal 3 , > +.Xr sleep 3 > .Sh STANDARDS > The > .Nm > @@ -108,10 +81,11 @@ utility is compliant with the > .St -p1003.1-2008 > specification. > .Pp > -The handling of fractional arguments is provided as an extension to that > -specification. > +Support for fractional > +.Ar seconds > +is an extension to that specification. > .Sh HISTORY > A > .Nm > -utility appeared in > +utility first appeared in > .At v4 . >
