Date: Mon, 24 Aug 1998 20:26:31 -0400 (EDT)
Message-Id: <199808250026.UAA20275@delorie.com>
From: DJ Delorie <dj AT delorie DOT com>
To: george DOT foot AT merton DOT oxford DOT ac DOT uk
CC: djgpp-workers AT delorie DOT com
In-reply-to: <E0zB6bm-0005zZ-00@sable.ox.ac.uk>
	(george DOT foot AT merton DOT oxford DOT ac DOT uk)
Subject: Re: Patch to mkdoc and re: portability information
Precedence: bulk


Some thoughts:

It would be nice if mkdoc.cc could automatically generate the
"@section Portabillity" line as well.  That way, we could change it
globally later.

"dos" should imply whatever the untainted DOS interrupts would do; for
example, rename() does not just call int 0x21 ah=0x56 and open() calls
different things depending on LFN.  We don't need to specify
other-compiler-specific things.  If Borland and MSC differ, we should
note how DJGPP acts in that case since "dos compatible" obviously
isn't well defined.  However, we don't need to say "differs from MSC"
we just need to say "does it this way" or "doesn't do it that way", to
highlight the djgpp-specific ways that dos programmers might get
confused.

Same for Unix.  For example, sprintf sometimes returns an int, and
sometimes a char*.  We should document what we return in the regular
documentation, and in port-nodes for "unix" simply say "djgpp returns
foo, but some unix systems return blah".

"unix" compatibility means things that are usually found in Unix
systems, aside from ANSI and POSIX.  An example might be sys_siglist.

If the port section notes ANSI or POSIX compatibility, Unix
compatibility need not be mentioned.  If ANSI is mentioned, POSIX need
not be mentioned, since in general those three "systems" are proper
supersets: ANSI < POSIX < Unix, even though some unix systems don't
provide all POSIX functions.

For ANSI and POSIX compatibility, there are actually four cases:

* We follow the spec (i.e. malloc())
* We do not follow the spec (i.e. posix requires text files use \n not \r\n)
* The spec doesn't define this function (i.e. _bios_print())
* The spec precludes this function (i.e. biosprint(), but not _bios_print())

The last case should be for functions that, by default, are pulled in
by spec-required headers (like stdio.h) but pollute the spec's name
space.  Such functions could be removed by #defining the appropriate
symbol (i.e. _POSIX_SOURCE).

We had originally agreed that, for the first pass, we would divvy up
the files by header.  Just post here before you start a header saying
"I'll do X for ANSI" or something like that.  As usual, submit changes
as diffs from the top directory so I can apply them easily.

Anyone want to write a utility to generate an HTML compatibility
table?  All it would have to do is list Y/N/P/V (yes, no, partial,
violates spec) in each column, or the symbols right from the @port
line (+, !, ~).

DJ