Date: Thu, 12 Feb 1998 06:58:08 +0000 (GMT)
From: George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
Reply-To: George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
To: Nate Eldredge <eldredge AT ap DOT net>
cc: Ned Ulbricht <nedu AT ee DOT washington DOT edu>, djgpp-workers AT delorie DOT com
Subject: Re: Suggestion: Portability section for libc docs
In-Reply-To: <199802120241.SAA17242@adit.ap.net>
Message-ID: <Pine.OSF.3.95.980212052420.31947C-100000@sable.ox.ac.uk>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk

On Wed, 11 Feb 1998, Nate Eldredge wrote:

> I wonder how should we coordinate all this. Do we swamp djgpp-workers with
> passing these lists back and forth? Is that a problem? 

I don't think that would be necessary.  Let volunteers choose which bits
of the source tree they want to do (i.e. name a subdirectory and do every
function whose documentation is below that directory) by sending email
directly to you (or some other entity). It might be worth keeping a
quickly-updatable web page somewhere with a list of already-claimed
directories, so that people can know accurately which ones are still free
(I could host this if you like); the updates would have to take immediate 
effect for it to be of any use, of course (mine would; I'm NFS-linked to
the web server).  Perhaps DJ would rather put it on delorie.com.


> >(since all Unices are POSIX, aren't they?).
>         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> In a perfect world, yes. In real life, no. But I suspect as far as a C
> library goes, most Unices will be close.

... and their non-compliance is really their fault, not ours.


> Okay, here's an imaginary example of how an entry might look. I'll have to
> look over how the Texinfo formatting would work, but I believe it's simple.
> It's off the top of my head, but I hope it gives the basic idea.
> 
> `frob'
> 
> #include <foobar.h>
> int frob();
> ...
> Portability
> 
> POSIX. Provided by other DOS compilers, in <mumble.h>.
> Most DOS compilers don't twiddle the frobozzicator when calling this
> function. Borland C does.

I think we should mention both ANSI and POSIX in all entries, for clarity;
i.e.:

    Portability
        POSIX, not ANSI, DOS (in <mumble.h>)

        Most DOS compilers... [i.e. general notes]

IMHO this is clearer; I like the brevity.  The first line does look rather
like Borland's information though; is Ned's `secondary concern' a real
problem? I don't think anyone could sue based upon the style of a small
part of the documentation (I thought look-and-feel sueing died) and the
fact remains that we're not stealing from their docs -- we're writing this
ourselves, from scratch, in a completely different format to Borland's.

FWIW I think that copying Borland's portability information verbatim would
be a distinctly bad method; they might have got it wrong in places, and
the portability information we provide ought to be consistent with the
header files IMHO.


> Oh, another thought. Should this be worked on relative to the 2.02 alpha, or
> just to 2.01? I think 2.02 adds some documentation.

If we work relative to the latest alpha, we have to catch any further
documentation updates that occur as we work.  If we base our work on 2.01,
we must redo all the files which have changes since then.  I don't know
the extent of these changes, but judging by traffic here they seem fairly
substantial.

We could write the portability sections separately for now, and insert
them into the 2.02 docs at any time, whatever changes have occured to the
other docs.  This ought to be fairly simple to organise, but whether or
not it's worth going to the trouble really depends on (a) the magnitude of
changes since 2.01 and (b) the number of changes which occur as we work.
I personally think context diffs ought to work fairly well in most cases.

> If we do, can somebody
> do me a favor and give me a complete pointer to the alpha? I can only ftp
> through an ftp-email server, and searching for things that way is very
> tedious. (Yes, I do plan to get better Internet service Real Soon Now...)

Ouch, bad luck.  Relative to the base djgpp directory, the alphas are in
v2/alphas.  According to ftp.cdrom.com, the latest is 980101, and the
library sources are of course in djlsr202.zip.  So: 

/pub/simtelnet/gnu/djgpp/v2/alphas/980101/djlsr202.zip

-- 
george DOT foot AT merton DOT oxford DOT ac DOT uk