On Fri, Feb 21, 2014 at 11:45:26PM +0100, Ingo Schwarze wrote: > Hi, > > Jan Klemkow wrote on Wed, Jan 29, 2014 at 08:44:05PM +0100: > > > I've made a little diff to clean up some manpages with references to the > > obsoleted functions usleep(1), alarm(3). > > Actually, i like this diff and would like to commit it, > for the following reason: We include pointers in SEE ALSO > when they are likely to help readers. That's not the case here. > > From section 1 pages, pointers to section 2 and 3 are rarely helpful > because readers of section 1 usually look for ready-to-use utilities, > not for programming interfaces. Still, i like keeping a very small > number of pointers to the main syscalls and library functions used > for the implementation because that may help programmers to find > the most important code examples more quickly than by wading through > /usr/src/. But in sleep(1), this is clearly overdone, and Jan's > diff trims it down to a more reasonable level. I might even remove > sleep(3) as well, nanosleep(2) points to it anyway, and sleep(1) > doesn't even use it. > > From sleep(3), a pointer to usleep(3) is no longer helpful. If you > are considering to use sleep(3) in your code, you might reconsider > and use nanosleep(2) or setitimer(2) instead, when you discover > their existence. But it doesn't make sense at all to use usleep(3) > instead, that would merely harm portability for no benefit. So why > point to it? On the other hand, if you find usleep(3) in old code > and wonder what it does, you are looking at the usleep(3) manual > in the first place and don't need the pointer either. > > OK? > Ingo > > > > Index: bin/sleep/sleep.1 > > =================================================================== > > RCS file: /cvs/src/bin/sleep/sleep.1,v > > retrieving revision 1.19 > > diff -u -p -r1.19 sleep.1 > > --- bin/sleep/sleep.1 3 Sep 2010 09:53:20 -0000 1.19 > > +++ bin/sleep/sleep.1 29 Jan 2014 19:39:14 -0000 > > @@ -109,9 +109,7 @@ done > > .Xr at 1 , > > .Xr nanosleep 2 , > > .Xr setitimer 2 , > > -.Xr alarm 3 , > > -.Xr sleep 3 , > > -.Xr usleep 3 > > +.Xr sleep 3 > > .Sh STANDARDS > > The > > .Nm > > Index: lib/libc/gen/sleep.3 > > =================================================================== > > RCS file: /cvs/src/lib/libc/gen/sleep.3,v > > retrieving revision 1.14 > > diff -u -p -r1.14 sleep.3 > > --- lib/libc/gen/sleep.3 18 Jul 2013 10:14:49 -0000 1.14 > > +++ lib/libc/gen/sleep.3 29 Jan 2014 19:39:31 -0000 > > @@ -70,7 +70,7 @@ slept) in seconds. > > .Sh SEE ALSO > > .Xr sleep 1 , > > .Xr nanosleep 2 , > > -.Xr usleep 3 > > +.Xr setitimer 2 > > .Sh STANDARDS > > The > > .Fn sleep > >
what do you want here, really? in my opinion, readers of section one pages should not be pointed to code. yes, yes, yes, other people disagree. but no one using sleep(1) will care. so you propose to remove the Xr to alarm(). that's a function mandated by posix. why make people less aware of that interface? really? second, why replace, in sleep(3), the reference to usleep with setitimer? usleep(3) says it is obsoleted by nanosleep(2), not setitimer(2). and additionally the posix page for sleep() lists getitimer, not setitimer. that's the name of our page, too. so its one of those "pick your colors, best ones win" cases. are you sure this is making the docs clearer? really? my advice is to remove all 2/3 refs in sleep(1), and just zap the usleep ref in sleep(3). since people who never previously cared about this will now start caring, ask yourself whether it's worth it. jmc
