From owner-cvs-all Mon Jul 16 9:16:16 2001 Delivered-To: cvs-all@freebsd.org Received: from meow.osd.bsdi.com (meow.osd.bsdi.com [204.216.28.88]) by hub.freebsd.org (Postfix) with ESMTP id BA2E837B401; Mon, 16 Jul 2001 09:16:04 -0700 (PDT) (envelope-from jhb@FreeBSD.org) Received: from laptop.baldwin.cx (john@jhb-laptop.osd.bsdi.com [204.216.28.241]) by meow.osd.bsdi.com (8.11.4/8.11.2) with ESMTP id f6GGFUv69264; Mon, 16 Jul 2001 09:15:30 -0700 (PDT) (envelope-from jhb@FreeBSD.org) Message-ID: X-Mailer: XFMail 1.4.0 on FreeBSD X-Priority: 3 (Normal) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 8bit MIME-Version: 1.0 In-Reply-To: <20010714235559.A40654@colnta.acns.ab.ca> Date: Mon, 16 Jul 2001 09:15:35 -0700 (PDT) From: John Baldwin To: Chad David Subject: Re: cvs commit: src/share/man/man9 cdevsw_add.9 cdevsw_remove.9 Cc: cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, Dima Dorfman , Alfred Perlstein 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 15-Jul-01 Chad David wrote: >> > I agree, having lockmgr.9 contain all the lockmgr related functions, and a >> > cdevsw.9 would be nice. It keeps all the related material in one place so >> > you >> > can browse an API easily in one place. See atomic.9, kthread.9, mutex.9, >> > etc. >> > as examples of this. > > I agree that a bunch of the ones I have written could be grouped, but I > have to struggle with two evils; one, write every man page on the subject > before I submit any thing or two, create one big page with a bunch of holes > in it and then have to justify that... What I would prefer to do is start > out with individual pages and then merge them when their bulk begins to > demand > it, or my rewritting the same intro over and over starts to drive me crazy. Leaving holes is fine. The kthread.9 manpage started out as a stub manpage that basically listed the functions in that group with very little description of them until more was added later. Grouping related things together in a single manpage gives you a handy place to describe general issues for a topic. For example, if you document all the vm_page operations in one vm_page.9, then you can also include in that manpage as the intro a little blurb about what a vm page is and what it does, etc. Then just adding the bits for hold/wire/flags is easy, where as if you have separate manpages for all the bits then a) you don't have a place for the generic description to go or b) you duplicate it in all the manpages. -- John Baldwin -- http://www.FreeBSD.org/~jhb/ PGP Key: http://www.baldwin.cx/~john/pgpkey.asc "Power Users Use the Power to Serve!" - http://www.FreeBSD.org/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message