GNOME Bugzilla – Bug 727523
Failed to rebuild docs using gtk-doc-1.20
Last modified: 2014-05-10 16:17:19 UTC
Building goocanvas-2.0.2 on OS X with --enable-gtk-doc (I have gtk-doc-1.20 installed) fails in the "DOC Building HTML" stage with a mile of warnings, but more importantly, errors: DOC Building HTML ../xml/goocanvasitem.xml:868: parser error : Opening and ending tag mismatch: refsect2 line 843 and para </refsect3></para> ^ ../xml/goocanvasitem.xml:875: parser error : Opening and ending tag mismatch: para line 869 and refsect2 </refsect2> ^ ../goocanvas2-docs.sgml:23: element include: XInclude error : could not load ../xml/goocanvasitem.xml, and no fallback was found ../xml/goocanvasitemmodel.xml:676: parser error : Opening and ending tag mismatch: refsect2 line 651 and para </refsect3></para> ^ and similar tag-mismatch parser-errors reported for many other ../xml/*.xml. I see the same error reported for goocanvas-0.15. I've heard that gtk-doc is movings towards stricter handling of html. The errors all went away when I adjusted lots of src/*.c files that had a line in a function documentation block comment of: * <!--PARAMETERS--> Maybe gtk-doc (now) treats that as some sort of tag rather than as a string of "PARAMETERS" inside a comment? Changing that to: * <!-- PARAMETERS --> (whitespace between the comment delimiters and the comment text) solved it.
Moving to gtk-doc as this is probably caused by all the recent changes there. The "<!--PARAMETERS-->" comment is used to tell gtk-doc where to put the little table of function parameter documentation. It looks like this isn't working now.
Continuing to use goocanvas-0.15 as my test case, gtk-doc-1.18 and gtk-doc-1.19 work fine, so it's due to some change in 1.19->1.20. It looks like the gtkdoc-mkdb handler of the <!--PARAMETERS--> token inserts the parameters table correctly as a <refsect3>...</refsect3> block, but then is placing a stray </para> followed by <para> before copying the content that follows the <!--PARAMETERS--> token. Sounds related to gtkdoc-mkdb line 4471 (in 1.20)? # Convert <!--PARAMETERS--> with any blank lines around it to # a </para> followed by <!--PARAMETERS--> followed by <para>. $src_doc =~ s%\n+\s*<!--PARAMETERS-->\s*\n+%\n</para>\n<!--PARAMETERS-->\n<para>\n%g; making an invalid assumption about the context of the token? But then why are the stray close-then-open together *after* the actual parameters content?
It looks like it doesn't work with all the new code to handle "markdown".
Damon, since all the years I am now maintaining gtk-doc I never came across this feature (you added in gtk-doc-1.3). I does not seem to be widely used (I grepped my jhbuild checkout and find 0 uses) and it neither is documented in the yelp manual. Do we want to keep this? Re comment #1, From the gtk-doc code, the tag '<!--PARAMETERS-->' is without spaces. If you add spaces, you leave a XML comment in the generated code and have default parameter positions.
Yes, it is probably easier to just remove the feature if noone uses it.
Created attachment 274725 [details] [review] Patch to remove support for <!--PARAMETERS--> Here's a quick patch to remove the support for the <!--PARAMETERS--> flag. But check it!
Comment #6 patch applied to gtk-doc-1.20 built fine, and enabled building of goocanvas-0.15, and the results appear identical to my original solution of converting the special token to a normal *ML comment tag.
Comment on attachment 274725 [details] [review] Patch to remove support for <!--PARAMETERS--> Thanks, please push.
Pushed