Date: Thu, 26 Feb 1998 21:28:29 -0800 (PST)
Message-Id: <199802270528.VAA05446@adit.ap.net>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
To: George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
From: Nate Eldredge <eldredge AT ap DOT net>
Subject: Re: Suggestion: Portability section for libc docs
Cc: djgpp-workers AT delorie DOT com
Precedence: bulk

At 04:44  2/26/1998 +0000, George Foot wrote:
>On Wed, 25 Feb 1998, Nate Eldredge wrote:
>
>> The only other ones I can think of that we might need are "dos", "unix", and
>> perhaps "windows".
>
>Yes.  I just put in ANSI and POSIX because they're the simplest to do on
>the first pass.

Yeah, I think my comment was sort of a random brain dump.
>
>
>> IMHO, functions that don't mention a target should just not mention it.
>[snip]
>
>That conflicts with the proposed tabular format -- all the columns would
>(presumably) exist in each function's documentation, so those not
>explicitly mentioned would implicitly be documented as "no"s.  I may have
>misunderstood here though -- we can of course make the table only contain
>columns for mentioned targets.
>
>> "Not portable to DOS". I'd like to propose that we say either "dos"
>> (portable to DOS), "~dos" (sort of portable to DOS), or something like
>> "!dos" (not portable to DOS), and not mentioning it results in nothing.
>
>The "!dos" sounds sensible, yes -- this can be added easily.
>
>> people would just have to draw their own conclusions. Alternatively, to
>> force us to get everything, it could issue a warning "Token not mentioned"
>> and/or put "Unknown" in the text.
>
>Well yes, but we should make sure the docs don't get distributed with
>"Unknown"s present.
>
Right, that's the idea. Insert something that will be obvious when it's checked.

But I'm still not sure what action would be best if a target is not
mentioned. Is it reasonable to assume (like I suggest below) that we want to
mention every target everywhere, for consistency? That would work
particularly well with the table format. Or might there be times when we
*want* some left out? (See also my message about the "unique" pseudo-target,
which would be such a case, but could be done specially.)

>That's relying on the way the output is formatted.  If @port-note simply
>writes the following:
>
>(1) This note about portability...
>doesn't fit on a single line.
>
>then the output will be wrapped sensibly by Info.  This means that my
>previous example wouldn't have the line break before the `MS' part, which
>will look a bit ugly.  How about:
>
>@port-note dos Borland's portability note is very long and does not fit
>@port-note-cont on a single line.
>@port-note dos Microsoft's is much shorter though.

That should work. `@port-note-cont' is a bit cumbersome to type, but I
suppose that's a feature, not a bug.  :) Encourages us to be concise.

>> So can anyone think of anything else that needs to happen before work
>> can start? 
>
>Decide whether or not to use !, whether to implement @port-note-cont as
>above, and how many targets to include in all docs consistently.  I think
>ANSI and POSIX should always be mentioned, which is all we need to agree
>on for now.

I think the ! scheme is preferable to implicit "no"s. See above re the others.

Nate Eldredge
eldredge AT ap DOT net