Date: Tue, 24 Jul 2001 03:31:12 -0500 From: Mike Pritchard <mpp@mppsystems.com> To: John Baldwin <jhb@FreeBSD.org> Cc: Greg Lehey <grog@FreeBSD.org>, doc@FreeBSD.org, cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org, Ruslan Ermilov <ru@FreeBSD.org> Subject: Re: Which OS does a man page come from? (was: cvs commit: src/bi Message-ID: <20010724033112.B46693@mppsystems.com> In-Reply-To: <XFMail.010723165018.jhb@FreeBSD.org>; from jhb@FreeBSD.org on Mon, Jul 23, 2001 at 04:50:18PM -0700 References: <20010724090443.L55779@wantadilla.lemis.com> <XFMail.010723165018.jhb@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jul 23, 2001 at 04:50:18PM -0700, John Baldwin wrote:
>
> On 23-Jul-01 Greg Lehey wrote:
> > On Monday, 23 July 2001 at 12:21:24 +0300, Ruslan Ermilov wrote:
> >> On Sun, Jul 22, 2001 at 03:57:33AM -0500, Mike Pritchard wrote:
> >>> I agreed to it, never requested it. At the time I suggested
> >>> that if all we are going to have is a plain ".Os" line in every man
> >>> page with no information, then we should just remove ".Os" totally,
> >>> since it it just taking up space and processing time.
> >>
> >> Historically, a missing .Os call would result in an empty bottom left
> >> corner.
> >> With -mdocNG, as of this delta,
> >>
> >> <snip>
> >>
> >> the .Os call is not (strictly speaking) required at all, so we may
> >> eventually remove it completely, yes. I think I will do this after
> >> NetBSD and OpenBSD upgrade to -mdocNG.
> >
> > How would this handle non-native man pages? I have a whole collection
> > of man pages for different operating systems on my system. I don't
> > want the formatting software to claim that they relate to the system
> > on which they're formatted. It looks to me as if the .Os should
> > explicitly specify which operating system the man page belongs to.
>
> I agree. Especially for manpages that are very OS-specific, such as many
> kernel API manpages which document API's very specific to FreeBSD. If someone
> looks at that manpage on a Solaris box, it shouldn't be claiming that solaris
> implements sx locks for example.
We have had very specific FreeBSD only features, and the man page has
a ".Os FreeBSD" line in it, only to have NetBSD/OpenBSD adopt it later.
We have also take software from those two groups and removed the
".Os NetBSD" lines from them because the manual actually describes what
is going on under FreeBSD.
I can see two cases where having a non-blank ".Os" call are needed.
1) You are documenting an obsolete version of something. Say feature
'x' went away in FreeBSD version 4.0, but you still want to document it
so people who are upgrading can figure out what the old feature did
so they can upgrade to the new feature. In this case, ".Os FreeBSD 4.0"
would be correct. The compat libraries are probably about the only
thing to which this would apply.
2) You are documenting a feature of another operating system.
Then you would want to include a ".Os other-os" line. I don't
think we have any of these cases right now.
It has always been a mixed bag since the early days of FreeBSD.
A lot of man pages had a plain ".Os" line, and the rest had a
".Os FreeBSD [version]". The ones with version information became
out of date as soon as the next release came around, especially since
we started to work hard at having a correct "HISTORY" section for man pages.
-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?20010724033112.B46693>