add some missing parentheses
use markdown for rst headings

underlines and all, no need to measure length.