GNOME Bugzilla – Bug 723118
Mark |[ blocks as CDATA
Last modified: 2014-01-29 16:36:04 UTC
While converting GTK+ to use |[ instead of <informalexample><programlisting> it became clear that it would be much nicer to treat these sections as CDATA so the docbook parser doesn't try to interpret any tag like items inside. The one caveat is that in order to have c-style comments in these blocks we need to use an entity so the cpp doesn't see them.
Created attachment 267335 [details] [review] Put examples in CDATA
Created attachment 267336 [details] [review] Convert comment entities since c preprocessors don't like embedded comments
Created attachment 267344 [details] [review] Convert comment entities since c preprocessors don't like embedded comments
Created attachment 267345 [details] [review] Support |[<!-- language="C" -->
Wouldn't this break people that use markup in the examples?
The examples are programlistings and having that interpreted as markup is really a pain. Especially since the markup changes over time. I really think we don't want to allow markup in programlistings. That said we should try not to break existing users. Existing users are likely using entities in order to work around the fact that the programs are parsed. If we replace the entities with the real text equivalents we should cover most of it.
Created attachment 267458 [details] [review] 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.
Created attachment 267459 [details] [review] Support |[<!-- language="C" -->
Review of attachment 267344 [details] [review]: ::: gtkdoc-mkdb.in @@ +2765,3 @@ $text =~ s%\]\|%]]></programlisting></informalexample>%g; + + # Convert comment entities since c preprocessors don't like embedded comments nit: I am a bit confused about the comment? What case does this address? You are convertion * entities back to '*'.
Attachment 267335 [details] pushed as c4d09c7 - Put examples in CDATA Attachment 267459 [details] pushed as 26bf8d0 - Support |[<!-- language="C" -->