Date: Tue, 25 Aug 1998 13:41:22 -0400 (EDT)
Message-Id: <199808251741.NAA10295@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: <E0zBMqc-0000Hg-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


> Hmm.  So `dos' would mean "this is a raw DOS call", rather than
> "this function behaves in the same way on djgpp as it does on other 
> DOS compilers".

No, "dos" means it does what you'd expect a dos compiler to do, and
most dos compilers hook right into the dos interrupts.

> Also bearing in mind the fact that ANSI and POSIX are standards while 
> Unix (and possibly DOS) is just a general class holding various 
> compilers, perhaps we should say instead something like:
> 
>     Defined by ANSI.  Generally available on Unix and DOS.
> or
>     Defined by POSIX but not ANSI.  Generally available on Unix but not DOS.
> or
>     Not defined by ANSI or POSIX.  Not generally available on Unix or DOS.

Perhaps a small section at the beginning talking about portability,
and cut out the long descriptions on each page.  A simple
"Portability: POSIX" will do on the individual function pages.

> > 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).
> 
> How should these four possibilities be listed?  Any of the latter 
> three would mean that djgpp code calling the function wouldn't work 
> on other systems, while the second and possibly the fourth cases 
> would mean that code for other compilers wouldn't work on djgpp.  
> Under the current system I think the second case corresponds to "~" 
> (partial) and the last two to "!" (not).  Do you want the 
> documentation to differentiate between the last two cases?

I don't know.  Just a thought for discussion.

> > 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.
> 
> Oh, I thought we were doing branches of the source tree -- not quite 
> the same thing.

Almost the same thing, since the source branches corrspond to headers.