Schema Documentation - Book Profile
version 1.0

The annoref element

On this page:

The annoref element represents a textual reference to an annotation .

Although not as common as with footnotes and endnotes, the content or location in the document being annotated may be noted by a text referent (e.g., a superscripted symbol).

By default, the text content of the annoref represents the link reference and is treated as document content. When superscripted numbers or symbols are instead used to identify the corresponding annotation, the value attribute should be used. The annoref must be an empty element when attaching a value attribute; it it not permitted to include text content and a value attribute.

The ref attribute is used to establish the link between the annoref and its associated annotation.

Usage details available in the Usage Details section.

Usage Example

<p>…it created a great chasm between my step-mother and me.<annoref ref="anno-04" value="4" /></p>

<annotation xml:id="anno-04" by="translator">
    This needs explanation. In Germany, even by strangers, children are universally addressed…
</annotation>

Allowed parents

address, annoref, annotation (block variant), annotation (phrase variant), m:annotation-xml, aside (block variant), aside (toc variant), block, caption, citation (block variant), citation (phrase variant), d, definition, description (block variant), description (phrase variant), emph, entry (toc variant), entry (index variant), entry (bibliography variant), entry (glossary variant), expansion, xforms:group, h, hd, hpart, item, xforms:label, ln, d:longdesc, meta, note (block variant), note (phrase variant), noteref, object (block variant), object (phrase variant), sel:otherwise, p, ssml:phoneme, ssml:prosody, quote (block variant), quote (phrase variant), its:rb, ref, xforms:repeat, its:rt, s, ssml:say-as (phrase variant), ssml:say-as (text variant), d:simplifiedLanguageDescription, span, spine, ssml:sub, d:summary, td, term, th, d:tour and sel:when

Allowed children

This element may contain text.

This element may contain the following children: abbr, address, annoref, ssml:break, char, code, d, definition, emph (text variant), emph (phrase variant), expansion, xforms:input, rend:linebreak, ln, m:math, name, note, noteref, num, object (text variant), object (phrase variant), pagebreak, ssml:phoneme (text variant), ssml:phoneme (phrase variant), ssml:prosody (text variant), ssml:prosody (phrase variant), xforms:range, ref, its:ruby, s, ssml:say-as (text variant), ssml:say-as (phrase variant), xforms:secret, sel:select, xforms:select, xforms:select1, span (phrase variant), span (text variant), sub, ssml:sub (text variant), ssml:sub (phrase variant), sup, term, xforms:textarea, time, ssml:token (text variant), ssml:token (phrase variant) and w

Content model and additional requirements

required attributes: @ref
optional attributes: @about, @by, @class, @content, @continuation, @datatype, @desc, @its:dir, @its:translate, @property, @rel, @resource, @rev, @role, @sel:selid, @ssml:onlangfailure, @typeof, @value, @xml:base, @xml:id, @xml:lang and @xml:space
optionally the following 2 co-ocurring attributes: @ssml:alphabet and @ssml:ph
a choice of
either no content
or one or more of
a choice of
either one of the 50 elements: abbr, address, annoref, char, code, d, definition, emph, emph, expansion, its:ruby, ln, m:math, name, note, noteref, num, object, object, pagebreak, ref, rend:linebreak, s, sel:select, span, span, ssml:break, ssml:break, ssml:phoneme, ssml:phoneme, ssml:prosody, ssml:prosody, ssml:say-as, ssml:say-as, ssml:sub, ssml:sub, ssml:token, ssml:token, sub, sup, term, time, w, w, xforms:input, xforms:range, xforms:secret, xforms:select, xforms:select1 or xforms:textarea
or text
end of choice
end of choice
Note that in addition to restrictions presented in the content model above, use of this element must also respect the following requirements:
  • The value attribute cannot be used on a non-empty annoref.
  • An empty annoref element must include a value attribute.
  • The IDREF(s) in the ref attribute must resolve to annotations.
  • Superscripted referents should be included in a value attribute, not as text content.
Such requirements take precedence over any conflicting statements in the content model or in the lists above of allowed children and parents.

Namespace

http://www.daisy.org/ns/z3998/authoring/

Usage Details

There are two means of tagging references to annotations. When a superscripted identifier is used, the value attribute is required: 

<p>…it created a great chasm between my step-mother and me.<annoref ref="anno-04" value="4" /></p>

In the above example, the annotation identifier (the number 4) is no longer part of the document content, but can still be output and repurposed by a processing agent.

It is sometimes the case, however, that using one or more words in the content to link to the annotation is preferred to a superscripted identifier. In this case, the value attribute is omitted and the text content of the annoref becomes the linkable text: 

<p>…it created a great chasm between <annoref ref="anno-04">my step-mother and me</annoref>.</p>

An additional benefit to tagging words instead of inserting superscripted referents is that a transformation process could automatically remove the link from the words and instead insert superscripted numbers or symbols after the element when they are needed. It would not be possible to do the reverse if only the superscripts have been tagged, however.

It is illegal to use an empty element and omit a value attribute, as in the following example, as some text content is necessary to render the link: 

<p>…it created a great chasm between my step-mother and me.<annoref ref="anno-04" /></p>

It is also illegal to use text content together with a value attribute, as it introduces ambiguity in how to format the output: 

<p>…it created a great chasm between <annoref ref="anno-04" value="4">my step-mother and me</annoref>.</p>