Updated docs for issue #504
formatting tweaks, fixed some links
Revamped TOC
Merge pull request #509 from jacqui/update-docs-504

Documentation update