remove "in pixels" where it may not be true
switch to markdown for docstring syntax
a handful of fixes, clarifications and cleanup