GNOME Bugzilla – Bug 784208
Warning: multiple "IDs" for constraint linkend: api-index-3.2.
Last modified: 2018-01-10 19:03:15 UTC
Trying to build evolution-data-server (for bug #783420) gtk-doc with git master of gtk-doc (at commit 0b348f6) introduces semi-new tons of (for me?) useless warnings on console, which look like: > Warning: multiple "IDs" for constraint linkend: api-index-3.2. with same and other "api-index-X-YZ" at the end. It used to do that for some version I do not recall, then it had been fixed and no more warnings like that. It's back now. Should it be back? I hope not. Trying with gtk-doc 1.25 release the warnings are not there.
(In reply to Milan Crha from comment #0) > Trying to build evolution-data-server (for bug #783420) gtk-doc... Oops, it was meant to be bug #784182.
I'm currently with gtk-doc-1.26-2.fc27.x86_64 and there are too many of these. I try to keep builds warning free, as much as I can, because compilers sometimes know why they claim issues. The gtk-doc data generation produces so many warnings like that, which makes it pretty hard to follow. I see two options: 1) either it's my fault, by giving incorrect data/sgml to gtk-doc, then, please, guide me how to fix it properly 2) it's an odd error from gtk-doc on data generated by gtk-doc itself, over which I have no control, then please either make the warnings visible only to gtk-doc developers, or fix the gtk-doc, or remove the warning altogether
Hej, keep calm. I don't get any help on maintaining gtk-doc. I am currently spending most of my free time on addressing performance and portability issues. I have limmited time to rebuild peoples projects to figure wha they run into issues. The fact that you wire your own build infrastructure does *not* make it easier. I just started a jhbuild for eds, so that hopefully I have a repro later today. On the issue above. If you get "Warning: multiple "IDs" for constraint linkend: api-index-3.2.", the first thing you can do is to grep the docbook xml for 'id="api-index-3.2"'. In your case you have: grep "=\"api-index-" evolution-data-server-docs.sgml.in <index id="api-index-full"> <index id="api-index-deprecated" role="deprecated"> <index id="api-index-3.28" role="3.28"> <index id="api-index-3.26" role="3.26"> <index id="api-index-3.24" role="3.24"> <index id="api-index-3.22" role="3.22"> <index id="api-index-3.20" role="3.20"> <index id="api-index-3.18" role="3.18"> <index id="api-index-3.16" role="3.16"> <index id="api-index-3.12" role="3.12"> <index id="api-index-3.10" role="3.10"> <index id="api-index-3.8" role="3.8"> <index id="api-index-3.6" role="3.6"> <index id="api-index-3.4" role="3.4"> <index id="api-index-3.2" role="3.2"> <index id="api-index-3.0" role="3.0"> <index id="api-index-2.32" role="2.32"> <index id="api-index-2.30" role="2.30"> <index id="api-index-2.28" role="2.28"> <index id="api-index-2.26" role="2.26"> <index id="api-index-2.24" role="2.24"> <index id="api-index-2.22" role="2.22"> <index id="api-index-1.12" role="1.12"> And this is the same 'id' that the docbook stylesheets set on the file that is included. The easiest workaround is to use 'id="api-index-1-12" in the <index> tag. This aparently was change in the docbook stylesheets at some point or the perl version or gtk-doc did suppress the error better. In any case, please just change the id. This exactly is one of the reason I am trying to abandon the xsl-stylesheets.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #3) > Hej, keep calm. I've been just suggesting options as I see them from my point of view and kindly asked for an advice. If you feel offended by any such thing, then please believe me it was not intended by any means. > The easiest workaround is to use 'id="api-index-1-12" in the <index> tag. Okay, I tried that, which resulted in no such warnings. There are still some other I'm not sure about (see below), but those about api-index are gone. As an example, the doc/reference/camel/ contains: <index id="api-index-3-28" role="3.28"> <title>Index of new symbols in 3.28</title> <xi:include href="xml/api-index-3.28.xml"><xi:fallback /></xi:include> </index> and looking into the build directory it also has "xml/api-index-3.28.xml" file, but this is not part of the html/ directory in the build dir, neither in PREFIX/usr/share/gtk-doc/html/camel/ I see installed only api-index-full.html there. I'd expect to see these indexes also in the index.html, but maybe you do not include it there intentionally. I compared the resulting files before and after this suggested change and I see the gtk-doc expects also the href in the above snippet to be change to an "xml/api-index-3-28.xml" (used dash in the version part, instead of dot), it seems. I changed that too, in the sgml file, and then nothing changed, the build dir still contains xml/api-index-3.28.xml file and no corresponding html/ file and it also added warnings about "warning: failed to load external entity "../xml/api-index-3-28.xml"", which makes sense. Maybe I'm comparing nonsense, I do not know internals of gtk-doc. ------------------------------------------------------------------------- For the above-mentioned other warnings I see: > Warning: multiple "IDs" for constraint linkend: CLIENT-BACKEND-PROPERTY-CAPABILITIES:CAPS. > ... > Element i in namespace '' encountered in para, but no template matches. There are multiple of those with ":CAPS" suffix. I searched my sgml file for "CLIENT-BACKEND-PROPERTY-CAPABILITIES", but it's not there. Note that I provide only the sgml file to gtk-doc, everything else it left up to gtk-doc itself. Grepping the sources for that define (dashes replaced with underscores), I see that define is declared multiple times, which I guess is the reason for the warning. I do not know how to change it in the code yet. The last print there is confusing too.
I forgot to add, would it make sense to prefix the "by gtk-doc generated ID-s" with something unique, thus they won't clash? Something like "gtk-doc-api-index-3.28", maybe? Then I could have "naturally written version in the index id" in the sgml file with no clash on gtk-doc generated ID-s.
(In reply to Milan Crha from comment #4) > (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #3) > > Okay, I tried that, which resulted in no such warnings. There are still some > other I'm not sure about (see below), but those about api-index are gone. As > an example, the doc/reference/camel/ contains: > > <index id="api-index-3-28" role="3.28"> > <title>Index of new symbols in 3.28</title> > <xi:include href="xml/api-index-3.28.xml"><xi:fallback /></xi:include> > </index> > > and looking into the build directory it also has "xml/api-index-3.28.xml" > file, but this is not part of the html/ directory in the build dir, neither > in > PREFIX/usr/share/gtk-doc/html/camel/ > I see installed only api-index-full.html there. I'd expect to see these > indexes also in the index.html, but maybe you do not include it there > intentionally. > > I compared the resulting files before and after this suggested change and I > see the gtk-doc expects also the href in the above snippet to be change to > an "xml/api-index-3-28.xml" (used dash in the version part, instead of dot), > it seems. I changed that too, in the sgml file, and then nothing changed, > the build dir still contains xml/api-index-3.28.xml file and no > corresponding html/ file and it also added warnings about "warning: failed > to load external entity "../xml/api-index-3-28.xml"", which makes sense. > Maybe I'm comparing nonsense, I do not know internals of gtk-doc. This could be #785139, please check if you are affected too (let me know what distro you are using and which version of the docbook-xsl package). > > ------------------------------------------------------------------------- > > For the above-mentioned other warnings I see: > > > Warning: multiple "IDs" for constraint linkend: CLIENT-BACKEND-PROPERTY-CAPABILITIES:CAPS. > > ... > > Element i in namespace '' encountered in para, but no template matches. > > There are multiple of those with ":CAPS" suffix. I searched my sgml file for > "CLIENT-BACKEND-PROPERTY-CAPABILITIES", but it's not there. Note that I > provide only the sgml file to gtk-doc, everything else it left up to gtk-doc > itself. Grepping the sources for that define (dashes replaced with > underscores), I see that define is declared multiple times, which I guess is > the reason for the warning. I do not know how to change it in the code yet. > The last print there is confusing too. Can we track this as a new bug? Thanks!(In reply to Milan Crha from comment #5) > I forgot to add, would it make sense to prefix the "by gtk-doc generated > ID-s" with something unique, thus they won't clash? Something like > "gtk-doc-api-index-3.28", maybe? Then I could have "naturally written > version in the index id" in the sgml file with no clash on gtk-doc generated > ID-s. I retrospect, definitely! Please understand that I took over maintainership of gtk-doc and changing this now requires to do this in a way that won't break existing projects.
> This could be #785139, please check if you are affected too (let me know > what distro you are using and which version of the docbook-xsl package). Okay, I updated bug #785139. > Can we track this as a new bug? Thanks! I'm not sure it's a bug in gtk-doc at all, because the code contains multiple documentation comments with the same symbol, which is correct in this case, even it's not ideal. If you think such thing can be covered in gtk-doc, then I'll file it, but you can claim that it's an issue in the code, with which I'm fine as well. It's for the "multiple IDs". I still do not know how to track which part of the documentation is this warning about: > Element i in namespace '' encountered in para, but no template matches. > I retrospect, definitely! Please understand that I took over maintainership > of gtk-doc and changing this now requires to do this in a way that won't > break existing projects. If you think that some projects rely on IDs generated by gtk-doc itself, and reference them in their "code", then it's an obstacle for sure. How much correct behaviour and expectation from their side it is is hard to say. :)
Just for the record, I fixed that api-index ID clash in eds [1] and evo [2] for 3.27.90 release in a way suggested above (s/api-index-1.2/api-index-1-2/). [1] https://git.gnome.org/browse/evolution-data-server/commit/?id=4cb2655f1796db35afa41f63423c177446e78ce1 [2] https://git.gnome.org/browse/evolution/commit/?id=28c701389d2dca7b5248aa5b3edf2a4bdd4ad117
Thanks. I am closing this one now. With regards to the "Warning: multiple "IDs" for constraint linkend" you would need to grep all XML files for those since all of them form one unit (like multiple symbols are clashing when linking a binary). If those IDs are generated by gtk-doc then it is probably a good idea to prefix them (e.g. with the section-id). If those are in hand-written files it is a user-error. Of course it would be nice to print a better file:line stale error. I don't mind a new ticket and if it turns out not to be a gtk-doc bug, we'll close it :)