Subject: Linux-Activists - DOC Channel digest. 93-6-22-4:32
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Thu, 22 Jul 1993 10:09:02 +0300

Topics:
	 SAG -- tsx-11
	 "CONFORMING TO" flames

----------------------------------------------------------------------

From: <[email-masked]>
Subject: SAG -- tsx-11
Date: Thu, 22 Jul 1993 03:51:15 +0300

I have placed all of the SAG files at
tsx-11.mit.edu:/pub/linux/ALPHA/{LDP,linux-doc-project}/sag*

michaelkjohnson

------------------------------

From: Rik Faith <[email-masked]>
Subject: "CONFORMING TO" flames
Date: Thu, 22 Jul 1993 04:36:14 +0300

*** FLAME ON ***

For some reason, we have decided to have a "CONFORMING TO" field on our man
pages.  I think this field should actually *mean* something.  For example,
consider brk(2).  It conforms to everything:

    SVID, AT&T, POSIX, X/OPEN OPT, BSD 4.3

This is useless: I don't know what AT&T means, and I don't know how X/OPEN
effects my life.  I think POSIX, BSD, and System V are sufficient (POSIX.1
includes the C Standard).

This example is also *WRONG*: POSIX.1 and the C Standard SPECIFICALLY
EXCLUDE BRK(2) from their definitions (see paragraphs B.1.1.1.3 and B.8.3.3
of POSIX.1 for an explaination).  Further, the man page as written (which
did not describe the actual behavior of the function when called from a
user-level program) did not conform to BSD 4.3, and probably didn't conform
to anything else, since it was so wrong -- no one implements brk(2) the way
the man page said Linux implemented it.  Clearly, whoever put the
CONFORMING TO section into brk(2) didn't check any standards.

*** FLAME OFF *** 

I think that we should be very careful with the COMFORMING TO field.  Maybe
we should remove it: most of our error reporting does not "conform" exactly
to anything, and many of our functions do almost-but-not-quite what the
standards say they should.  Instead of wasting time on this CONFORMING TO
field, perhaps we should concentrate on getting correct information into
the man pages, and then use that description as the "Linux Standard."

I realize that it is a pain in the ass to write man pages, and I really
appreciate all the effort everyone has been putting into them.  However,
the CONFORMING TO field merely makes the man page writer's job harder
without really contributing anything to the man page.

Send comments to the list -- we haven't have a flame war in a while :-)

------------------------------

End of DOC Digest
*****************
-------