From owner-freebsd-doc Mon Aug 6 2:22: 1 2001 Delivered-To: freebsd-doc@freebsd.org Received: from wantadilla.lemis.com (unknown [192.109.197.80]) by hub.freebsd.org (Postfix) with ESMTP id 24F1737B401; Mon, 6 Aug 2001 02:21:43 -0700 (PDT) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id 6EFD96ACCA; Mon, 6 Aug 2001 18:51:39 +0930 (CST) Date: Mon, 6 Aug 2001 18:51:39 +0930 From: Greg Lehey To: John Baldwin , Mike Pritchard , 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> References: <20010724033112.B46693@mppsystems.com> <20010806120700.D1228@sunbay.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20010806120700.D1228@sunbay.com>; from ru@FreeBSD.org on Mon, Aug 06, 2001 at 12:07:00PM +0300 Organization: The FreeBSD Project Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-418-838-708 WWW-Home-Page: http://www.FreeBSD.org/ X-PGP-Fingerprint: 6B 7B C3 8C 61 CD 54 AF 13 24 52 F8 6D A4 95 EF Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org 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