Many documentation updates

This cleans up the formatting of some of the description fields
so that the asciidoc version preserves the formatting. There are
several other minor formatting changes.
Most of the previously undocumented fields now have at least some
minimal documentation.
This simplifies the code that ensures utf-8 correctness. This should
work with both python2 and python3.