[gtk-doc] help: Add a bit more about markdown

[William Jon McCann <mccann src gnome org>]

commit e2dc5547197a3993cd2b2098b17e3ef6b1fa757f
Author: William Jon McCann <william jon mccann gmail com>
Date:   Fri Feb 14 12:59:46 2014 -0500

    help: Add a bit more about markdown

 help/manual/C/index.docbook |   62 +++++++++++++++++++++++++++++++------------
 1 files changed, 45 insertions(+), 17 deletions(-)
---
diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook
index 5218c33..193daed 100644
--- a/help/manual/C/index.docbook
+++ b/help/manual/C/index.docbook
@@ -811,53 +811,81 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
       </para>
 
       <tip>
-             <para>
+        <para>
           If you need to use the special characters '&lt;', '&gt;', '()', '@',
           '%', or '#' in your documentation without GTK-Doc changing them you
           can use the XML entities "&amp;lt;", "&amp;gt;", "&amp;lpar;",
           "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and "&amp;num;"
           respectively or escape them with a backslash '\'.
-             </para>
+        </para>
       </tip>
 
       <para>
-        DocBook can do more than just links. One can also have lists, tables and
-        examples. To enable the usage of docbook SGML/XML tags inside
-        doc-comments you need to have <option>--xml-mode</option> or
+        DocBook can do more than just links. One can also have lists,
+        examples, headings, and images. As of version 1.20, the
+        preferred way is to use a subset of the basic text formatting
+        syntax called
+        <ulink url="http://daringfireball.net/projects/markdown/";>Markdown</ulink>.
+        On older GTK-Doc versions any documentation that includes
+        Markdown will be rendered as is.  For example, list items will
+        appear as lines starting with a dash.
+      </para>
+
+      <para>
+        In older GTK-Doc releases, if you need support for additional
+        formatting, you would need to enable the usage of docbook
+        SGML/XML tags inside doc-comments by
+        putting <option>--xml-mode</option> or
         <option>--sgml-mode</option> in the variable
         <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.
       </para>
 
       <para>
-        Since GTK-Doc-1.18 the tool supports a subset of the
-        <ulink url="http://daringfireball.net/projects/markdown/";>markdown language</ulink>.
-        The support has improved a lot with version 1.20. On older GTK-Doc
-        versions the content will be rendered as it (the list items will appear
-        in one line separated by dashes).
-        <example><title>GTK-Doc comment block using markdown</title>
+        <example><title>GTK-Doc comment block using Markdown</title>
           <programlisting>
 <![CDATA[
 /**
  * identifier:
  *
- * documentation ...
+ * documentation paragraph ...
+ *
+ * # Sub Heading #
  *
- * # Sub heading #
+ * ## Second Sub Heading
+ *
+ * # Sub Heading With a Link Anchor # {#heading-two}
  *
  * more documentation:
+ *
  * - list item 1
+ *
+ *   Paragraph inside a list item.
+ *
  * - list item 2
  *
- * Even more docs.
+ * 1. numbered list item
+ *
+ * 2. another numbered list item
+ *
+ * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
+ *
+ * ![an inline image][plot-result.png]
+ *
+ * [A link to the heading anchor above][heading-two]
+ *
+ * A C-language example:
+ * |[<!-- language="C" -->
+ * GtkWidget *label = gtk_label_new ("Gorgeous!");
+ * ]|
  */
 ]]>
           </programlisting>
         </example>
       </para>
-      
+
       <para>
-        More examples of what markdown tags are supported can be found in the 
-        <ulink url="http://git.gnome.org/browse/gtk-doc/tree/tests";>gtk-doc test suite</ulink>.
+        More examples of what markdown tags are supported can be found in the
+        <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown";>GTK+ Documentation 
Markdown Syntax Reference</ulink>.
       </para>
 
       <tip>