Mail Archives: djgpp-workers/1998/08/24/13:40:08
George Foot wrote:
[snip description of format]
> 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.
I think the current scheme looks good, personally. Though you didn't
say what the Texinfo looks like-- could you post an example of that?
That's fairly immaterial, however.
> 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.
I think we should have categories which cover general types of systems,
and describe specific ones in the notes. So `sprintf' might be done
like so:
@port-note Unix
Some versions of SunOS return a @code{char *} instead.
@portability ansi posix dos ~unix
And similarly, `stat':
@port-note DOS
Borland and Microsoft compilers do not fill in the @code{st_ino} field.
@portability !ansi posix ~dos unix
I also expect that specifics wouldn't need to be mentioned often.
So `dos' and `unix' would be good categories. I don't know enough about
Windows to say whether it deserves its own category. Anyone?
[snip]
> 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.
I agree.
> 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.
This brings me to another question. Presumably I will be coordinating
this. I'm not sure what is the best way to reconcile all the changes.
The usual way is `diff', but there will be several people simultaneously
making changes to the same parts of files, and I don't know how well
`diff' will work in such a case. Does anyone have any suggestions?
--
Nate Eldredge
nate AT cartsys DOT com
- Raw text -