Sender: nate AT cartsys DOT com
Message-ID: <35E1A3D3.AE88F41@cartsys.com>
Date: Mon, 24 Aug 1998 10:33:07 -0700
From: Nate Eldredge <nate AT cartsys DOT com>
MIME-Version: 1.0
To: 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
References: <E0zAhTX-0008K6-00 AT sable DOT ox DOT ac DOT uk>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Precedence: bulk

George Foot wrote:
[snip description of format]

> If everybody approves of the general system outlined above, we need
> to decide what the categories should be.  This patched mkdoc.cc has
> two catogries -- "ansi" and "posix".  Of course it's simple to add
> more.  It's also simple to change the format of the Texinfo output if
> you don't like it.

I think the current scheme looks good, personally.  Though you didn't
say what the Texinfo looks like-- could you post an example of that? 
That's fairly immaterial, however.

> When we discussed this before, people disagreed about which
> categories we should use; should DOS be a category all by itself, or
> should each DOS compiler get its own category?  What about Windows
> compilers?  What about Unix compilers -- can Unix be a single
> category, or would we need to list a lot of flavours?
> 
> 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 don't know about Unix compilers; presumably they all
> support ANSI and POSIX but after that do they differ a lot from each
> other?  If so then we should either give them separate categories or
> not list them at all -- or just say that the function is not
> universally portable to Unix systems, if only some have it.  Again
> we could list in notes which do/don't if you like.

I think we should have categories which cover general types of systems,
and describe specific ones in the notes.  So `sprintf' might be done
like so:

@port-note Unix
Some versions of SunOS return a @code{char *} instead.

@portability ansi posix dos ~unix

And similarly, `stat':

@port-note DOS
Borland and Microsoft compilers do not fill in the @code{st_ino} field.

@portability !ansi posix ~dos unix

I also expect that specifics wouldn't need to be mentioned often.

So `dos' and `unix' would be good categories.  I don't know enough about
Windows to say whether it deserves its own category.  Anyone?

[snip]

> We also need to decide where in the documentation the portability
> information should go; I suggest putting it just before the example
> in nodes which have an example, or at the end of the node if there
> is no example.

I agree.

> 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.
> 
> I don't think it's possible to be more specific all through the docs
> (e.g. mentioning how a function is not quite POSIX) unless you have
> experience using that function and already know how it is different.
> I think that sort of detail needs to be added afterwards bit by bit.
> In extreme cases (like `stat') there's already a lot of information
> given about how the function is awkward to implement in DOS.

This brings me to another question.  Presumably I will be coordinating
this.  I'm not sure what is the best way to reconcile all the changes. 
The usual way is `diff', but there will be several people simultaneously
making changes to the same parts of files, and I don't know how well
`diff' will work in such a case.  Does anyone have any suggestions?
-- 

Nate Eldredge
nate AT cartsys DOT com