The 'html' target in docs/Makefile generated a few warnings/errors because
of errors in RST, orphan refs, etc. While at it, I re-aligned code blocks
and lists, fixed hyperlinks, corrected grammatical mistakes and updated some
content here and there.