some markdown updates for better rst (and the rst file generated from pandoc)