docs: re-organise and edit README.md to make way for pending docs.
docs: re-organise and edit README.md to make way for pending docs.

* README.md (YAML): Split out from the Specifications section.
Don't list the quirks at the end, explain them in the main text
of this section.
Renumber following sections accordingly.
(Contexts): Introduce an example right away.
(Pending Examples): Pending.
(Custom Formatters): Describe API changes necessary to support
display of pending expectations and examples.

Signed-off-by: Gary V. Vaughan <f9023000f29773649f3850298becb9544b5fd6a9@gnu.org>

gvvaughan/specl