[PATCH] <![CDATA[ and ]]> in the description in the source.

[Shiino Yuki <shiino yuki be to>]

Hi, everyone

    My name is SHIINO Yuki. I'm using gtk-doc to document my small
project.

    I made a patch which enable gtkdoc-mkdb to parse a pair of
 <![CDATA[ and ]]> in the description in the source code,
like bellow:

/**
 * func_name:
 * @par1: ...
 * @par2: ...
 * Your description is here. And a small example code is following.
 *
<informalexample><programlisting><![CDATA[
#include <stdio.h>

int main(void) {
   printf("hello, world\n");
   return 0;
}
]]></programlisting></informalexample>
 */


    This feature is very useful to write a small example to
show how a function may be used. Sometimes, I would like to
write a sample code in a source file rather than in a XML
document file. It's easier to maintain sample code.

    The attached patch can be applied to CVS current version.
Any comments are welcome.

    Best regards.

-- 
  Shiino Yuki    <shiino yuki be to>

diff -Naur gtk-doc.cvs/gtkdoc-mkdb.in gtk-doc/gtkdoc-mkdb.in
--- gtk-doc.cvs/gtkdoc-mkdb.in	2006-10-14 23:01:13.000000000 +0900
+++ gtk-doc/gtkdoc-mkdb.in	2006-10-29 20:56:21.000000000 +0900
@@ -790,7 +790,7 @@
     my $parameters_output = 0;
 
     if (defined ($SymbolDocs{$symbol})) {
-	my $symbol_docs = &ExpandAbbreviations($SymbolDocs{$symbol});
+	my $symbol_docs = &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
 
 	# Try to insert the parameter table at the author's desired position.
 	# Otherwise we need to tag it onto the end.
@@ -835,7 +835,7 @@
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
+	$desc .= &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
     }
     $desc .= OutputSymbolTraits ($symbol);
     $desc .= "</refsect2>\n";
@@ -957,7 +957,7 @@
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
+	$desc .= &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
     }
 
     # Create a table of fields and descriptions
@@ -998,7 +998,7 @@
 
 	    $desc .= "<varlistentry>\n<term>$text</term>\n";
 	    if (defined $field_descr) {
-		$desc .= "<listitem><simpara>".&ExpandAbbreviations($field_descr)."</simpara></listitem>\n";
+		$desc .= "<listitem><simpara>".&ExpandAbbreviationsExceptCDATA($field_descr)."</simpara></listitem>\n";
 	    } else {
 		$desc .= "<listitem></listitem>\n";
 	    }
@@ -1035,7 +1035,7 @@
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
+	$desc .= &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
     }
 
     # Create a table of fields and descriptions
@@ -1069,7 +1069,7 @@
 	    $condition = &MakeConditionDescription ($member_name);
 	    $desc .= "<varlistentry>\n<term><anchor id=\"$id\" role=\"constant\"${condition}${empty_element_end}<literal>$member_name</literal></term>\n";
 	    if (defined $member_descr) {
-		$desc .= "<listitem><simpara>".&ExpandAbbreviations($member_descr)."</simpara></listitem>\n";
+		$desc .= "<listitem><simpara>".&ExpandAbbreviationsExceptCDATA($member_descr)."</simpara></listitem>\n";
 	    } else {
 		$desc .= "<listitem></listitem>\n";
 	    }
@@ -1107,7 +1107,7 @@
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
+	$desc .= &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
     }
     $desc .= OutputSymbolTraits ($symbol);
     $desc .= "</refsect2>\n";
@@ -1148,7 +1148,7 @@
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
+	$desc .= &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
     }
     $desc .= OutputSymbolTraits ($symbol);
     $desc .= "</refsect2>\n";
@@ -1326,7 +1326,7 @@
     my $parameters_output = 0;
 
     if (defined ($SymbolDocs{$symbol})) {
-	my $symbol_docs = &ExpandAbbreviations($SymbolDocs{$symbol});
+	my $symbol_docs = &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
 
 	# Try to insert the parameter table at the author's desired position.
 	# Otherwise we need to tag it onto the end.
@@ -1367,12 +1367,12 @@
 	    my $param_name = $$params[$j];
 	    my $param = $$params[$j + 1];
 	    if ($param_name eq "Returns") {
-		$returns = &ExpandAbbreviations($param);
+		$returns = &ExpandAbbreviationsExceptCDATA($param);
 	    } else {
 		if ($param_name eq "Varargs") {
 		    $param_name = "...";
 		}
-		$param = &ExpandAbbreviations($param);
+		$param = &ExpandAbbreviationsExceptCDATA($param);
 		$params_desc .= "<varlistentry><term><parameter>$param_name</parameter>&nbsp;:</term>\n<listitem><simpara>$param</simpara></listitem></varlistentry>\n";
 	    }
 	}
@@ -1474,21 +1474,21 @@
 #	$short_desc = "one line description goes here.";
 	$short_desc = "";
     } else {
-	$short_desc = &ExpandAbbreviations($short_desc);
+	$short_desc = &ExpandAbbreviationsExceptCDATA($short_desc);
 #	print "Found short_desc: $short_desc";
     }
     my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
     if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) {
 	$long_desc = "<para>\nA longer description goes here.\n</para>\n";
     } else {
-	$long_desc = &ExpandAbbreviations($long_desc);
+	$long_desc = &ExpandAbbreviationsExceptCDATA($long_desc);
 #	print "Found long_desc: $long_desc";
     }
     my $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
     if (!defined ($see_also) || $see_also =~ m%^\s*(<para>)?\s*(</para>)?\s*$%) {
 	$see_also = "";
     } else {
-	$see_also = &ExpandAbbreviations($see_also);
+	$see_also = &ExpandAbbreviationsExceptCDATA($see_also);
 #	print "Found see_also: $see_also";
     }
     if ($see_also) {
@@ -1626,7 +1626,7 @@
     open (OUTPUT, ">$new_sgml_file")
 	|| die "Can't create $new_sgml_file";
 
-    print OUTPUT &ExpandAbbreviationsExceptCDATA($contents);
+    print OUTPUT &ExpandAbbreviationsExceptCDATAExceptCDATA($contents);
     close (OUTPUT);
     
     return &UpdateFileIfChanged ($old_sgml_file, $new_sgml_file, 0);
@@ -1764,17 +1764,37 @@
 
 sub ConvertSGMLChars {
     my ($text) = @_;
-    if ($SGML_MODE) {
-	$text =~ s/&(?![a-zA-Z#])/&amp;/g;	# Do this first, or the others get messed up.
-	$text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
-	$text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
-    }
-    else {
+
+    if (! $SGML_MODE) {
 	$text =~ s/&/&amp;/g;	# Do this first, or the others get messed up.
 	$text =~ s/</&lt;/g;
 	$text =~ s/>/&gt;/g;
+	return $text;
     }
-    return $text;
+
+    # SGML mode.
+    my ($i, $part, @out);
+    foreach $part (split /<!\[CDATA\[/, $text) {
+	if (defined $i) {
+	    my @p = split /]]>/, $part;
+	    if (scalar @p != 2) {
+		warn "Cannot find CDATA section end";
+		@p = ('', join(']]>', @p));
+	    }
+	    $p[1] =~ s/&(?![a-zA-Z#])/&amp;/g;	# Do this first, or the others get messed up.
+	    $p[1] =~ s/<(?![a-zA-Z\/!])/&lt;/g;
+	    $p[1] =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
+	    push @out, join(']]>', @p);
+	}
+	else {
+	    $part =~ s/&(?![a-zA-Z#])/&amp;/g;	# Do this first, or the others get messed up.
+	    $part =~ s/<(?![a-zA-Z\/!])/&lt;/g;
+	    $part =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
+	    push @out, $part;
+	}
+	$i = 'really inside CDATA';
+    }
+    return join('<![CDATA[', @out);
 }
 
 
@@ -1929,7 +1949,7 @@
 		$desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
 	}
 	if ($Deprecated{$symbol} ne "") {
-	    $note = &ExpandAbbreviations($Deprecated{$symbol});
+	    $note = &ExpandAbbreviationsExceptCDATA($Deprecated{$symbol});
 	    $note =~ s/^\s*([0-9\.]+)\s*:\s*//;
 	    $note =~ s/^\s+//;
 	    $note =~ s/\s+$//;
@@ -2370,7 +2390,7 @@
 
 	    $AllSymbols{$symbol} = 1;
 	    if (defined ($SymbolDocs{$symbol})) {
-	        my $symbol_docs = &ExpandAbbreviations($SymbolDocs{$symbol});
+	        my $symbol_docs = &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
 
 		# Try to insert the parameter table at the author's desired
 		# position. Otherwise we need to tag it onto the end.
@@ -2468,7 +2488,7 @@
 	    my $blurb;
 	    if (defined($SymbolDocs{$symbol}) &&
 		!IsEmptyDoc($SymbolDocs{$symbol})) {
-		$blurb = &ExpandAbbreviations($SymbolDocs{$symbol});
+		$blurb = &ExpandAbbreviationsExceptCDATA($SymbolDocs{$symbol});
 		$AllDocumentedSymbols{$symbol} = 1;
 	    }
 	    else {
@@ -3069,9 +3089,24 @@
 	    $src_doc =~ s%\n+\s*<!--PARAMETERS-->\s*\n+%\n</para>\n<!--PARAMETERS-->\n<para>\n%g;
 
 	    # If there is a blank line, finish the paragraph and start another.
-	    if ($src_doc =~ s%\n{2,}%\n</para>\n<para>\n%g) {
-#		print "Converted blank lines:\n$src_doc\n";
+	    my ($i, $part, @out);
+	    foreach $part (split /<!\[CDATA\[/, $src_doc) {
+		if (defined $i) {
+		    my @p = split /]]>/, $part;
+		    if (scalar @p != 2) {
+			warn "Cannot find CDATA section end";
+			@p = ('', join(']]>', @p));
+		    }
+		    $p[1] =~ s%\n{2,}%\n</para>\n<para>\n%g;
+		    push @out, join(']]>', @p);
+		}
+		else {
+		    $part =~ s%\n{2,}%\n</para>\n<para>\n%g;
+		    push @out, $part;
+		}
+		$i = 'really inside CDATA';
 	    }
+	    $src_doc = join('<![CDATA[', @out);
 
             if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
                 # FIXME: should we check for empty $tmpl_doc ?