From owner-cvs-all Sat Nov 11 8: 8: 4 2000 Delivered-To: cvs-all@freebsd.org Received: from mppsystems.com (mppsystems.com [208.210.148.205]) by hub.freebsd.org (Postfix) with ESMTP id A6E4637B479; Sat, 11 Nov 2000 08:07:58 -0800 (PST) Received: (from mpp@localhost) by mppsystems.com (8.11.1/8.11.1) id eABG7FD56078; Sat, 11 Nov 2000 10:07:15 -0600 (CST) (envelope-from mpp) Date: Sat, 11 Nov 2000 10:07:15 -0600 From: Mike Pritchard To: Sheldon Hearn , Jeroen Ruigrok van der Werven , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/man/man5 periodic.conf.5 Message-ID: <20001111100715.A55972@mppsystems.com> References: <200011090505.VAA56652@freefall.freebsd.org> <13279.973759974@axl.fw.uunet.co.za> <20001109113058.A59246@sunbay.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20001109113058.A59246@sunbay.com>; from ru@sunbay.com on Thu, Nov 09, 2000 at 11:30:58AM +0200 Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG On Thu, Nov 09, 2000 at 11:30:58AM +0200, Ruslan Ermilov wrote: > On Thu, Nov 09, 2000 at 10:52:54AM +0200, Sheldon Hearn wrote: > > > > > > On Wed, 08 Nov 2000 21:05:18 PST, Jeroen Ruigrok van der Werven wrote: > > > > > Modified files: > > > share/man/man5 periodic.conf.5 > > > Log: > > > Change .Os FreeBSD 5.0 to .Os FreeBSD. > > > > For the record, I'm of the opinion that there is no value at all in > > providing an argument to the Os macro. :-) > > > Seconded, historical information could be put into the HISTORY section. And a third (a bit late, but I just want to be on the record, and I'm just catching up on my e-mail :-). After an e-mail discussion with Sheldon and some other people on the subject and doing some thinking, I think we should just leave .Os blank. I would even go so far as to say that ".Os" is optional, but that would probably make it harder for other *BSD projects to import our work, so you still have to at least have a ".Os" line in your man page. (and yes, I'm still pondering/tinkering with a style.mdoc.7 man page, but feel free to write your own and submit it for review :-)!!!!!, please!. 1) It makes it easier for other people to import our work. 2) If other people / projects do the same, it makes it easier for us to import their work. 3) It keeps our man pages from looking out of date. We still have man pages that have ".Os FreeBSD 2.2" or whatever in the tree, even though those man pages actually only apply to -current (or whatever release they actually appear in). As stated above, historical information should be placed in the HISTORY section (create one if it isn't already there). Now, the only case I can see for actually using .Os with an OS/version # is to document a deprecated interface. E.g. ".Os FreeBSD 1.0" to describe the old "xyzzy" interface. And the man page should have lots of big letters at the top saying that this is gone, or changed, or morgified or whatever indicating this, and what you should be actually using (with proper xrefs of course :-). With that comment, IMO, the only time .Os should be used with arguments is when "dead" interface / whatever is documented. E.g. Think Latin. It is only being documented so that people who know the old interface at least have some kind of documentation on how it used to work in FreeBSD, and then hopefully some pointers to the current method. -Mike -- Mike Pritchard mpp@FreeBSD.org or mpp@mppsystems.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message