Date: Thu, 27 Aug 1998 14:02:11 +0300 (IDT)
From: Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
To: George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
cc: djgpp-workers AT delorie DOT com
Subject: Re: Patch to mkdoc and re: portability information
In-Reply-To: <E0zAhTX-0008K6-00@sable.ox.ac.uk>
Message-ID: <Pine.SUN.3.91.980827140146.6326C-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk


On Sun, 23 Aug 1998, George Foot wrote:

> Here's an example, for the `fflush' function:
> 
>     @subheading Portability
>     
>     @port-note Borland 
>     Borland has an extension to @code{fflush}; it lets you fflush an 
>     input stream, purging all characters.  DJGPP does not support this.
>     
>     @portability ansi posix ~borland

Is it really necessary to have port-note's *before* the @portability
tag?  It's kinda counter-intuitive (a note to something that's not
written yet?).  This is nitpicking, of course.

> Personally I think DOS compilers should be a single category; we can
> list individual compilers' differences in notes if it's thought to be
> necessary.

I agree.

> I don't know about Unix compilers; presumably they all
> support ANSI and POSIX but after that do they differ a lot from each
> other?

They do, but I don't think we should be worried with that at first.
We can always put any important differences as @port-note's.

> We also need to decide where in the documentation the portability
> information should go;

I think it should be right after the Description and Return Value
parts.

> Finally we need to go through the .txh files adding the information.  
> This is a big task, but not very difficult to do at a simple level, 
> since the header files already show whether a function is defined in 
> ANSI or POSIX or neither.

You could do this with a program, or even a Sed script, since the
__STRICT_ANSI__ and __POSIX_SOURCE symbols tell the whole story.