From owner-cvs-all  Sat Apr 28  4:45:24 2001
Delivered-To: cvs-all@freebsd.org
Received: from mppsystems.com (mppsystems.com [208.210.148.205])
	by hub.freebsd.org (Postfix) with ESMTP
	id 26F3C37B43E; Sat, 28 Apr 2001 04:45:16 -0700 (PDT)
	(envelope-from mpp@mppsystems.com)
Received: (from mpp@localhost)
	by mppsystems.com (8.11.3/8.11.3) id f3SBjFW55610;
	Sat, 28 Apr 2001 06:45:15 -0500 (CDT)
	(envelope-from mpp)
Date: Sat, 28 Apr 2001 06:45:15 -0500
From: Mike Pritchard <mpp@mppsystems.com>
To: cvs-committers@FreeBSD.ORG, cvs-all@FreeBSD.ORG
Subject: Re: cvs commit: src/share/doc/papers/memfs Makefile src/share/misc mdoc.template src/share/man/man7 Makefile man.7 mdoc.7 mdoc.samples.7 src/share/examples/mdoc example.1 example.3 example.4
Message-ID: <20010428064515.A55534@mppsystems.com>
References: <200104261713.f3QHDUU90290@freefall.freebsd.org> <20010428055232.A54517@mppsystems.com> <20010428141016.B65625@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: <20010428141016.B65625@sunbay.com>; from ru@FreeBSD.ORG on Sat, Apr 28, 2001 at 02:10:17PM +0300
Sender: owner-cvs-all@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.ORG

On Sat, Apr 28, 2001 at 02:10:17PM +0300, Ruslan Ermilov wrote:
> > >   Modified files:        (Branch: RELENG_4)
> > >     share/examples/mdoc  example.1 example.3 example.4 
> > [...]
> > >   Log:
> > >   MFC: Upgrade to Groff 1.17.
> > >   
> > >   Revision  Changes    Path
> > >   1.12.2.4  +3 -7      src/share/examples/mdoc/example.1
> > >   1.12.2.5  +4 -8      src/share/examples/mdoc/example.3
> > >   1.10.2.3  +3 -7      src/share/examples/mdoc/example.4
> > 
> > I missed this on the first go round, but in the example
> > man pages, they had comments that read like so:
> > 
> > .\" Note: Only specify the operating system when the command
> > .\" is FreeBSD specific, otherwise use the .Os macro with no
> > .\" arguments.
> > 
> > These were removed by this MFC, and presumabliy by the original
> > commit.
> > 
> > I think the comments are still valid, although with how we are doing 
> > man pages these days, I might re-word it so it might be better:
> > 
> > Note:  Only specify the operating system and version when 
> > the command is FreeBSD specific, or when it is documenting a 
> > deprecated interface.
> > 
> Nope, one should not use arguments to the .Os call anymore,
> they are computed automatically.  For -CURRENT, this will be
> FreeBSD 5.0, for -STABLE this will be FreeBSD 4.3 for the
> moment.
> 
> > And maybe for those few man pages that are actually documenting
> > obsoleted interfaces, they should have an "OBSOLETE" header right
> > at the start of the man page.
> > 
> Any examples of where this would be required would be great.
> I see plenty of manpages in lib/libc/compat-43/ that say they
> are obsolete.  But even in these manpages, .Os should be empty.

Then why have an .Os macro at all?  If they are all blank, and
printing "FreeBSD", then .Os should just go away.  The compat man
pages sound like the best reason for leaving .Os, and actually using
it.  We do document interfaces we no longer support.  The man pages
should have some way to specify that they are documenting "something
else".

-Mike
-- 
Mike Pritchard
mpp@FreeBSD.org or mpp@mppsystems.com

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message