add more info to README
add Markdown sources for manual
fix verbatim HTML in scaladoc comment