Date: Mon, 16 Jul 2001 11:30:12 -0600 From: Chad David <davidc@acns.ab.ca> To: John Baldwin <jhb@FreeBSD.org> Cc: Chad David <davidc@acns.ab.ca>, 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: <20010716113012.B44677@colnta.acns.ab.ca> In-Reply-To: <XFMail.010716091352.jhb@FreeBSD.org>; from jhb@FreeBSD.org on Mon, Jul 16, 2001 at 09:15:35AM -0700 References: <20010714235559.A40654@colnta.acns.ab.ca> <XFMail.010716091352.jhb@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jul 16, 2001 at 09:15:35AM -0700, John Baldwin wrote: > > 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. That works fine for me, just don't shoot me when something never gets 100% completed :). Chad PS. Sorry about the long lines in my previous emails. I switch between my laptop (800x600) and my primary workstation (1600x1200) and sometimes get a little carried away :-(. > > -- > > 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?20010716113012.B44677>