After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 723118 - Mark |[ blocks as CDATA
Mark |[ blocks as CDATA
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal normal
: 1.20
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks: 723119
 
 
Reported: 2014-01-27 19:19 UTC by William Jon McCann
Modified: 2014-01-29 16:36 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Put examples in CDATA (998 bytes, patch)
2014-01-27 19:19 UTC, William Jon McCann
committed Details | Review
Convert comment entities since c preprocessors don't like embedded comments (983 bytes, patch)
2014-01-27 19:19 UTC, William Jon McCann
none Details | Review
Convert comment entities since c preprocessors don't like embedded comments (953 bytes, patch)
2014-01-27 21:08 UTC, William Jon McCann
reviewed Details | Review
Support |[<!-- language="C" --> (983 bytes, patch)
2014-01-27 21:08 UTC, William Jon McCann
none Details | Review
Explicitly handle entities in |[ (2.52 KB, patch)
2014-01-29 00:02 UTC, William Jon McCann
committed Details | Review
Support |[<!-- language="C" --> (983 bytes, patch)
2014-01-29 00:02 UTC, William Jon McCann
committed Details | Review

Description William Jon McCann 2014-01-27 19:19:00 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.
Comment 1 William Jon McCann 2014-01-27 19:19:02 UTC
Created attachment 267335 [details] [review]
Put examples in CDATA
Comment 2 William Jon McCann 2014-01-27 19:19:05 UTC
Created attachment 267336 [details] [review]
Convert comment entities since c preprocessors don't like embedded comments
Comment 3 William Jon McCann 2014-01-27 21:08:52 UTC
Created attachment 267344 [details] [review]
Convert comment entities since c preprocessors don't like embedded comments
Comment 4 William Jon McCann 2014-01-27 21:08:55 UTC
Created attachment 267345 [details] [review]
Support |[<!-- language="C" -->
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-28 13:55:12 UTC
Wouldn't this break people that use markup in the examples?
Comment 6 William Jon McCann 2014-01-28 17:05:04 UTC
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.
Comment 7 William Jon McCann 2014-01-29 00:02:25 UTC
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.
Comment 8 William Jon McCann 2014-01-29 00:02:28 UTC
Created attachment 267459 [details] [review]
Support |[<!-- language="C" -->
Comment 9 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-29 16:04:30 UTC
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 &ast; entities back to '*'.
Comment 10 William Jon McCann 2014-01-29 16:31:36 UTC
Attachment 267335 [details] pushed as c4d09c7 - Put examples in CDATA
Attachment 267459 [details] pushed as 26bf8d0 - Support |[<!-- language="C" -->