From owner-cvs-all Sun Jan 5 12:41:47 2003 Delivered-To: cvs-all@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4E2FF37B401; Sun, 5 Jan 2003 12:41:46 -0800 (PST) Received: from angelica.unixdaemons.com (angelica.unixdaemons.com [209.148.64.135]) by mx1.FreeBSD.org (Postfix) with ESMTP id F284843EA9; Sun, 5 Jan 2003 12:41:44 -0800 (PST) (envelope-from hiten@angelica.unixdaemons.com) Received: from angelica.unixdaemons.com (hiten@localhost.unixdaemons.com [127.0.0.1]) by angelica.unixdaemons.com (8.12.7/8.12.1) with ESMTP id h05KfcO2078108; Sun, 5 Jan 2003 15:41:38 -0500 (EST) Received: (from hiten@localhost) by angelica.unixdaemons.com (8.12.7/8.12.1/Submit) id h05Kfcri078107; Sun, 5 Jan 2003 15:41:38 -0500 (EST) (envelope-from hiten) Date: Sun, 5 Jan 2003 15:41:38 -0500 From: Hiten Pandya To: Nate Lawson Cc: Bruce Evans , 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> References: <20030106055442.X563-100000@gamplex.bde.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.4i X-Operating-System: FreeBSD i386 X-Public-Key: http://www.pittgoth.com/~hiten/pubkey.asc X-URL: http://www.unixdaemons.com/~hiten X-PGP: http://pgp.mit.edu:11371/pks/lookup?search=Hiten+Pandya&op=index Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG 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