Date: Mon, 6 Aug 2001 18:51:39 +0930 From: Greg Lehey <grog@FreeBSD.org> To: John Baldwin <jhb@FreeBSD.org>, Mike Pritchard <mpp@mppsystems.com>, cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, doc@FreeBSD.org Subject: Re: Which OS does a man page come from? (was: cvs commit: src/bi Message-ID: <20010806185139.I69153@wantadilla.lemis.com> In-Reply-To: <20010806120700.D1228@sunbay.com>; from ru@FreeBSD.org on Mon, Aug 06, 2001 at 12:07:00PM %2B0300 References: <20010724033112.B46693@mppsystems.com> <XFMail.010724095938.jhb@FreeBSD.org> <20010806120700.D1228@sunbay.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Monday, 6 August 2001 at 12:07:00 +0300, Ruslan Ermilov wrote: > 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: >>>> >>> 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. Why? What if I don't have the native OS? What if I use the man pages anyway, even after being told to do so? Where do we supply the cat pages for FreeBSD for download? I don't buy this "should". > 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. No, I will need the source of this man page if I want to save space. Or if I want to format it multiple times for different output devices. >>> 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. I'm in agreement with you on that one. > Currently, an empty (or ever missing) .Os call causes the default > value to be substituted. That's a reasonable default. > 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". That's fine. But remember "default" originally meant "mistake". We should consider a missing .Os to be a mistake. >>> 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. Why? That's your claim, but it doesn't make any sense to me. cat pages are typically made exactly when they *are* used on the same OS as they were intended for. > Just copying some foreign code and compiling it on a given system > may not work at all or not work properly. Similarly for manpages. I thought the stated intent of mdocNG was precisely that they should be portable. This seems to be the only justification for a number of the changes which seem otherwise just plain wrong, such as shifting the names to upper case. Greg -- See complete headers for address and phone numbers 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?20010806185139.I69153>