Date: Thu, 26 Feb 1998 04:44:47 +0000 (GMT)
From: George Foot <george DOT foot AT merton DOT oxford DOT ac DOT uk>
To: Nate Eldredge <eldredge AT ap DOT net>
cc: djgpp-workers AT delorie DOT com
Subject: Re: Suggestion: Portability section for libc docs
In-Reply-To: <199802260149.RAA14218@adit.ap.net>
Message-ID: <Pine.OSF.3.95.980226040722.30284D-100000@sable.ox.ac.uk>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk

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.


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


> Yeah, that should be fine, because we can even do:
> 
> @port-note dos This note about portability to Borland is very very long and
> @port-note dos doesn't fit on a single line.

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.

giving something like:

@item
@itemize
@item
Borland's portability note is very long and does not fit
on a single line.
@item
Microsoft's is much shorter though.
@end itemize

which may look like this in Info:

  (1)  Borland's portability note is very long and does not fit on a
       single line.

       Microsoft's is much shorter though.

i.e. an itemized list within a numbered list.  This is trivial to
implement.  @port-note-cont just concatenates the given string to the end
of the last @port-note, or using the Line struct it can just add another
line.  The rest would be done in write_portability.


> BTW: I assume it is possible to include other Texinfo commands in the
> port-notes? Stuff like:
> 
> @port-note dos Use @code{foobar} instead of this function on MSC.
> 
> needs to be possible.

Of course.  It should always be possible, since the write_portability
method doesn't interpret the notes in any way.


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

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