Date:	Thu, 12 Feb 1998 19:28:37 -0800 (PST)
Message-Id:	<199802130328.TAA12320@adit.ap.net>
Mime-Version:	1.0
To:	George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>, <eliz AT is DOT elta DOT co DOT il>
From:	Nate Eldredge <eldredge AT ap DOT net>
Subject:	Re: Suggestion: Portability section for libc docs
Cc:	Ned Ulbricht <nedu AT ee DOT washington DOT edu>, djgpp-workers AT delorie DOT com

At 06:58  2/12/1998 +0000, George Foot wrote:
>On Wed, 11 Feb 1998, Nate Eldredge wrote:
>
>> I wonder how should we coordinate all this. Do we swamp djgpp-workers with
>> passing these lists back and forth? Is that a problem? 
>
>I don't think that would be necessary.  Let volunteers choose which bits
>of the source tree they want to do (i.e. name a subdirectory and do every
>function whose documentation is below that directory) by sending email
>directly to you (or some other entity). It might be worth keeping a
>quickly-updatable web page somewhere with a list of already-claimed
>directories, so that people can know accurately which ones are still free
>(I could host this if you like); the updates would have to take immediate 
>effect for it to be of any use, of course (mine would; I'm NFS-linked to
>the web server).  Perhaps DJ would rather put it on delorie.com.
Okay, that sounds like a good way to coordinate. Perhaps, though, it would
make more sense for the web page maintainer to be the one who gets informed
when somebody claims a piece.

Eli wrote:
>Here's another suggestion:
>
>  @subheading Portability
>
>  @multitable {Supported}     {ANSI}   {POSIX}   {Unix}   {MS-DOS/MS-Windows}
>  @item	      Supported? @tab   no @tab yes @tab (1) @tab (2)
>  @end multitable
>
>  (1) SysV flavor doesn't frobnicate the foobar.  BSD does.  Many Unix
>      systems don't have the prototype declared anywhere (so it's best
>      to have an explicit prototype in the program).
>
>  (2) Known to be buggy in Borland.  DOS compilers declare prototype
>      in @code{<io.h>}.
>
I think Eli's idea of a table with footnotes makes a lot of sense. A major
advantage is that it will keep all the docs consistent. The Texinfo is a bit
more complicated, yes, but I found that reading the Info node "Texinfo"
"Lists and Tables" "Multi-Column Tables" explained it in about 60 seconds.
One could just copy, paste and edit another example, too.
Slight variation on Eli's suggestion: I think it would be better to sum up
the table entries with "yes" or "no" in most cases, so people don't have to
get involved in the details for a simple answer. In Eli's example, the Unix
column might say "yes (1)". Sometimes it would be too complicated for this,
of course. 
It wasn't immediately clear to me that the headings shown (ANSI, POSIX, etc)
just define the column widths and don't actually appear in the output. IMHO,
they should, so each entry can be reasonably self-contained. i.e. add this line:
@item @tab ANSI @tab POSIX @tab Unix @tab MS-DOS/MS-WINDOWS

Also, maybe the header used by a DOS compiler should be in-line with the
column entry, instead of a footnote. I assume it will be a common occurence.

Here's my revision of Eli's suggestion:

  @subheading Portability

  @multitable {Supported}     {ANSI}   {POSIX}   {Unix}   {MS-DOS/MS-Windows}
  @item                  @tab  ANSI @tab POSIX @tab Unix @tab MS-DOS/MS-Windows
  @item	      Supported? @tab   no  @tab yes @tab yes (1) @tab yes <io.h> (2)
  @end multitable

  (1) SysV flavor doesn't frobnicate the foobar.  BSD does.  Many Unix
      systems don't have the prototype declared anywhere (so it's best
      to have an explicit prototype in the program).

  (2) Known to be buggy in Borland.

Btw, a stylistic note: Is it correctly written "Unix" or "UNIX"? I have seen
both ways.

>We could write the portability sections separately for now, and insert
>them into the 2.02 docs at any time, whatever changes have occured to the
>other docs.  This ought to be fairly simple to organise, but whether or
>not it's worth going to the trouble really depends on (a) the magnitude of
>changes since 2.01 and (b) the number of changes which occur as we work.
>I personally think context diffs ought to work fairly well in most cases.
Though I wonder if the context might bite us later. Since this is a new
section and not at all context-dependent, would it be better to use file
fragments which later get stuck on the end of the existing files? Or is it
even likely to matter much?

Eli wrote:
>Somebody (you?) should coordinate the effort.  Everybody else should
>submit their contribution to that person.  When the time comes to
>review the results, if the file is too long, it can be uploaded to
>DJ's and put into the v2/.alphas tree on SimTel.
Okay, I can do that. As I said, though, I'll be away for about a week
shortly. It might be better if people were to hang on to their work until I
get back.

Nate Eldredge
eldredge AT ap DOT net

- Raw text -