Mostly replace gtk-doc example syntax with markdown,
and reword first sentences.