Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 28 Apr 2001 15:25:59 +0300
From:      Ruslan Ermilov <ru@FreeBSD.org>
To:        Mike Pritchard <mpp@mppsystems.com>
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>
In-Reply-To: <20010428064515.A55534@mppsystems.com>; from mpp@mppsystems.com on Sat, Apr 28, 2001 at 06:45:15AM -0500
References:  <200104261713.f3QHDUU90290@freefall.freebsd.org> <20010428055232.A54517@mppsystems.com> <20010428141016.B65625@sunbay.com> <20010428064515.A55534@mppsystems.com>

next in thread | previous in thread | raw e-mail | index | archive | help
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  <ru@freebsd.org>
: 
:         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




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010428152559.A72985>