Date:	Sat, 28 Feb 1998 12:07:51 -0800 (PST)
Message-Id:	<199802282007.MAA15200@adit.ap.net>
Mime-Version:	1.0
To:	DJ Delorie <dj AT delorie DOT com>, george DOT foot AT merton DOT oxford DOT ac DOT uk
From:	Nate Eldredge <eldredge AT ap DOT net>
Subject:	Re: Suggestion: Portability section for libc docs
Cc:	djgpp-workers AT delorie DOT com

At 12:05  2/27/1998 -0500, DJ Delorie wrote:
>
>> > The only other ones I can think of that we might need are "dos",
"unix", and
>> > perhaps "windows".
>> 
>> Yes.  I just put in ANSI and POSIX because they're the simplest to do on
>> the first pass.
>
>ansi and posix are definite.  I think "dos" doesn't make sense; it's
>not a compiler.  "unix" is too vague, and ansi/posix should cover it.

Not always. Take, for instance, the case of `sbrk'. AFAIK, it is not POSIX,
yet it is practically universal on Unix systems. 

>"windows" is also not a compiler.  I'd recommend ansi, posix, and
>maybe bc and msc, potentially with a digit after to indicate a version
>number (i.e. msc7 or bc3).  After all, they're the most popular
>platforms people will be interested in being portable to.  Maybe add
>cygwin?

I guess we have a confusion here. I was envisioning talking about
portability to general classes of targets, like "dos" = "dos compilers in
general", etc. This will give people an idea of what sort of platforms they
can expect to be portable to. Where a specific compiler differs from its
brethren, it would be specially noted by the `port-note' mechanism. I
suspect there will be few cases where, say, MSC provides a function and
Borland does not. There will probably be only functionality differences,
which would require a note in any case.

IMHO, your method would result in us having many, many targets to keep track
of, which I thought was to be avoided. We might end up with such things as:

BC v1, BC v2, BC v3, BC v4, MSC v1, MSC v2, MSC v3, Watcom, Zortech, Linux, BSD,
        SysV, ...

which IMHO is less clear than my idea.

>
>> > IMHO, functions that don't mention a target should just not mention it.
>> [snip]
>> 
>> That conflicts with the proposed tabular format -- all the columns would
>> (presumably) exist in each function's documentation, so those not
>> explicitly mentioned would implicitly be documented as "no"s.  I may have
>> misunderstood here though -- we can of course make the table only contain
>> columns for mentioned targets.
>
>If a target isn't mentioned, put "?" or "unknown", or omit that column
>in the table (after all, we only have one function per table!).
>
>> The "!dos" sounds sensible, yes -- this can be added easily.
>
>Unfortunately, this means that every function needs to list every
>compiler we support.  Don't know if that's better than assuming
>unlisted means unsupported.

That's a good point, but IMHO also would be helped by having a very few
general targets. George's idea of "unlisted" == "you figure it out" seems good.

>
>> > Yeah, that should be fine, because we can even do:
>> > 
>> > @port-note dos This note about portability to Borland is very very long and
>> > @port-note dos doesn't fit on a single line.
>> 
>> That's relying on the way the output is formatted.  If @port-note simply
>> writes the following:
>
>mkdoc should combine port-note's with the same keyword, in the order
>they're given, into a single note.

That would not work with my idea, because MS and Borland notes would be
combined, obviously the Wrong Thing. Otherwise, that probably makes sense.

Nate Eldredge
eldredge AT ap DOT net

- Raw text -