Brian Utterback wrote: > > Danek Duvall wrote: >> On Tue, Dec 23, 2008 at 10:53:17AM -0500, Brian Utterback wrote: >> Most other fast-tracks filed around this time have been given timers that >> extend into January. I would suggest extending it until the 13th, but >> show >> up to the meeting on the 6th (if there is one) and see if it can't be >> closed at that point. >> > > Timer extended until the 13th. > > >>> This practice seems wrong to me. >> >> To me, too, but if you're going to be pushing a lot of F/OSS through our >> processes, making little corrections here and there can slow a lot of >> people down. If you feel you have the time to make these corrections, >> though, please do so -- accuracy is highly desired. The SFW C-team is >> likely to ask you to put an Attributes section at the end of the page >> anyway, so fixing the other bits might not be too onerous on top of that. >> >> Danek > > To me, getting the man page right is part of the porting process. To say > that correcting the man page would slow the process down is like saying > that getting the program to run on Solaris just slows the project down. > Come to that, wouldn't it be faster to skip that bothersome compile step? > > We usually require man pages for projects that don't have them. I am not > saying that the man page has to be perfect, but would it be so bad to > require the project teams to take an hour or so to make it reflect > something resembling reality? Or if that really is too much, how about a > disclaimer at the top saying that the man page is being delivered "as > is" and may not reflect reality? > > This is another one of those pesky "best practices" issues. Either the > goal is to have man pages that are good documentation on the use of the > commands that are now part of our product, or the goal is to deliver the > man pages exactly as delivered by the community. If the former then it > is the responsibility of the project team to make a pass over the man > page and remove any egregious errors and document Solaris specific > issues. If the latter, then we have a responsibility to differentiate > between the types of man pages. Right now we appear to primarily deliver > the latter and pretend it is the former. That is untenable. > Another question is whether there are any legal implications modifying the code and whether modifying the man page is considering modifying the code. I believe it is a complicating legal factor to change *any* source in the delivery and it may be the real reason why man pages stay as they are in all the GNU ports. I will have to look into that.
--thomas
