Date: Thu, 27 Aug 1998 14:03:28 +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: Nate Eldredge <nate AT cartsys DOT com>, djgpp-workers AT delorie DOT com
Subject: Re: Patch to mkdoc and re: portability information
In-Reply-To: <E0zB6bm-0005zZ-00@sable.ox.ac.uk>
Message-ID: <Pine.SUN.3.91.980827140302.6326E-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk


On Tue, 25 Aug 1998, George Foot wrote:

> Texinfo:
> | ANSI, POSIX, DOS, partially Unix (see note 1)
> | 
> | @noindent
> | Notes:
> | 
> | @enumerate
> | @item
> | Some versions of SunOS return a @code{char *} instead.
> | 
> | @end enumerate

I suggest to use @multitable instead.  Here's how the above might look
using that feature:

  Texinfo:
  @multitable {ANSI} {POSIX} {DOS} {partial (see note 1)}
  @item  ANSI @tab POSIX @tab DOS @tab UNIX
  @item  yes  @tab yes   @tab yes @tab partial (see note 1)
  @end multitable

Note that the text after @multitable is meant to tell makeinfo and TeX
how much space to reserve for each field, so it should include the
longest entry in that column.  The whole story about @multitable is in
the Texinfo docs.

Here's how it should look in Info:

  ANSI  POSIX  DOS  UNIX
  yes   yes    yes  partial (see note 1)

If we want to be really fancy, we could enclose the whole @multitable
in a @cartouche (which draws a frame with rounded corners around the
table--in the printed output alone, of course).

> The problem is of course that nobody knows about every compiler; if
> possible it would be best to have each function's documentation
> updated by one person, but that's clearly not possible because for
> many functions no one person will know enough about enough compilers
> to be able to add all the information.

Come on, let's do it the DJGPP way: somebdoy should do the first cut
as best as they can, post the diffs and gather comments from whoever
cares to comment.  If we wait for the perfect solution, we will wait
forever.

> To get the information about other platforms, we could make a text 
> file containing the alphabetic list of functions.  Then people can 
> check whether or not their compilers have the functions, removing 
> them from a copy of the list if their compiler does not.  Then we'll 
> have a simple list of functions which that compiler defines; we can 
> then compare the lists for Borland and Microsoft to determine what 
> functions are `dos' portable, and the lists for various Unices to 
> determine which functions are `unix' portable.

I'm not sure this isn't too much.  But anyway, this could be automated
by using output of `nm' or the local librarian and sorting the
results.  Then you could easily compare the sorted lists and even
generate some of the @port-note's automatically.  On Unix, either
`nm' or the man pages are a good place to start.

> Systematically checking whether djgpp's functions 
> behave in the same way as their counterparts on other compilers would 
> be extremely tedious

I don't think anybody would expect to have this information.  It's too
much.  Let's add notes as the experience and user feedback dictate.