Date: Mon, 6 Aug 2001 12:07:00 +0300 From: Ruslan Ermilov <ru@FreeBSD.org> To: John Baldwin <jhb@FreeBSD.org> Cc: Mike Pritchard <mpp@mppsystems.com>, 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: <20010806120700.D1228@sunbay.com> In-Reply-To: <XFMail.010724095938.jhb@FreeBSD.org>; from jhb@FreeBSD.org on Tue, Jul 24, 2001 at 09:59:38AM -0700 References: <20010724033112.B46693@mppsystems.com> <XFMail.010724095938.jhb@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Jul 24, 2001 at 09:59:38AM -0700, John Baldwin wrote: > > 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. > If you are just going to look at the _output_ of the sx.9 on a different OS, you should copy and view the .cat version of the manpage in question generated on the "native" OS. You will probably only need the _source_ of the manpage if you are going to port this feature to another OS, and then you should at least edit the manpage and put the relevant credits to the HISTORY section. > > 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. > .Os (by design) should document the operating system/release the manpage is written for. Currently, an empty (or ever missing) .Os call causes the default value to be substituted. Historically, original CSRG manpages were written with an empty .Os call causing the default "BSD" to be displayed. The default has since been changed to "FreeBSD X.Y". > > 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. > Not when they are read "properly" -- you should be viewing the .cat version of the manpage. Just copying some foreign code and compiling it on a given system may not work at all or not work properly. Similarly for manpages. If you take a Linux binary, and run it under emulation, it will work. If you take a Linux sources for this binary, you may not even be able to compile it on FreeBSD. Similarly for manpages. If you take the "raw" source for the manpage, you may not even be able to "compile" it (-mdoc package may be of different version or missing, etc.). If you take the "binary" of the manpage (preprocessed output), you should be able to read it exactly as it was seen on the targetted OS. Cheers, -- Ruslan Ermilov Oracle Developer/DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010806120700.D1228>