Date: Mon, 23 Feb 1998 17:53:19 -0500 (EST)
Message-Id: <199802232253.RAA10395@delorie.com>
From: DJ Delorie <dj AT delorie DOT com>
To: george DOT foot AT merton DOT oxford DOT ac DOT uk
CC: eldredge AT ap DOT net, djgpp-workers AT delorie DOT com
In-reply-to: <Pine.OSF.3.95.980223060123.517C-100000@sable.ox.ac.uk> (message
	from George Foot on Mon, 23 Feb 1998 06:16:53 +0000 (GMT))
Subject: Re: Suggestion: Portability section for libc docs
Precedence: bulk


> mkdoc doesn't use any advanced C++ -- just member functions in a struct,

Yup, I don't use "full" C++ unless the task calls for it.  Otherwise,
C++ is used so that I can declare variables where they're used and
maybe implement a class to contain some group of related functions
with their data.

> AFAICS.  I presume that it's not intended to implement a versatile macro
> system; just enough to handle the portability information. In this case
> I'd revise the suggestion to something like this:
> 
> : @subheading Portability

I would have done something even simpler:

@port-note borland Borland's function take only two parameters
@port-note msc MS
@portability ansi posix ~borland ~msc

Note that the port-note lines come before the portability line, and
each starts with a keyword matching one of the portability keywords.
Again, ~ means "sort of compatible"; one would expect a note for each ~.

Putting the notes first means that you can generate the texinfo as
soon as you see the portability line.

> This relies on us adding specific code to mkdoc to deal with the
> portability information, rather than generic macro expansion code.  I
> personally think this is appropriate; mkdoc is a specialist utility.

Agreed.