initial changes & documentation, not yet tested