Date: Tue, 24 Feb 1998 20:19:00 -0500 (EST)
Message-Id: <199802250119.UAA21994@delorie.com>
From: DJ Delorie <dj AT delorie DOT com>
To: eldredge AT ap DOT net
CC: djgpp-workers AT delorie DOT com
In-reply-to: <199802250048.QAA28537@adit.ap.net> (message from Nate Eldredge
	on Tue, 24 Feb 1998 16:48:45 -0800 (PST))
Subject: Re: Suggestion: Portability section for libc docs
Precedence: bulk


> IMHO, this is important. Being limited to one line in the comment would be
> very annoying.

Long comments should be possible, but not necessarily convenient.

The need for long comments in the portability section should be
limited (that was a request, not an observation).  The only case where
a portability issue should be discussed at length is when DJGPP
deviates from the expected (or defined) functionality.  In that case,
the note should go in the regular documentation, not the portability
section.  Notes in the portability section should be limited in
length, because I expect we'll be talking about other compilers here,
which is not the goal of the djgpp documentation.  Short notes, like
"bc3 - needs <stddef.h>" or "msc - only two parameters" are enough;
people who really need more information (about porting *to* those
compilers) should have those manuals handy.  People porting to djgpp
from those compilers should find the info they need in the main body
of the documentation.

I guess this boils down to "what's the portability section for?"

Here's my opinion: it's for people who want to write portable code.
Those people need to know not only how djgpp does it (the regular
docs) but also enough information to decide if they want to avoid a
particular function because of portability reasons.  This section
should have enough information to make that decision, and no more.

> Perhaps I'm confused, but from DJ's example it looked as though it would be
> possible for the "keywords" to be non-magical. That is, any word could be
> used as a header instead of "ANSI" or "Borland", etc. I'd like to suggest we
> do that, so we don't have to hack `mkdoc' again each time we want to add
> something.
> 
> So the keywords would only be "key" in the sense that we'd standardized on
> them for consistency, not that there's something special about them.

Actually, I *was* thinking of hardcoding them into mkdoc, but I
suppose mkdoc could read a separate config file that gives the
expected tokens (mkdoc can report on others it finds) with full names
and the order they are to be listed in.

> >lconv.c:27: warning: excess elements in struct initializer after `__lconv_'
> 
> I saw this too. I suspect it's due to mixing 2.02 source with the 2.01
> headers. Although I haven't tried it, I suspect that installing djdev202
> first will fix it.

This might be a bug in 2.02 also, since I had to *add* a field to that
structure (posix required it, but I missed it the first time around in
2.01).