Date: Sun, 5 Jan 2003 15:41:38 -0500 From: Hiten Pandya <hiten@unixdaemons.com> To: Nate Lawson <nate@root.org> Cc: Bruce Evans <bde@zeta.org.au>, cvs-committers@FreeBSD.ORG, cvs-all@FreeBSD.ORG Subject: Re: cvs commit: src/share/man/man5 Makefile msdos.5 Message-ID: <20030105204138.GB73068@unixdaemons.com> In-Reply-To: <Pine.BSF.4.21.0301051217510.7893-100000@root.org> References: <20030106055442.X563-100000@gamplex.bde.org> <Pine.BSF.4.21.0301051217510.7893-100000@root.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Jan 05, 2003 at 12:19:55PM -0800, Nate Lawson wrote the words in effect of: > On Mon, 6 Jan 2003, Bruce Evans wrote: > > > > fs.5: actually does document a file format, namely the superblock > > > > format > > > > for 10-year old versions of ffs. This belongs in an Attic. The > > > > non-rotted version is in ffs/fs.h. > > > > > Perhaps instead of Attic, we clean up the rot? > > > > I think its bits are correctly placed in ffs/fs.h (since we have open > > sources). Kirk McKusick agreed with me that there is little point in > > updating it and approved moving it to the Attic. I want any useful > > bits in it moved to fs.h before that is done. > > I agree with Bruce -- interfaces are best documented in one place to > prevent rot. Given the choice between man page and .h, I'd choose .h > since it's less likely to rot (although we need to be intentional about > documentation either way.) This is also true for other manual pages, like Vnode(9) (in 5.0/CURRENT) where struct vnode has just been dumped, no offense. It would be better to reference the struct (as Bruce said), and then give explanation of its fields. IMHO of course. -- Hiten Pandya (hiten@unixdaemons.com, hiten@uk.FreeBSD.org) http://www.unixdaemons.com/~hiten/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030105204138.GB73068>