Date: Sat, 8 Jul 2000 21:51:29 -0400 Message-Id: <200007090151.VAA03172@envy.delorie.com> From: DJ Delorie To: djgpp-workers AT delorie DOT com CC: djgpp-workers AT delorie DOT com In-reply-to: <396792CB.85E1BCDE@phekda.freeserve.co.uk> (message from Richard Dawe on Sat, 08 Jul 2000 21:44:59 +0100) Subject: Re: mkdoc patch, take 2 References: <396792CB DOT 85E1BCDE AT phekda DOT freeserve DOT co DOT uk> Reply-To: djgpp-workers AT delorie DOT com Errors-To: nobody AT delorie DOT com X-Mailing-List: djgpp-workers AT delorie DOT com X-Unsubscribes-To: listserv AT delorie DOT com Precedence: bulk > The distinction between C89 and C99 is a special case of a more general > problem, so I decided to rework the way the portability info is done, in a > backwards-compatible way. Here's how the new system works. The whole thing > is table-driven. Each portability target has several "qualifiers". So > there's an ANSI ISO/C target "ansi", for which there are qualifiers > "-c89", "-c99". 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. > Each target has a default status for each qualifier, so if > you just use: > > @portability ansi > > it defaults to C89 portability. You could have: 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. > @portability ansi-c89, !ansi-c99 How much stuff would qualify for this particular example? > We might want to add 4.2BSD or 4.4BSD too, e.g. unix-4.2-bsd, > unix-4.4-bsd. 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. > ANSI/ISO C not C89 (see note 1); not C99 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. > 2. With the default qualifiers for the ansi target, C89 compatibility is > set to yes, but C99 is set to unknown. Should the unknown part be > displayed in the portability? I think this could be confusing for users. 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. > 1. Add an option to dump out the table of targets and their qualifiers. That would be useful. > 2. Make @port-note be a multi-line @ command, e.g. > > @port-note ansi > This > uses > four > lines. > @end port-note Since mkdoc is the only thing parsing @port-note, there's no reason not to automatically support both syntaxes. If there's text after the keyword, it's a single-line note. If not, assume it's a multi-line note.