Mail Archives: djgpp-workers/1998/08/23/17:15:24
Hello
At last I have some time on my hands, so I decided to work on the
portability information again. Here's a patch for
`src/mkdoc/mkdoc.cc', based on the version in the 980628 alpha. It
incorporates changes I made back in March, and a few others made
today. The changes alter the way the information is tracked inside
mkdoc and make it slightly more flexible.
The current structure is based around having the following lines in
the documentation for each function:
@subheading Portability
@portability ansi ~posix !borland
If `ansi', `posix' and `borland' were categories, this would mean
that the function would be portable to ANSI and partially to POSIX,
but not to Borland.
When a function is only partially portable to a target (like the
`posix' target above) you can give a descriptive note explaining why
it's not quite portable to that platform. Put this line:
@port-note posix Feature X is meaningless in a DOS environment
before the `@portability' line; or, write:
@port-note posix
Feature X is meaningless in a DOS environment
This way, you can write longer notes split across several lines
(they'll be reformatted by makeinfo, of course).
You can write notes for as many targets as you like, not just for
ones marked with `~', but I think it's better to avoid unnecessary
notes, especially if the reason for the note is already stated in
the documentation for the function. The patched mkdoc is capable of
including multi-paragraph notes, but this is just a safety net in
case for some function it really is necessary to say a lot.
Here's an example, for the `fflush' function:
@subheading Portability
@port-note Borland
Borland has an extension to @code{fflush}; it lets you fflush an
input stream, purging all characters. DJGPP does not support this.
@portability ansi posix ~borland
I don't actually think that's a good place for a note, but it's just
an example.
Please comment on this. I personally think we have enough to start
adding this information to the documentation, but if you disagree
let's change it. I think it's better to have the processing done by
`mkdoc.cc' itself rather than through Texinfo macros.
If everybody approves of the general system outlined above, we need
to decide what the categories should be. This patched mkdoc.cc has
two catogries -- "ansi" and "posix". Of course it's simple to add
more. It's also simple to change the format of the Texinfo output if
you don't like it.
When we discussed this before, people disagreed about which
categories we should use; should DOS be a category all by itself, or
should each DOS compiler get its own category? What about Windows
compilers? What about Unix compilers -- can Unix be a single
category, or would we need to list a lot of flavours?
Personally I think DOS compilers should be a single category; we can
list individual compilers' differences in notes if it's thought to be
necessary. I don't know about Unix compilers; presumably they all
support ANSI and POSIX but after that do they differ a lot from each
other? If so then we should either give them separate categories or
not list them at all -- or just say that the function is not
universally portable to Unix systems, if only some have it. Again
we could list in notes which do/don't if you like.
Having a very large number of categories will be unwieldy in the
documentation, but they don't all have to be mentioned in every
function. We could have a generic DOS category, and also one
category for each DOS compiler, and only list individual compilers
when they're different from the normal DOS trend. I think Eli said
this was rare, anyway.
So there are many options. I don't think we need to decide this
immediately; assuming that ANSI and POSIX are definite categories we
can go ahead and put that information into the .txh files, adding
other categories later. Even just having the ANSI/POSIX portability
information would be an improvement on what we have now (i.e. no
portability information).
We also need to decide where in the documentation the portability
information should go; I suggest putting it just before the example
in nodes which have an example, or at the end of the node if there
is no example.
Finally we need to go through the .txh files adding the information.
This is a big task, but not very difficult to do at a simple level,
since the header files already show whether a function is defined in
ANSI or POSIX or neither.
I don't think it's possible to be more specific all through the docs
(e.g. mentioning how a function is not quite POSIX) unless you have
experience using that function and already know how it is different.
I think that sort of detail needs to be added afterwards bit by bit.
In extreme cases (like `stat') there's already a lot of information
given about how the function is awkward to implement in DOS.
--
george DOT foot AT merton DOT oxford DOT ac DOT uk
- Raw text -