Documentation typos and fixes

Changes created from @danielsilverstone-ct 's notes.

These are changes to the Doc's

• several around how sphinx deals with -- for "paragraph" text
• several effect vs affect.
• some Debian best practices.
• the odd typo.