Documentation updates and syntax tidying

Moderate overhaul of documentation, with some additonal utility functions and
syntax improvements