tweak formatting, add usage subsections, clarify and elaborate examples