[gtk-doc] Explicitly handle entities in |[

[William Jon McCann <mccann src gnome org>]

commit ba968ea8232c79f24ed27dd9eb7d3701b145b473
Author: William Jon McCann <william jon mccann gmail com>
Date:   Wed Jan 29 11:18:26 2014 -0500

    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.

 gtkdoc-mkdb.in |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index a08234e..8367847 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -2850,6 +2850,38 @@ sub ExpandAbbreviationsCallback2 {
     # FIXME: why is this different from &ExpandAbbreviationsCallback(),
     #        why not just call it
     $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg;
+  } elsif ($tag eq "<![CDATA[") {
+    my $warn = "";
+    my @entities = ( [ "&lt;", "<" ],
+                     [ "&gt;", ">" ],
+                     [ "&ast;", "*" ],
+                     [ "&num;", "#" ],
+                     [ "&percnt;", "%"],
+                     [ "&colon;", ":" ],
+                     [ "&quot;", "\"" ],
+                     [ "&apos;", "'" ],
+                     [ "&nbsp;", " " ],
+                     [ "&amp;", "&" ] ); # Do this last, or the others get messed up.
+    my $i;
+
+    # Expand entities in <programlisting> even inside CDATA since
+    # we changed the definition of |[ to add CDATA
+    for ($i = 0; $i <= $#entities; $i++) {
+      if ($text =~ s/$entities[$i][0]/$entities[$i][1]/g) {
+        # don't warn about &ast; since it is expected to be present
+        # for C-style comments
+        if ($entities[$i][0] ne "&ast;") {
+          $warn .= "$entities[$i][0] ";
+        }
+      }
+    }
+
+    if ($warn ne "") {
+      chomp $warn;
+      &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+                   "Deprecated entities found in documentation for $symbol: $warn");
+    }
+
   }
 
   return $text;