Comments: Authenticated sender is From: "George Foot" To: Nate Eldredge Date: Tue, 25 Aug 1998 01:03:45 +0000 MIME-Version: 1.0 Content-type: text/plain; charset=US-ASCII Content-transfer-encoding: 7BIT Subject: Re: Patch to mkdoc and re: portability information Reply-to: george DOT foot AT merton DOT oxford DOT ac DOT uk CC: djgpp-workers AT delorie DOT com Message-Id: Precedence: bulk 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