On Fri, Feb 07, 2003 at 02:00:01AM +0100, Martin Nilsson (Åskblod) @ Pike (-) developers forum scribbled:
Compatibility issues should be taken care of by #pike.
How? Will future Pike versions implement new APIs for #pike 7.4 or others? If somebody uses a new API then no #pike will help them with older pikes out there.
I would be nice and swell if a complete paper trail of how all functions and classes changed throughout the ages, but I have some sceptisism how
Note, that I only meant one thing - when a given API appeared in Pike. That's pretty much 90% of the problematic cases, I'd say.
making it harder to write documentation would improve things. If there
http://www.php.net/manual/en/function.umask.php
do you know why, among other reasons, php is so popular? Because their documentation makes it easy for people to get acquainted with the language _and_ to know which APIs they can use to be backwards compatible. In the current state of things, when people using Pike have to run the same code under 0.6, 7.0, 7.2 and 7.4 (7.5 not counted yet), such information:
umask [0.6] (or whenever it appeared)
would be an enormous help for some.
were hords of eager technical writers begging for CVS-access or at least someone who occasionally lended a hand it would be one thing, but as it is today I think our very limited resources are better spent elsewhere.
It's a magic circle. You won't get more users by not writing documentation and if you don't get more users, nobody would be willing to improve the documentation. It's enough (IMHO) to add a committer's rule to the Pike CVS policy to tag new APIs with the current Pike version number - either in the autodoc or in some external file listing all the public APIs. I imagine it might be possible to write an API listing generator by writing a script that loads all the modules that are found in the standard Pike and does indices() on them writing all the methods to the listing file. Done once manually, it can be automated later on.
However, if you whop together something neat that takes the generated XML-files for autodoc from several Pike versions and presentes the changes between the versions we would all think of it as a good and noble deed.
Wouldn't the method I presented above be better? Is there any way to get the list of all the modules Pike can find? If so, then writing such a generator script wouldn't that hard, I guess.
marek