P H I L O S O P H Y 
__________________________________________________________________________
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

   I got a lot of feedback like: "Hey, this function is working fine, so
why does PatchWork bark about it?" Okay, let me tell you the philosophy
behind PatchWork, and software documentation in general.

   In the early days, when the first home computers like the ZX Spectrum
and C64 were popular, computers were some kind of static. They were
constructed by some smart people, and then they were never touched again.
Even if there were hardware improvements, the kernel ROM did not change,
to ensure compatibility to the existing software.

   This was because everyone could buy a book with the commented ROM
listing, and then they knew where to find what function, and exact details
of the kernel functionality. And since only one software could run on
these systems simultaneously, you didn't need to care about sharing
resources and you never had to deal with 3rd party software updates.

   Well, times have changed. The static ROM has been replaced by operating
systems, which are updated frequently (at least they should be). These
systems are able to run a number of programs simultaneously, but since
they run on the same hardware, they have to share their resources.

   You have to follow exact rules if you want to write software that can
interact with several versions of the operating system and other software
installed on the software.

   First, you always have to use the operating system instead of accessing
the hardware resources yourself. A good example for this is the DraCo,
which is able to run all conformous software without modifications, just
because they do not access the Amiga chipset directly.

   The other, even more crucial thing is documentation. You don't know how
the operating system or the piece of software works exactly. You aren't
ought to know it, and you won't even be able to know since software is
growing more and more complex. So there is only one interface between your
software and the operating system. This is the documentation that explains
how your operating system works.

   If you are a tool programmer, you rely that the OS call works exactly
as documented. You want to have a certain result if you pass in the right
mixture of parameters.

   If you are a driver or patch programmer, you rely that OS functions
were called in a definite way. You cannot catch all variations and
eventualities, since this would unnecessarily slow down your function.

   I want to mention a good example of what happens if people ignore the
documentation. When Amiga started to get popular, it was delivered with
the AmigaOS 1.2, and later with AmigaOS 1.3. Some people wrote programs
like they have been used to write it on their C64: they knew the address
of some functions in the ROM, and they knew for example that the
graphics.library was always the 3rd library after exec.library (or was
it the 4th, I don't know exactly). So, to save some microseconds, they
ignored the documentation and used their hacks. And they worked fine!

   Until the day when Commodore released the AmigaOS 2.0.

   This was really a black day for the Amiga, because a LOT of games and
hacker tools crashed on the new AmigaOS. Commodore was not to blame,
they did the right thing. Instead of trying to be compatible to as much
existing software as possible (which was the philosophy of Microsoft
these days), they were only downward compatible to their documented
features. So all conformous software still worked on AmigaOS 2.0, while
all the hacks crashed awfully.

   Unfortunately, Commodore WAS blamed for the crashing applications! In
all shops, the new Amiga models were considered as unstable, not compatible
and just awful. I heard a lot of vendors who told their customers this
scrap! They suggested to buy the AmigaOS 1.3 and a switchboard as well,
but the mounting would void the warranty. Most customers decided to better
buy a PC with Windows 3.1, which was said to be more stable.

   This rumour of AmigaOS being incompatible and unstable, is told until
today. And all this just because some lame programmers ignored the rules
and wrote some bad hacks.

   As you see, the documentation is the most important part if you want to
write rock stable and reliable software. And this is why you should use
PatchWork! Certainly, PatchWork is no guarantee that your software will
still run on future AmigaOS releases, but it comes very close to that.

   PatchWork knows about the AutoDocs, the MUSTs and MUST-NOTs. And it is
quite pedantic. It will surely annoy you some time with hits that seem to
be harmless at the first sight. But if you fix these hits, you can be sure
that your program might also work with clean system patches, OS updates or
other software.

   Anyhow, if you don't get any PatchWork hits, it is no sign for your
program being 100% compatible. It also depends on some other factors. The
best rule of thumb is not to play the smart Alec and regard undocumented
features as given. If you find some behaviour that is not documented,
better try to find a documented way to reach your aim, instead of just
using the undocumented feature and rely on that it will still work in
future versions.