Put examples in CDATA

https://bugzilla.gnome.org/show_bug.cgi?id=723118
Explicitly handle entities in |[

Now that we mark |[ blocks as CDATA that means legacy
usage that used entities to work around markup for
examples will be rendered incorrectly. So, we explicitly
convert them to text and print a deprecation warning.
Support |[<!-- language="C" -->

https://bugzilla.gnome.org/show_bug.cgi?id=723118