Stopping DocBook Version Control Churn
I have been getting frustrated with DocBook's generation of HTML files, because it seems to gratuitously insert random id's for things in a pattern that doesn't repeat, so you run xsltproc on the same file twice, and the output changes. subversion, git, etc... pick up on the differences and want to save the new version, which is quite annoying.
I figured out a way to get around this. I have no idea if it's ugly or not, but it works and that's enough for me. Comments/ideas/improvements welcome.
<xsl:template name="object.id">
<xsl:param name="object" select="."/>
<xsl:choose>
<xsl:when test="$object/@id">
<xsl:value-of select="$object/@id"/>
</xsl:when>
<xsl:when test="$object/@xml:id">
<xsl:value-of select="$object/@xml:id"/>
</xsl:when>
<xsl:otherwise>
id-<xsl:number level="multiple" count="*"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
The key is the line:
id-<xsl:number level="multiple" count="*"/>
which replaces
<xsl:value-of select="generate-id($object)"/>
The problem is that generate-id, at least in xsltproc, uses a fairly random bit of data (memory location) to create the id.
My fix uses the location of the element within the document as the id.
Trackbacks
Use the following link to trackback from your own site:
http://journal.dedasys.com/trackbacks?article_id=2164
about 1 hour later:
Errrr... In the FreeBSD Documentation Project, we've been using a slightly different solution for ages - just add "id" attributes to all the , , etc. elements :) This makes it a bit easier to actually link to them afterwards, too. And I've not found it to be any amount of bothersome trouble.
Of course, YMMV, and if you really don't want to - or can't - or something - add the ID attributes everywhere, well, then, I guess disabling generate-id is a good thing.
about 1 hour later:
Argh, and of course, I did use "Preview", but didn't see the obvious problem with my comment... that should have read:
...just add "id" attributes to all the "section", "chapter", "footnote", etc. elements :)
about 1 hour later:
I have id attributes for most of the 'high level' elements that I care about. That's also a good idea because it lets you generate HTML files with names that come from the id's. However, for things like refsect1's, it just doesn't seem to matter that much, and would be a lot of work.
about 4 hours later:
Err, you shouldn't be storing generated files in a VCS anyway. You wouldn't do the same for ELF executables, why for generated HTML?
about 4 hours later:
Err, you shouldn't be storing generated files in a VCS anyway. You wouldn't do the same for ELF executables, why for generated HTML?
about 21 hours later:
The xsl snippets got through to your atom feed unescaped so they do not show up on aggregators.
2 days later:
someone - I store generated stuff as a convenience, so that people downloading the latest sources have documentation, without having to go through the hassle of running xsltproc.