From owner-cvs-all Tue Jul 24 10: 0:12 2001 Delivered-To: cvs-all@freebsd.org Received: from meow.osd.bsdi.com (meow.osd.bsdi.com [204.216.28.88]) by hub.freebsd.org (Postfix) with ESMTP id E8EB837B409; Tue, 24 Jul 2001 09:59:49 -0700 (PDT) (envelope-from jhb@FreeBSD.org) Received: from laptop.baldwin.cx (john@jhb-laptop.osd.bsdi.com [204.216.28.241]) by meow.osd.bsdi.com (8.11.4/8.11.2) with ESMTP id f6OGxYv19970; Tue, 24 Jul 2001 09:59:35 -0700 (PDT) (envelope-from jhb@FreeBSD.org) Message-ID: X-Mailer: XFMail 1.4.0 on FreeBSD X-Priority: 3 (Normal) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 8bit MIME-Version: 1.0 In-Reply-To: <20010724033112.B46693@mppsystems.com> Date: Tue, 24 Jul 2001 09:59:38 -0700 (PDT) From: John Baldwin To: Mike Pritchard Subject: Re: Which OS does a man page come from? (was: cvs commit: src/bi Cc: Ruslan Ermilov , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org, doc@FreeBSD.org, Greg Lehey Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG 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, >> >> >> >> >> >> >> >> 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 -- 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