Mail Archives: djgpp-workers/1998/08/25/13:26:28
On 24 Aug 98 at 20:26, DJ Delorie wrote:
> It would be nice if mkdoc.cc could automatically generate the
> "@section Portabillity" line as well. That way, we could change it
> globally later.
OK. The reason I didn't make it do this was that the portability
documentation seemed to blend in with the existing text in the .txh
files.
> "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.
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".
> 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".
That seems sensible, since we're documenting djgpp's library, not the
Unix compilers' libraries.
> 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.
Presumably ANSI is also a superset of general DOS behaviour -- but
not under your definition of DOS behaviour above.
I'll make it assume at the input stage that if POSIX is not mentioned
ANSI => POSIX, and if Unix is not mentioned POSIX => Unix, and I'll
make it not mention POSIX at the output stage if the function is both
ANSI and POSIX, and not mention Unix if the function is POSIX and
Unix. This way we have a sensible default (so the information in the
.txh files only needs to say ANSI to cause POSIX and UNIX to be
assumed) but still have a mechanism for noting that a function does
not obey these rules, in case one turns up.
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.
This explains to the reader what the categories really mean, and I
think it's clearer.
> 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?
> 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.
> 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 (+, !, ~).
Presumably "yes" means the first case above, "no" means the third,
"partial" means the second and "violates spec" means the fourth?
I don't know enough HTML to make the table, but mkdoc.cc could fairly
easily generate this table from the "Node::write_portability" method.
--
george DOT foot AT merton DOT oxford DOT ac DOT uk
- Raw text -