Skip site navigation (1)Skip section navigation (2)
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 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?20010806185139.I69153>