lots of markup fixes and some English nits fixed.

Still needs real review.  Some of the function signatures used in this
module are really bad!  (Two leading optional parameters? Ugh!)