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> In-Reply-To: <20010428141016.B65625@sunbay.com>; from ru@FreeBSD.ORG on Sat, Apr 28, 2001 at 02:10:17PM %2B0300 References: <200104261713.f3QHDUU90290@freefall.freebsd.org> <20010428055232.A54517@mppsystems.com> <20010428141016.B65625@sunbay.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010428064515.A55534>