What Annotate does with your document

What Annotate does with your document
Prev	Chapter 2. How Annotate works	Next

XSL processing

Annotate relies on the DocBook XSL style sheets to generate HTML output: it imports the DocBook XSL style sheets and extends them. In other words, Annotate provides a customization layer to the DocBook style sheets.

Preserving Node-IDs

Annotate can make parts of your document annotatable. In order to achieve this, it needs to uniquely identify every annotatable element in your document, that is, each part (“node”) of the document needs an identifier (“Node-ID”). Annotate uses the object.id template which is defined in common/common.xsl in the DocBook style sheets:

<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:otherwise>
      <xsl:value-of select="generate-id($object)"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

The object.id template automatically generates a unique identifier for each part of your document. By default it relies on the XSLT generate-id() function which is part of the XSLT specification:

The generate-id function returns a string that uniquely identifies the node in the argument node-set that is first in document order. [...] An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed.

Using Node-IDs generated like this works automatically, but is has one drawback: if the source document is changed, the IDs change and thus the link between existing annotations and their positions in the document is lost.

However, there is a solution to this problem: as the object.id template suggests the id attribute of an element -- if it exists -- is taken as the Node-ID. If every annotatable element has an id, comments will persist even if the DocBook document is changed.

If you don't want to add id attributes manually, you can do it automatically with a script. In the misc directory, the Annotate distribution provides a Perl script (generate-ids.pl) which can do this: it will scan your document for existing IDs and then add additional, randomly generated ones to every annotatable element lacking an ID.