GNOME Bugzilla – Bug 783420
gtkdoc-mkhtml cannot build documentation for pango because < and > are not escaped
Last modified: 2017-08-09 14:05:36 UTC
This happens when building pango with --enable-gtk-doc when srcdir == builddir: DOC Building HTML ../xml/pangocairo.xml:153: parser error : error parsing attribute name #include <pango/pangocairo.h> ^ ../xml/pangocairo.xml:153: parser error : attributes construct error #include <pango/pangocairo.h> ^ ../xml/pangocairo.xml:153: parser error : Couldn't find end of Start Tag pango line 153 #include <pango/pangocairo.h> ^ ../xml/pangocairo.xml:242: parser error : Opening and ending tag mismatch: math.h line 152 and programlisting </programlisting> ^ ../xml/pangocairo.xml:243: parser error : Opening and ending tag mismatch: programlisting line 151 and example </example> ^ ../xml/pangocairo.xml:249: parser error : Opening and ending tag mismatch: example line 149 and refsect1 </refsect1> ^ ../xml/pangocairo.xml:1124: parser error : Opening and ending tag mismatch: refsect1 line 122 and refentry </refentry> ^ ../xml/pangocairo.xml:1125: parser error : Premature end of data in tag refentry line 8 ^ ../pango-docs.sgml:33: element include: XInclude error : could not load ../xml/pangocairo.xml, and no fallback was found Running diff on files generated by the new python version and the old perl version shows < and > used in example code don't get escaped when the new python version is used: @@ -149,8 +149,8 @@ <example id="rotated-example"> <title>Using Pango with Cairo</title> <programlisting> -#include <math.h> -#include <pango/pangocairo.h> +#include <math.h> +#include <pango/pangocairo.h> static void draw_text (cairo_t *cr) This problem can also be reproduced by building pango with meson. It cannot be reproduced by doing out-of-source build of pango with autotools because pangocairo.xml is broken and nearly empty.
Link: https://git.gnome.org/browse/pango/tree/pango/pangocairo-render.c#n56 This is not using the standard way of embedding code ( |[ code ]| ), so it is probably also not highlighted. Need to check.
Created attachment 353965 [details] [review] test Actually I think the pango docs should be fixed instead. If one uses XML, the XML must be valid. So in this case there are two options: 1) use CDATA: * <title>Using Pango with Cairo</title> * <programlisting><![CDATA[ * #include <math.h> ... * ]]></programlisting> 2) use the short notation: * <title>Using Pango with Cairo</title> * |[ * #include <math.h> ... * ]| I could not see through which code path the perl version accidentally made this work, but since this is the first report, I rather see the pango docs fixed, that making this an official feature. WDYT?
I am doing a full rebuild to find all jhbuild modules having this problem, so I can file all bugs at once.
It seems that only pango and telepathy-logger have this problem.
I tried the short notation, but it causes '#include &lt;math.h&gt;' to be written to html ...
I filed 3 bugs for the problem. Pango https://bugzilla.gnome.org/show_bug.cgi?id=784181 Evolution-Data-Server https://bugzilla.gnome.org/show_bug.cgi?id=784182 Telepathy-Logger https://bugs.freedesktop.org/show_bug.cgi?id=101585
I'll take another look.
Ting, I added an example: https://git.gnome.org/browse/gtk-doc/commit/?id=8f451a60b2290863194d137e02e1c5b477293de8 and it works for me.
The generated html is: <informalexample><programlisting language="C"><![CDATA[ #include <glib.h> #include <glib-object.h> GObject *myobj; myobj = gtkdoc_object_new(); ... But the changes you made looks good too.
I can repro this finally. The problem happens for examples in docbook sections. See this example, the first source is rendered good, the 2nd isn't. Expect a fix later today. /** * bug_783420: * @in: input * @out: output * * http://bugzilla.gnome.org/show_bug.cgi?id=783420 * * |[ * #include <tester.h> * * int res; * bug_783420(42, &res); * ]| * * <refsect2 id="subsect"> * <title>Subsection</title> * <para> * Lorem ipsum ... * |[ * #include <tester.h> * * int res; * bug_783420(42, &res); * ]| * </para> * </refsect2> */
commit d1c3e1708f079ab91502e83304fb88d74e6f8d0d Author: Stefan Sauer <ensonic@users.sf.net> Date: Wed Aug 9 15:58:35 2017 +0200 mkdb: also replace entities in non-markdown sections Fixes: https://bugzilla.gnome.org/show_bug.cgi?id=783420 Please reopen if the issue still happens.