GNOME Bugzilla – Bug 611848
gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside <para>
Last modified: 2010-03-05 10:12:42 UTC
Sample documentation comment that will produce invalid markup: /** * SECTION:dummysection * @Short_description: Dummy section * @Title: Dummy section * * This is first paragraph. * * <refsect2 id="dummy-id"> * <para> * Second paragraph inside subsection. * </para> * </refsect2> */ Produced markup: <refsect1 id="dummysection.description" role="desc"> <title role="desc.title">Description</title> <para> This is first paragraph. </para> <para> <refsect2 id="dummy-id"> <para> Second paragraph inside subsection. </para> </refsect2> </para> </refsect1> Tadej
This is the logic at fault in gtkdoc-mkdb:MergeSourceDocumentation. It operators on the doc body. # If there is a blank line, finish the paragraph and start another. $src_doc = &ConvertBlankLines ($src_doc, $symbol); # Do not add <para> to nothing, it breaks missing docs checks. my $src_doc_para = ""; if ($src_doc) { $src_doc_para = "<para>\n$src_doc</para>\n"; #print "$symbol : [$src_doc][$src_doc_para]\n"; } It is not as easy as suppressing the </para> on the end, you would also want to suppress the <para> before <refsect2>. Now unfortunately gtk-doc does not parse the docbook dtd, it only cares about well-formed xml (but does not ensure really). I think the easies way would be to introduce proper wiki markup, so that people would not need to use docbook so much here.
commit 366f2b6823bd8e4d4748fd5fed6d822d53d38f83 Author: Stefan Kost <ensonic@users.sf.net> Date: Fri Mar 5 12:11:17 2010 +0200 mkdb: fix xml when using refsect2 in docblobs, Fixes #611848 Strip para tag wrapping the refsect2. Add example to tests.