Sender: rich AT phekda DOT freeserve DOT co DOT uk
Message-ID: <396A39C1.708E619@phekda.freeserve.co.uk>
Date: Mon, 10 Jul 2000 22:01:53 +0100
From: Richard Dawe <rich AT phekda DOT freeserve DOT co DOT uk>
X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.14 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: djgpp-workers AT delorie DOT com
Subject: Re: mkdoc patch, take 2
References: <396792CB DOT 85E1BCDE AT phekda DOT freeserve DOT co DOT uk> <200007090151 DOT VAA03172 AT envy DOT delorie DOT com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Hello.

DJ Delorie wrote:
> Can we generalize it to "foo-bar" where "foo" is the general target,
> and "bar" is the qualifier?  I'm thinking that the unix98 below should
> be unix-98, to avoid special cases.

Sure, it's already generalised to handle this. "unix98" is only "unix98"
because the qualifier doesn't start with a dash. Requiring a dash could
catch some typos too.

> It could default to not mentioning the qualifier (i.e. "ANSI: Yes")
> but that might be confusing.  Of course, a quick script could update
> all the txh files to meet the new requirements, rather than trying to
> make mkdoc too smart about it.

Yes, I think a script to convert them would be a good idea. It's probably
better to be precise.

> > @portability ansi-c89, !ansi-c99
> 
> How much stuff would qualify for this particular example?

Well, maybe not !ansi-c99, perhaps the floating-point is ~ansi-c99. I
admit I had trouble following the FP discussion a while back, but it
seemed that the new behaviour was slightly incompatible. I may be
completely wrong here. ;)

> Can we dynamically add targets based on what we find in the txh files?
> That way, we can document obscure compatibilities without having to
> update mkdoc each time, or have 99.9% of the tables have a row for the
> obscure targets.

It's more likely that the qualifier will be obscure than the target, e.g.:

Unix: SCO Unixware 8

but I take your point. It may take me a while to add the dynamic targets.
How about the following syntax, using Unixware as an example:

@port-target sco, SCO
@port-qualifier unixware-8, Unixware 8
@port-note sco-unixware-8, It just about works.
@portability posix, ~sco-unixware-8

( I just realised that my comment in my other mail today that "@port-note
ansi blah" should be "@port-note{ansi, blah}" is actually wrong. Please
ignore it. )

> I still recommend that all the "not"s be listed after all the "is"s.
> 
> Plus, if a general target is all "not"s, just say "ANSI/ISO C   No"
> rather than enumerating all the nots.

Yep, I'll make those changes.

> I think simply saying "ANSI(C89)" is sufficient.  One can assume that
> meeting the old spec implies meeting the new spec also, and if that
> assumption is false, we should say so in the docs, and thus it won't
> be unknown.

Sure, we /should/ say so in the docs, but I thought it might be safer to
omit the details until the library had been thoroughly checked. But for
the C standard, I guess we can assume the library (except FP, new stuff)
complies with the newer standard.

Note that the new mkdoc has no concept of newer, so there is no current
way of saying that C99 encompasses C89.

Thanks, bye,

-- 
Richard Dawe
[ mailto:richdawe AT bigfoot DOT com | http://www.bigfoot.com/~richdawe/ ]