more links throughout; fix wording and improve docs as per H.S. Teoh advice