Mail Archives: djgpp-workers/1998/08/24/20:06:29
On 24 Aug 98 at 10:33, Nate Eldredge wrote:
> 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.
Here are the results of the examples you gave:
.txh:
> @port-note Unix
> Some versions of SunOS return a @code{char *} instead.
>
> @portability ansi posix dos ~unix
[...]
> @port-note DOS
> Borland and Microsoft compilers do not fill in the @code{st_ino}
> field.
>
> @portability !ansi posix ~dos unix
Texinfo:
| ANSI, POSIX, DOS, partially Unix (see note 1)
|
| @noindent
| Notes:
|
| @enumerate
| @item
| Some versions of SunOS return a @code{char *} instead.
|
| @end enumerate
[...]
| not ANSI, POSIX, partially DOS (see note 1), Unix
|
| @noindent
| Notes:
|
| @enumerate
| @item
| Borland and Microsoft compilers do not fill in the @code{st_ino}
| field.
|
| @end enumerate
Info:
: ANSI, POSIX, DOS, partially Unix (see note 1)
:
: Notes:
:
: 1. Some versions of SunOS return a `char *' instead.
[...]
: not ANSI, POSIX, partially DOS (see note 1), Unix
:
: Notes:
:
: 1. Borland and Microsoft compilers do not fill in the `st_ino' field.
The actual documentation will be a little different to the above
though; I generated this Info file with no options to `makeinfo'.
The Texinfo output is very easy to change in `mkdoc.cc'. I don't
think the current wording is very good, but it doesn't matter yet.
> 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?
The problem is of course that nobody knows about every compiler; if
possible it would be best to have each function's documentation
updated by one person, but that's clearly not possible because for
many functions no one person will know enough about enough compilers
to be able to add all the information.
In total there are just over 550 .txh files, containing just over
700 nodes. It doesn't take long to update them, when you know what
to put in.
I think there are two ways we could do this. We could go through
mechanically, adding the ANSI/POSIX information, and then invite
people with access to (and knowledge about) other platforms to add
more specific information later on. Or we could attempt to gather
all the information on other platforms first, and add that at the
same time as the ANSI/POSIX information.
I think the first way is probably simpler, and produces results more
quickly, but has the problem of requiring changes to some functions
by several different people.
To get the information about other platforms, we could make a text
file containing the alphabetic list of functions. Then people can
check whether or not their compilers have the functions, removing
them from a copy of the list if their compiler does not. Then we'll
have a simple list of functions which that compiler defines; we can
then compare the lists for Borland and Microsoft to determine what
functions are `dos' portable, and the lists for various Unices to
determine which functions are `unix' portable. When a function is
only supported by some of the compilers in a category we can add
notes to mention this.
Under the second system then we could automatically generate the
@portability lines for most of the functions (those which are
supported either universally or not at all on each platform), and
add these entries manually. We'd then have a list of oddball
functions which require more care.
This system wouldn't take account of differences in behaviour of
functions though. I think maybe that information would be better if
added later on. Systematically checking whether djgpp's functions
behave in the same way as their counterparts on other compilers would
be extremely tedious -- it's probably better to add the extra notes
when the inaccuracies are noticed.
--
george DOT foot AT merton DOT oxford DOT ac DOT uk
- Raw text -