Date: Fri, 13 Feb 1998 05:13:15 +0000 (GMT) From: George Foot Reply-To: George Foot To: Nate Eldredge cc: eliz , Ned Ulbricht , djgpp-workers AT delorie DOT com Subject: Re: Suggestion: Portability section for libc docs In-Reply-To: <199802130328.TAA12320@adit.ap.net> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Precedence: bulk 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 (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