Date:	Fri, 13 Feb 1998 05:13:15 +0000 (GMT)
From:	George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
Reply-To:	George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
To:	Nate Eldredge <eldredge AT ap DOT net>
cc:	eliz <eliz AT is DOT elta DOT co DOT il>, Ned Ulbricht <nedu AT ee DOT washington DOT edu>,
	djgpp-workers AT delorie DOT com
Subject:	Re: Suggestion: Portability section for libc docs
In-Reply-To:	<199802130328.TAA12320@adit.ap.net>
Message-ID:	<Pine.OSF.3.95.980213034858.31350A-100000@sable.ox.ac.uk>
MIME-Version:	1.0

On Thu, 12 Feb 1998, Nate Eldredge wrote:

> 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.

Provided the same header is used by all DOS compilers; if not a footnote
would be more appropriate (and probably necessary anyway).

> 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
[snip]

I'm wondering whether the `Supported?' bit is necessary, since the table
only has one (real) row and it should be pretty obvious what `yes' and
`no' mean in each column.  Also I think it's wise to keep tables fairly
narrow when they're being converted into a markup language, since you
don't know exactly what they'll look like (margins, page width, etc) on
the user's screen.  This could be particularly relevant for RHIDE users; I
don't use it myself but I presume its help window is resizable. 

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

I believe both ways are accepted and that the original was Unix. 
Something to do with it not standing for anything; wasn't it a pun (`mult'
vs `un')? 

> >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?

That's true of course; it would be perfectly possible to just make
separate files.  Note that some (many?) of the .txh files contain more
than on function's documentation, though, and I think it would be better
aesthetically for the portability section to come before any examples.
All in all, it'll need a little work to merge in the separate bits and
pieces.

> 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.

If we sort out the macros versatilely fairly soon (not setting their
definitions in stone, just defining what they'll be) then people can start
work.  I'd suggest something if I had any idea how the macros for mkdoc
work; perhaps something like:

@portability
@brief ansi(no) posix(yes) unix(yes,1) dos(yes,io.h,2)
@notes

  (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.

@end portability

As I said, I don't understand the macros and can't find the documentation
for them, so the above is probably horribly incorrect.

-- 
george DOT foot AT merton DOT oxford DOT ac DOT uk

ko tavla fo la lojban

- Raw text -