add some detail in rst and markdown output
add pandoc note