Mail Archives: djgpp-workers/1998/02/25/20:53:32
At 02:51 2/25/1998 +0000, George Foot wrote:
>On Tue, 24 Feb 1998, DJ Delorie wrote:
>
>> I guess this boils down to "what's the portability section for?"
>>
>> Here's my opinion: it's for people who want to write portable code.
>> Those people need to know not only how djgpp does it (the regular
>> docs) but also enough information to decide if they want to avoid a
>> particular function because of portability reasons. This section
>> should have enough information to make that decision, and no more.
>
>Fair enough. I think though that if the `more' is very small then it
>could be added (e.g. headers used on other DOS compilers).
Sounds good to me too. I agree with the point about the headers and such,
though.
>
>IMHO we shouldn't have arbitrary keys defined by the .txh files -- that
>will just result in inconsistency and confusion. Currently my modified
>mkdoc has a couple of arrays at the start like so:
Okay, I see your point. I also didn't think of the possibility that we
might want to change the output text in the future, and your solution allows
that to happen without changing every txh file. My previous comment was
confused. DJ's idea about the config file is unnecessary too, since anybody
changing it is probably recompiling everything anyway.
>
>: #define NUM_PORT_TARGETS 2
>:
>...
>:
>: /* Tokens for use in .txh files */
>: char *port_target[NUM_PORT_TARGETS] = { "ansi", "posix" };
>: /* Strings to output in .txi files */
>: char *port_target_string[NUM_PORT_TARGETS] = { "ANSI", "POSIX" };
The only other ones I can think of that we might need are "dos", "unix", and
perhaps "windows".
>I know this isn't the table we considered before, and it doesn't quite
>make sense; my texinfo wasn't good enough to generate that table from
>memory and my version of texinfo doesn't support multitable (and hence
>doesn't document it) so I just put in the above quickly. Modifying the
>output format is very simple -- there are some new methods in the Node
>struct, one of which does all the .txi output.
That's fine, with this scheme it will be simple to add the table layout, and
work can start in the meantime.
>As I said, I don't think adding new tokens should be too trivial -- we
>don't want people doing it willy-nilly. If a new token is added, all
>functions that don't mention that token are documented to be unportable to
>that target. This could easily be changed, of course, if people don't
>like it.
IMHO, functions that don't mention a target should just not mention it. I
don't think that omitting to mention, say, DOS, should result in the text
"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. Then
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.
>
>To add new tokens, though, you just need to increase the #define, add
>new strings to the arrays, and recompile. To me this doesn't seem to be a
>problem.
I agree.
>
>At present my mkdoc issues warning messages if it discovers an
>unrecognised portability token or an empty port-note. I wasn't sure
>whether or not it should do (mkdoc doesn't give any other error messages)
>but it's easier to take them out than it is to add them.
I can't see why it shouldn't. Presumably by the release there will be
nothing to warn about. Also, it'll be seen only by people rebuilding the
libc anyway, and they should know what it means.
>
>The catenation with `\' won't work very well with what I've done at the
>moment because my code is only passed one line of the file at a time. The
>obvious way to fix this would be to make the `\' catenation work
>everywhere in .txh files, by modifying mkdoc's file reading section (in
>scan_directory IIRC). Any objections to this?
No objections per se, but see below.
>
>I'd like to suggest an alternative to this though. The real need for
>longish notes is where a function differs across a category (e.g. DOS or
>Unix) in different ways for different systems within that category. We
>could make this work by giving several notes in the same category, and
>putting them all under the same note number in the output, i.e.:
>
>@port-note dos Borland doesn't have this function.
>@port-note dos MS prototypes this in <foo.h>.
>@portability ~dos
>
>results in something like:
>
>Portable to DOS (1)
>
>(1) Borland doesn't have this function.
> MS prototypes this in <foo.h>.
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.
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.
>
>To me this seems sensible, but the catenation might be worth adding as
>well, in case it is needed.
Unless someone *wants* to add it now, we might as well wait until we decide
we need it.
Btw, thanks, George, for doing the patch.
So can anyone think of anything else that needs to happen before work can start?
Nate Eldredge
eldredge AT ap DOT net
- Raw text -