Recursive upgrade scripts

This is in the example module, but its not very obvious how it works without
a little thought. I hope this helps.

When writing an update function for a module, you must remember that the
user may be upgrading several jumps in one go. The user is upgrading
mymodule from 1.0 to 1.2, missing out 1.1. It is therefore important to
ensure your upgrade function still does the 1.0->1.1 upgrade followed by the
1.1->1.2 upgrade. You _could_ provide a code in the script to jump directly
from 1.1->1.2 in one go, but as you add futher versions to the module you
would need to go back and revisit each section, making it a more
complication procedure.

The upgrade function sits in xarinit.php and takes the name
<module>_upgrade(). It takes a single parameter, which contains the version
of the module the user is upgrading from. The function should look something
like this:

mymodule_upgrade($oldVersion)
{
   // The current version of this module is 1.2
   switch($oldVersion) {
      case 1.0:
         $newVersion = 1.1;
         // Changes to upgrade from 1.0 to 1.1
         ...
         break;
      case 1.1:
         $newVersion = 1.2;
         // Changes to upgrade from 1.1 to 1.2
         ...
         break;
      case 1.2:
         // This is the *current* version.
         return true;
   }
   return mymodule_upgrade($newVersion);
}

There are other issues to bear in mind (such as error handling), but this
example illustrates one way in which recursion can be used to step through
as many historical upgrade steps as necessary to bring a module up to its
current version. Non-recursive methods can be used too.