Date: Mon, 16 Jul 2001 09:15:35 -0700 (PDT) From: John Baldwin <jhb@FreeBSD.org> To: Chad David <davidc@acns.ab.ca> Cc: cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, Dima Dorfman <dima@unixfreak.org>, Alfred Perlstein <alfred@FreeBSD.org> Subject: Re: cvs commit: src/share/man/man9 cdevsw_add.9 cdevsw_remove.9 Message-ID: <XFMail.010716091352.jhb@FreeBSD.org> In-Reply-To: <20010714235559.A40654@colnta.acns.ab.ca>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <jhb@FreeBSD.org> -- 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?XFMail.010716091352.jhb>