This sort of problem pervades the open source community. Some years back (a decade or more) when we were setting up an ISP and investigating the documentation on various parts of LINUX in order, just as an example, to set up terminal servers, we looked into varous versions of getty. There are, of course several different types, and we wanted to use the one that best suited our needs. We found several cases where comments were left in place in source code to which they didn't apply at all any more. The comments were from v0.91, for example, yet the code was at v4.2. Key words were omitted, such as "not." Need I say more about that? Shouldn't documentation be released together with the code to which it refers? Wouldn't it be better to hold off on releasing code until the doc's are correct and complete?

This is not directed at SDCC alone, but since nobody really likes thoroughly evaluating the documents, being grateful that someone else has written them, it's no surprise that it's seldom that documentation is in synchronization with the software, or, even, with the realities in the websites and code sets themselves.

I'm still not straight on whether CYGWIN is needed in order to run SDCC, for example. The doc's are scattered about. Even the doc's that tell you where the doc's are located are scattered about, and it's there that I found my most recent self-contradiction. I was looking for doc's on the assembler syntax, and, in one place, found it was supposed to be a part of a source file set that had been tar.gz'd. I downloaded and, after some pain, decompressed that, it being purportedly intended for use with Windows, which it wasn't, and later learned that I'd had the doc's I wanted all along, as part of the SDCC package, so all that thrashing about for a couple of weeks of spare time was for nothing.

One problem, certainly, with open-source documentation, is that nobody verifies it. Does it really reflect the realities in the currently released code? Does it really state how one is expected to use it? Does it really contain the latest modifications and proper descriptions of those mod's to the resulting work product? Does it have correct default pathnames, for example? Surely you see what I mean.

I've been trying for over a decade to learn about this stuff, but, because of the diffuse nature of the doc's, I've stuck with ASM and haven't yet released one line of my own 'C'-compiled code from SDCC to any of my clients.

RE