Date: Wed, 25 Feb 1998 02:51:02 +0000 (GMT) From: George Foot Reply-To: George Foot To: DJ Delorie cc: djgpp-workers AT delorie DOT com Subject: Re: Suggestion: Portability section for libc docs In-Reply-To: <199802250119.UAA21994@delorie.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Precedence: bulk On Tue, 24 Feb 1998, DJ Delorie wrote: > Long comments should be possible, but not necessarily convenient. > > The need for long comments in the portability section should be > limited (that was a request, not an observation). The only case where > a portability issue should be discussed at length is when DJGPP > deviates from the expected (or defined) functionality. In that case, > the note should go in the regular documentation, not the portability > section. I agree here -- these cases are already mentioned in the docs in some places. > Notes in the portability section should be limited in > length, because I expect we'll be talking about other compilers here, > which is not the goal of the djgpp documentation. Short notes, like > "bc3 - needs " or "msc - only two parameters" are enough; > people who really need more information (about porting *to* those > compilers) should have those manuals handy. People porting to djgpp > from those compilers should find the info they need in the main body > of the documentation. This is true. At the lowest level all that is required is the yes/no/partially information -- if `yes' then it will work, if `no' then it won't, and if `partially' then it will need adapting. In the case of `no' you have to look for a new function; in the case of `partially' you either find a more portable function or read the docs for the other systems. If your goal is to make code portable across many systems, the latter isn't really practical. > I guess this boils down to "what's the portability section for?" > > Here's my opinion: it's for people who want to write portable code. > Those people need to know not only how djgpp does it (the regular > docs) but also enough information to decide if they want to avoid a > particular function because of portability reasons. This section > should have enough information to make that decision, and no more. Fair enough. I think though that if the `more' is very small then it could be added (e.g. headers used on other DOS compilers). > > Perhaps I'm confused, but from DJ's example it looked as though it would be > > possible for the "keywords" to be non-magical. That is, any word could be > > used as a header instead of "ANSI" or "Borland", etc. I'd like to suggest we > > do that, so we don't have to hack `mkdoc' again each time we want to add > > something. > > > > So the keywords would only be "key" in the sense that we'd standardized on > > them for consistency, not that there's something special about them. > > Actually, I *was* thinking of hardcoding them into mkdoc, but I > suppose mkdoc could read a separate config file that gives the > expected tokens (mkdoc can report on others it finds) with full names > and the order they are to be listed in. OK. Last night I modified mkdoc to support everything discussed apart from the catenation of lines using \. I did this based upon the v2.01 mkdoc; that's all I had on my machine, which isn't connected to the internet. I'll check that it applies to v2.02 also shortly and post it. IMHO we shouldn't have arbitrary keys defined by the .txh files -- that will just result in inconsistency and confusion. Currently my modified mkdoc has a couple of arrays at the start like so: : #define NUM_PORT_TARGETS 2 : ... : : /* Tokens for use in .txh files */ : char *port_target[NUM_PORT_TARGETS] = { "ansi", "posix" }; : /* Strings to output in .txi files */ : char *port_target_string[NUM_PORT_TARGETS] = { "ANSI", "POSIX" }; I referred to the keys as `tokens' here. The first array gives the valid tokens, and the second gives the `nice' output for the .txi files. For example, at present: @portability ansi ~posix would output: ANSI, partially POSIX I know this isn't the table we considered before, and it doesn't quite make sense; my texinfo wasn't good enough to generate that table from memory and my version of texinfo doesn't support multitable (and hence doesn't document it) so I just put in the above quickly. Modifying the output format is very simple -- there are some new methods in the Node struct, one of which does all the .txi output. As I said, I don't think adding new tokens should be too trivial -- we don't want people doing it willy-nilly. If a new token is added, all functions that don't mention that token are documented to be unportable to that target. This could easily be changed, of course, if people don't like it. To add new tokens, though, you just need to increase the #define, add new strings to the arrays, and recompile. To me this doesn't seem to be a problem. At present my mkdoc issues warning messages if it discovers an unrecognised portability token or an empty port-note. I wasn't sure whether or not it should do (mkdoc doesn't give any other error messages) but it's easier to take them out than it is to add them. The catenation with `\' won't work very well with what I've done at the moment because my code is only passed one line of the file at a time. The obvious way to fix this would be to make the `\' catenation work everywhere in .txh files, by modifying mkdoc's file reading section (in scan_directory IIRC). Any objections to this? I'd like to suggest an alternative to this though. The real need for longish notes is where a function differs across a category (e.g. DOS or Unix) in different ways for different systems within that category. We could make this work by giving several notes in the same category, and putting them all under the same note number in the output, i.e.: @port-note dos Borland doesn't have this function. @port-note dos MS prototypes this in . @portability ~dos results in something like: Portable to DOS (1) (1) Borland doesn't have this function. MS prototypes this in . To me this seems sensible, but the catenation might be worth adding as well, in case it is needed. -- george DOT foot AT merton DOT oxford DOT ac DOT uk ko tavla fo la lojban