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.
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 automatically generated Node-IDs as described above works without manual effort, but it 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 you can see from the first <xsl:when>
in the
object.id
template, the
id
attribute of an element — if it exists — is
taken as the Node-ID. If every annotatable element has an id
, annotations
will persist even if the DocBook document is changed.
If you do not 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.