[gtk-doc] mkdb: start simple markdown parser

[Stefan Kost <stefkost src gnome org>]

commit 5d0ca8c60b20a907040d1e69f128c687ce9f3b8b
Author: Stefan Kost <ensonic users sf net>
Date:   Tue Mar 29 22:23:04 2011 +0300

    mkdb: start simple markdown parser
    
    Turn ConvertBlankLines into a function that handles MarkDown. In addition to
    paragraph markers we now handle simple subsections.
    
    Fixes: #639145

 gtkdoc-mkdb.in              |   67 +++++++++++++++++++++++++++++++++++--------
 tests/gobject/src/gobject.c |   21 +++++++++----
 2 files changed, 69 insertions(+), 19 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 4c13c7d..faf9fdb 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -4378,9 +4378,8 @@ sub MergeSourceDocumentation {
 	    # Do not add <para> to nothing, it breaks missing docs checks.
 	    my $src_doc_para = "";
             if ($src_doc ne "") {
-                # If there is a blank line, finish the paragraph and start another.
-                $src_doc = &ConvertBlankLines ($src_doc, $symbol);
-                $src_doc_para = "<para>\n$src_doc\n</para>";
+                # Expand markdown (and do paragraphs)
+                $src_doc_para = &ConvertMarkDown ($src_doc, $symbol);
                 ## fixup xml markup
                 # FIXME: this is questionable, as we can't make assumtions on the content really
                 #$src_doc_para =~ s%^<para>\n(<refsect[1-9])%$1%gms;
@@ -4572,19 +4571,32 @@ sub IsEmptyDoc {
 
 
 #############################################################################
-# Function    : ConvertBlankLines
-# Description : Converts blank lines to "</para><para>", but only outside CDATA
-#               and <programlisting> tags.
+# Function    : ConvertMarkDown
+# Description : Converts mark down syntax to the respective docbook, but only
+#               outside CDATA and <programlisting> tags.
+#               http://de.wikipedia.org/wiki/Markdown
+#               Code snippets have been takesn from
+#               http://daringfireball.net/projects/markdown/
+#                 Copyright (c) 2004 John Gruber
 # Arguments   : the doc-string, the symbol name
 #############################################################################
-sub ConvertBlankLines {
-    return &ModifyXMLElements ($_[0], $_[1],
+my $in_refsect2;
+sub ConvertMarkDown {
+    my ($text, $symbol) = @_;
+    $in_refsect2=0;
+    $text = &ModifyXMLElements ($text, $symbol,
 			       "<!\\[CDATA\\[|<programlisting[^>]*>|\\|\\[",
-			       \&ConvertBlankLinesEndTag,
-			       \&ConvertBlankLinesCallback);
+			       \&ConvertMarkDownEndTag,
+			       \&ConvertMarkDownCallback);
+    if ($in_refsect2==1) {
+        $text = "<para>\n$text\n</para></refsect2>"
+    } else {
+        $text = "<para>\n$text\n</para>";
+    }
+    return $text
 }
 
-sub ConvertBlankLinesEndTag {
+sub ConvertMarkDownEndTag {
   if ($_[0] eq "<!\[CDATA\[") {
     return "]]>";
   } elsif ($_[0] eq "|[") {
@@ -4594,12 +4606,43 @@ sub ConvertBlankLinesEndTag {
   }
 }
 
-sub ConvertBlankLinesCallback {
+sub ConvertMarkDownCallback {
   my ($text, $symbol, $tag) = @_;
 
   # If we're not in CDATA or a <programlisting> we convert blank lines so
   # they start a new <para>.
   if ($tag eq "") {
+    # Setext-style headers:
+    #	  Header 1
+    #	  ========
+    #
+    #	  Header 2
+    #	  --------
+    #
+    if ($in_refsect2==1) {
+        $text =~ s%^\n(.+)[ \t]*\n=+[ \t]*\n\n%</para></refsect2><refsect2><title>$1</title><para>\n%gm;
+    } else {
+        if($text =~ s%^\n(.+)[ \t]*\n=+[ \t]*\n\n%</para><refsect2><title>$1</title><para>\n%gm) {
+            $in_refsect2=1;
+        }
+    }
+
+    # atx-style headers:
+    #	# Header 1
+    #	## Header 2
+    #	## Header 2 with closing hashes ##
+    #	...
+    #	###### Header 6
+    #
+    if ($in_refsect2==1) {
+        $text =~ s%^\n\#[ \t]*(.+?)[ \t]*\#\n+%</para></refsect2><refsect2><title>$1</title><para>\n%gm;
+    } else {
+        if($text =~ s%^\n\#[ \t]*(.+?)[ \t]*\#\n+%</para><refsect2><title>$1</title><para>\n%gm) {
+            $in_refsect2=1;
+        }
+    }
+
+    # Make Paragraphs on blank lines
     $text =~ s%\n{2,}%\n</para>\n<para>\n%g;
   }
 
diff --git a/tests/gobject/src/gobject.c b/tests/gobject/src/gobject.c
index be33439..d19277d 100644
--- a/tests/gobject/src/gobject.c
+++ b/tests/gobject/src/gobject.c
@@ -16,12 +16,14 @@
  * whole lifecycle usualy looks like shown in this example:
  * |[<!-- language="C" -->
  * GObject *myobj;
- * 
+ *
  * myobj = gtkdoc_object_new();
  * // do somehing
  * g_object_unref (myobj);
  * ]|
  *
+ * # Examples #
+ *
  * You can also change parameters:
  * <informalexample>
  * <programlisting language="c"><xi:include xmlns:xi="http://www.w3.org/2003/XInclude"; parse="text" href="../../examples/gobject.c" /></programlisting>
@@ -44,6 +46,11 @@
  * @see_also: #GtkdocIface
  *
  * This file contains non-sense code for the sole purpose of testing the docs.
+ *
+ * Internals
+ * =========
+ *
+ * All the internal details go here or not.
  */
 
 #include <glib.h>
@@ -95,7 +102,7 @@ GtkdocObject *gtkdoc_object_new (void) {
  * Since: 0.5
  */
 void gtkdoc_object_set_otest (GObject *self, const gchar *value) {
-  
+
 }
 
 /**
@@ -114,7 +121,7 @@ void gtkdoc_object_set_otest (GObject *self, const gchar *value) {
  * Since: 0.5
  */
 void gtkdoc_object_frobnicate (GObject *self, gint n) {
-  
+
 }
 
 /**
@@ -184,7 +191,7 @@ static void gtkdoc_object_class_init (GtkdocObjectClass *klass) {
 
   /**
    * GtkdocObject::strings-changed:
-   * 
+   *
    * Something has happened.
    */
   g_signal_new ("strings-changed", G_TYPE_FROM_CLASS (klass),
@@ -195,11 +202,11 @@ static void gtkdoc_object_class_init (GtkdocObjectClass *klass) {
                 g_cclosure_marshal_VOID__BOXED,
                 G_TYPE_NONE, // return type
                 1, G_TYPE_STRV); // n_params
-  
+
 #if GLIB_CHECK_VERSION (2, 25, 9)
   /**
    * GtkdocObject::variant-changed:
-   * 
+   *
    * Something has happened.
    */
   g_signal_new ("variant-changed", G_TYPE_FROM_CLASS (klass),
@@ -285,7 +292,7 @@ GType gtkdoc_object2_get_type (void) {
     static const GInterfaceInfo interface_info = {
       NULL,  // interface_init
       NULL,  // interface_finalize
-      NULL   // interface_data 
+      NULL   // interface_data
     };
     type = g_type_register_static(G_TYPE_OBJECT,"GtkdocObject2",&info,0);
     g_type_add_interface_static(type, GTKDOC_TYPE_IFACE, &interface_info);