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