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.