Date: Tue, 24 Jul 2001 09:59:38 -0700 (PDT) From: John Baldwin <jhb@FreeBSD.org> To: Mike Pritchard <mpp@mppsystems.com> Cc: Ruslan Ermilov <ru@FreeBSD.org>, cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, doc@FreeBSD.org, Greg Lehey <grog@FreeBSD.org> Subject: Re: Which OS does a man page come from? (was: cvs commit: src/bi Message-ID: <XFMail.010724095938.jhb@FreeBSD.org> In-Reply-To: <20010724033112.B46693@mppsystems.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 24-Jul-01 Mike Pritchard wrote: > 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. So? Surely they are competent enough to update their .Os macros when they port software. Also, you are assuming this happens for all features. It doesn't. If I copy sx.9 to a NetBSD box and view it, it claims NetBSD implements sx locks. This is _wrong_. This is a _lie_. If I copy lockmgr.9 with an .Os FreeBSD in it to a NetBSD box, it claims that FreeBSD implemenets lockmgr(). It doesn't say that NetBSD doesn't. > 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. Erm, isn't that what .Sh HISTORY is for? If you include a version number in the .Os line, it should probably list the range of all versions that the docuemented feature/API was valid for. I'm not sure mdoc likes version ranges however, and it would involve a lot of fixup work for old manpages. > 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. When our manpages are read on another OS, they "are documenting a feature of another operating system". You've just proved my point. -- 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?XFMail.010724095938.jhb>