GNOME Bugzilla – Bug 725194
gtkdoc doclet mismatches <para> tags for <programlisting> tags
Last modified: 2016-12-05 18:10:41 UTC
With folks master (currently commit 87e037787476ba), {{{}}} code listing blocks in folks/folks/individual-aggregator.vala get mis-parsed. The output generated in individual-aggregator.xml looks like: <para> <programlisting> foo(); <para> bar(); </programlisting> ... </para> </para> This results in "warnings" like the following: ../xml/individual-aggregator.xml:156: parser error : Opening and ending tag mismatch: para line 153 and programlisting yield my_individual_aggregator.link_personas (personas);</programlisting> The ^ This is clearly an error in gtk-doc but valadoc itself treats it like a warning. So I only noticed that no gtk-doc HTML was being generated because my install was failing due to: /home/treitter/.local/bin/install-check -m 644 ./gtk-doc/folks/html/* '/opt/gnome/_jhbuild/root-folks/opt/gnome/share/gtk-doc/html/folks' install: cannot stat ‘./gtk-doc/folks/html/*’: No such file or directory
This happens in rygel as well: "make install" fails in doc/reference/librygel-core because the xml for rygel-plugin-information.vala is malformed.
Created attachment 273174 [details] generated c-comment file There is this warning a little before the parser error: /home/jku/src/jhbuild/sources/rygel/doc/reference/librygel-core/gtkdoc/ccomments/rygel-plugin-information.c:57: warning: Can't find tag end: </programlisting> in docs for: RygelPluginInformation I'm attaching the generated ccomments/rygel-plugin-information.c. I can't see anything wrong with it but then I don't know what that should look like...
Created attachment 278916 [details] [review] gtkdoc: Fix generated markup for source code blocks Just emitting <programlisting> doesn’t work, as gtk-doc will insert <para> tags in the middle of the code block, generating invalid markup. Instead of trying to reinvent how gtk-doc does things, just emit the gtk-doc shorthand markup for a code block and let gtk-doc generate the markup.
Created attachment 289791 [details] [review] gtkdoc: Fix generated markup for source code blocks Just emitting <programlisting> doesn’t work, as gtk-doc will insert <para> tags in the middle of the code block, generating invalid markup. Instead of trying to reinvent how gtk-doc does things, just emit the gtk-doc shorthand markup for a code block and let gtk-doc generate the markup.
(Rebased on master. Still needs reviewing and committing.)
Comment on attachment 289791 [details] [review] gtkdoc: Fix generated markup for source code blocks Looks like this got pushed in May 2015 but the bug didn’t get updated. 9d0548335f85d9f91a7c97532eba47e0c6c6d454