---
== 0)
create and install initial version of a module

* create your module
* install inital version as 'module.rb.0.0.0'
* soft link module.rb to this version

<b>note that i've left it to intall.rb writers to implement this! ;-)</b>

at this point /usr/lib/ruby/ might have
  module.rb.0.0.0
and
  module.rb -> module.rb.0.0.0

---
== 1)
use *this* initial version in your software by asking to link against a
library which supports the 0th interface

  require 'library'
  Library::link 'module.rb', 0

or simply

  require 'library'
  Library::link 'module.rb.0.0.0'

where 'module.rb.0.0.0' is the name of the latest (best) module.rb at the time
you wrote your program.  by doing this you are making sure that your program
will, in the future, only load a 'module.rb' which supports the 0th interface.
it does *not* mean it will only load version 0.0.0.

---
== 2)
suppose some bugs are fixed in 'module.rb', resulting in version
'module.rb.0.1.0', being installed.  

at this point /usr/lib/ruby/ might have
  module.rb.0.0.0
  module.rb.0.1.0
and
  module.rb -> module.rb.0.1.0

your software, which has asked for *a* library supporting this 0th interface
<i>picks up the new version</i> still using (no change) :

  require 'library'
  Library::link 'module.rb', 0


---
== 3)
now suppose a completely new, non-backward compatible 'module.rb.1.0.0' comes
out.

at this point /usr/lib/ruby/ might have
  module.rb.0.0.0
  module.rb.0.1.0
  module.rb.1.0.0
and
  module.rb -> module.rb.1.0.0

your code, which has :

  require 'library'
  Library::link 'module.rb', 0

in it *continues* to pick up a library supporting the 0th interface!

newly written code having

  require 'library'
  Library::link 'module.rb', 1

will pick up 'module.rb.1.0.0' since *it* supports the 1st (only) interface.


---
== 4)
when the next version comes out it is versioned 'module.rb.1.0.1 meaning it is
now is backwards compatible with versions supporting the 0th interface - this
new library ALSO supports the 1st interface.  

at this point /usr/lib/ruby/ might have
  module.rb.0.0.0
  module.rb.0.1.0
  module.rb.1.0.0
  module.rb.1.0.1
and
  module.rb -> module.rb.1.0.1

your original code having :

  require 'library'
  Library::link 'module.rb', 0

will now pick up the new improved library since 1.0.1 is now <b>backward
compatible</b> with the 0th interface.  in otherwords it supports *both* the
1st *and* 0th interfaces (see README for explanation)