[gtk-doc] docs: improve docs for the sections.txt file

[Stefan Kost <stefkost src gnome org>]

commit 88bf236077fc5c469aeb8ffc001bbc9e89e56c53
Author: Stefan Sauer <ensonic users sf net>
Date:   Tue Sep 29 22:04:04 2015 +0200

    docs: improve docs for the sections.txt file
    
    Explicitly state that this is not xml.
    Fixes #751777

 help/manual/C/index.docbook |   28 +++++++++++++++++++++++++++-
 1 files changed, 27 insertions(+), 1 deletions(-)
---
diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook
index 3437abd..cac2db7 100644
--- a/help/manual/C/index.docbook
+++ b/help/manual/C/index.docbook
@@ -1672,10 +1672,36 @@ gtk_arrow_get_type
       </para>
 
       <para>
-        The section file is a plain text file with XML-like syntax (using tags).
+        The section file is a plain text file with tags delimiting sections.
         Blank lines are ignored and lines starting with a '#' are treated as
         comment lines.
       </para>
+      
+      <note>
+        <para>
+          While the tags make the file look like xml, it is not. Please do not
+          close tags like &lt;SUBSECTION&gt;.
+        </para>
+      </note>
+
+      <para>
+        <example><title>Including generated sections</title>
+          <programlisting><![CDATA[
+<INCLUDE>libmeep/meep.h</INCLUDE>
+
+<SECTION>
+<FILE>meepapp</FILE>
+<TITLE>MeepApp</TITLE>
+MeepApp
+<SUBSECTION Standard>
+MEEP_APP
+...
+MeepAppClass
+meep_app_get_type
+</SECTION>
+]]></programlisting>
+        </example>
+      </para>
 
       <para>
         The &lt;FILE&gt; ... &lt;/FILE&gt; tag is used to specify the file name,