From owner-cvs-all Mon Jul 16 10:30:23 2001 Delivered-To: cvs-all@freebsd.org Received: from colnta.acns.ab.ca (h24-68-206-125.sbm.shawcable.net [24.68.206.125]) by hub.freebsd.org (Postfix) with ESMTP id B1D0A37B405; Mon, 16 Jul 2001 10:30:12 -0700 (PDT) (envelope-from davidc@colnta.acns.ab.ca) Received: (from davidc@localhost) by colnta.acns.ab.ca (8.11.4/8.11.3) id f6GHUCH44818; Mon, 16 Jul 2001 11:30:12 -0600 (MDT) (envelope-from davidc) Date: Mon, 16 Jul 2001 11:30:12 -0600 From: Chad David To: John Baldwin Cc: Chad David , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, Dima Dorfman , Alfred Perlstein Subject: Re: cvs commit: src/share/man/man9 cdevsw_add.9 cdevsw_remove.9 Message-ID: <20010716113012.B44677@colnta.acns.ab.ca> References: <20010714235559.A40654@colnta.acns.ab.ca> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: ; from jhb@FreeBSD.org on Mon, Jul 16, 2001 at 09:15:35AM -0700 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 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 -- 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