Date: Sat, 11 Nov 2000 10:07:15 -0600 From: Mike Pritchard <mpp@mppsystems.com> To: Sheldon Hearn <sheldonh@uunet.co.za>, Jeroen Ruigrok van der Werven <asmodai@FreeBSD.org>, 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> In-Reply-To: <20001109113058.A59246@sunbay.com>; from ru@sunbay.com on Thu, Nov 09, 2000 at 11:30:58AM %2B0200 References: <200011090505.VAA56652@freefall.freebsd.org> <13279.973759974@axl.fw.uunet.co.za> <20001109113058.A59246@sunbay.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20001111100715.A55972>