From owner-cvs-all Sat Apr 28 5:26:34 2001 Delivered-To: cvs-all@freebsd.org Received: from whale.sunbay.crimea.ua (whale.sunbay.crimea.ua [212.110.138.65]) by hub.freebsd.org (Postfix) with ESMTP id 05ACD37B42C; Sat, 28 Apr 2001 05:26:19 -0700 (PDT) (envelope-from ru@whale.sunbay.crimea.ua) Received: (from ru@localhost) by whale.sunbay.crimea.ua (8.11.2/8.11.2) id f3SCPxj73811; Sat, 28 Apr 2001 15:25:59 +0300 (EEST) (envelope-from ru) Date: Sat, 28 Apr 2001 15:25:59 +0300 From: Ruslan Ermilov To: Mike Pritchard Cc: 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: <20010428152559.A72985@sunbay.com> Mail-Followup-To: Mike Pritchard , cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org References: <200104261713.f3QHDUU90290@freefall.freebsd.org> <20010428055232.A54517@mppsystems.com> <20010428141016.B65625@sunbay.com> <20010428064515.A55534@mppsystems.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20010428064515.A55534@mppsystems.com>; from mpp@mppsystems.com on Sat, Apr 28, 2001 at 06:45:15AM -0500 Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG On Sat, Apr 28, 2001 at 06:45:15AM -0500, Mike Pritchard wrote: > 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". > That was my secret :-) Yes, the .Os macro is no longer required at all actually. This happened here, as a side effect: : 2001-03-30 Ruslan Ermilov : : Remove .Ld from mdoc package; replace it with special handling of : `...'. : : * tmac/doc-common: Remove `Ld' register. : Uncomment `doc-volume-ds-*' strings. : Remove `doc-operating-system-default'. : (Os): Updated. : * tmac/doc-syms (Ld): Removed. : * tmac/doc.tmac (doc-parse-args, doc-parse-arg-vector): Handle : `...' specially. : * NEWS: Updated. : : * tmac/groff_mdoc.man: Many fixes and updates. Previously, if one missed the .Os call, then an empty left bottom corner would be printed. Currently, if the .Os call is missing, or .Os called without arguments, the default OS string is printed. I am about to remove the .Os calls from all FreeBSD manpages. NetBSD and OpenBSD did some a long time ago, but they left .Os call because of the old (empty corner) problem. But this can take some time, as most manpages abuse .Os macro for HISTORY related info. Most BSD manuals actually have duplicate .Os and HISTORY contents. But this should be given an eye check. Cheers, -- Ruslan Ermilov Oracle Developer/DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message