Date: Thu, 22 Jun 2000 16:06:40 +0200 From: Sheldon Hearn <sheldonh@uunet.co.za> To: doc@FreeBSD.org Subject: Improving STANDARDS section of the manual domain Message-ID: <43674.961682800@axl.ops.uunet.co.za>
next in thread | raw e-mail | index | archive | help
[LONG]
Hi folks,
My project for FreeBSD 5.0-RELEASE (hopefully still a way off) is to
bolster the STANDARDS section of our manual domain, such that folks who
understand the notion of STANDARDS can rely on the section to protect
them from making portability mistakes.
An easy example to pick on is the open(2) system call, which provides
the non-standard flag O_EXLOCK. This flag is not mandated by POSIX and
you run into serious trouble when you build cooperative software which
uses this flag and then try to port it.
I could have been saved hours of trouble if I'd seen a STANDARDS
section at the bottom of the manual page.
I understand that this is not something that many people can help me
with, because the job requires access to the POSIX books, which are
expensive. However, at this stage, I'd like to get feedback on the
planned approach.
Here's the STANDARDS section of the ls(1) manual page as it stands:
STANDARDS
The ls function is expected to be a superset of the IEEE Std1003.2
(``POSIX.2'') specification.
I'd like to make it so:
STANDARDS
The ls utility conforms to the IEEE Std1003.2 (``POSIX.2'') specification
and Version 2 of the Single UNIX Specification with the following excep
tions:
· The following options are not defined in either specification: -A,
-B, -G, -H, -L, -P, -T, -W, -b and -k.
· The following options do not conform to the definitions found in
Version 2 of the Single UNIX Specification: -f, -g, -n, -o and -s.
· The following options are defined in Version 2 of the Single UNIX
Specification but are not implemented: -m, -p and -x.
I'm focusing predominantly on POSIX, SUSv2 and ISO IEC 9899:1999 for
this pass at the manual pages. I like the idea of having all the
standards-related information in one section, which programmers (whether
using C or the shell) can flip to and rely on.
One danger in this approach, pointed out to me by Mark Murray, is that
it is easy for new options to be added and existing options to be
changed without regard for the STANDARDS section.
While this is true, the alternative seems to be to clutter the rest
of the manual page with parenthesized chirps for each option and
characteristic. I don't like that idea, and I'd prefer to simply say
that folks with an interest in the manual domain need to watch it like a
hawk for bit rot. Some of us already do so.
What I'm looking for now are either comments that suggest that my
intended approach is a good idea, or comments that enlighten me by
providing a much better way of achieving my stated goal. I'm _not_
looking for dismissive remarks that do not offer any kind of
alternatives. :-)
Thanks for your time.
Ciao,
Sheldon.
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?43674.961682800>