GNOME Bugzilla – Bug 365913
gtk-doc output is not predictable
Last modified: 2007-11-11 16:45:32 UTC
This is a problem for distributions 1. uses gtk-doc in their build system; to provide packages said gtk-doc output 2. and supports multi-lib; e.g. wants to install 32-bit and 64-bit packages The bug such distributions run into is that e.g. files in foo-devel.i386.rpm differs from foo-devel.x86_64.rpm because the generated gtk-doc files differs. Adding Matthias as cc as he already looked into this Thanks.
Can someone attach a diff so we can see what the differences are?
the differences are in generated ids using the non-deterministic generate-id xslt function. Fixing this would be easy, but needs to happen in libxslt. The current implementation uses memory addresses of nodes.
Would it help if we generate the id's in a deterministic way in gtk-doc? Matthias, could you still attach a diff that highlights the issue.
The generated ids occur in two places: 1. Sections (Top, Description, See Also, Object Hierarchy, ...). Giving them ids will help, either by itself or with some gtk-doc.xsl modification. 2. Index. Every index term is currently created in a way that it produces a new anchor which gets a generated id, even though there is already a perfectly good anchor to point to for each term. I don't know what effect the other index generation patches have on this, but perhaps it can be fixed by using zoned index terms (that refer to a particular id) instead of location-based index terms.
Created attachment 96073 [details] [review] proposed patch (part 1) Add ids to subsections such as Signals or See Also.
Stefan, I don't think any info is needed here, we just have to add ids to all referable elements (namely subsections) and generate index terms in less silly manner. Then there will be no auto-generated ids.
However, I would welcome if someone with stronger XSLT-fu told me how to get the section id in the header.navigation template so that <xsl:if test="count($sect_prerequisites) > 0">  |  <a href="#{generate-id(./refsect1[@role='prerequisites'])}" class="shortcut"> <xsl:value-of select="./refsect1[@role='prerequisites']/title"/> </a> </xsl:if> can be replaced with something like <xsl:if test="count($sect_prerequisites) > 0">  |  <a href="#$section_id.prerequisites" class="shortcut"> <xsl:value-of select="./refsect1[@role='prerequisites']/title"/> </a> </xsl:if>
Created attachment 96074 [details] [review] proposed patch (part 1) Missed a few subsections in the first patch.
Created attachment 96075 [details] [review] proposed patch (part 2) I figured out how to obtain the section id. Refer to subsections by the id we gave them instead of using generate-id function.
Created attachment 96408 [details] [review] proposed patch (part 1+3) Exterminate <anchor>s (almost), assign the ids to the real things, namely sections. The only remaining <anchor>s are section-level object anchors that are not so easy to get rid of as a section can describe multiple objects. Change <indexterm>s to zoned. Give them their own id so they are referrable. The id is composed as the id of the real thing with `.index' appended (this is a bit dumb but works at least as a proof of concept without fiddling with the XSL). Since parts 1 and 3 touch the same lines, this patch contains both.
Assigning ids to zoned <indexterm>s is wrong and reveals a deeper problem. They are never referred to -- if they were, it would be a stylesheet bug as their physical location is irrelevant. Yet the stylesheet generates <a id="id297450" class="indexterm"></a> in the (irrelevant) place corresponding to the zoned <indexterm> physical location. And this junk is what causes most of the troubles.
Created attachment 96537 [details] [review] proposed patch Added a XSL rule that prevents the output of the redundant indexterm anchors. Replaced the XSL rule that generated the top_of_page anchor with id="$section_id.top_of_page" on the corresponding item. This assumes that people 1. do not use the role='top_of_page' hack in manually written content files -- this seems to hold at least for Gnome documentation. 2. assign ids to all sections and elements referred in the index. If they don't the index will still work, but generated ids are unavoidable. The only remaining generated ids are from sections without and id and the -- probably misguided -- fix of bug 448879.
Created attachment 96890 [details] [review] proposed patch Update generation of index.sgml to match all elements we want to generate it from since now ids are generally on elements instead of extra <anchor>s.
2007-11-11 Stefan Kost <ensonic@users.sf.net> patch by: David Nečas <yeti@physics.muni.cz> * gtk-doc.xsl: * gtkdoc-mkdb.in: Avoid generated node ids. Fixes #365913.