Everything needs examples

[rowlesmr]

We need examples. Short ones for each data item, and longer for each category.

This can only really be done after all the additions are done.

[rowlesmr]

and also should deprecate things properly: see _definition_replaced.by