1.2 overhaul

Note that this pull reuqest removes outdated information and just updates it to be "1.2" compliant.

Significant new docs will be added subsequently, but this one at least is now uptodate.

/cc @ingenthr