pre-final version, full documentation

final update to come some time late tonight