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
annoref,
annotation (block variant),
annotation (phrase variant),
m:annotation-xml,
aside,
block,
caption,
citation (block variant),
citation (phrase variant),
d,
definition,
description (block variant),
description (phrase variant),
emph,
expansion,
h,
hd,
hpart,
item,
ln,
d:longdesc,
meta,
note (block variant),
note (phrase variant),
noteref,
object (block variant),
object (phrase variant),
p,
ssml:phoneme,
ssml:prosody,
quote (block variant),
quote (phrase variant),
its:rb,
ref,
its:rt,
s,
ssml:say-as (phrase variant),
ssml:say-as (text variant),
d:simplifiedLanguageDescription,
span,
ssml:sub,
d:summary,
td,
term,
th and
d:tour
Allowed children
This element may contain text.
This element may contain the following children: abbr,
annoref,
ssml:break,
char,
code,
d,
definition,
emph (text variant),
emph (phrase variant),
expansion,
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),
ref,
its:ruby,
s,
ssml:say-as (text variant),
ssml:say-as (phrase variant),
span (phrase variant),
span (text variant),
sub,
ssml:sub (text variant),
ssml:sub (phrase variant),
sup,
term,
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,
@ssml:onlangfailure,
@typeof,
@value,
@xml:base,
@xml:id,
@xml:lang and
@xml:spacea choice of
either no content
or
one or more of
a choice of either one of the 42 elements:
abbr,
annoref,
char,
code,
d,
definition,
emph,
emph,
expansion,
its:ruby,
ln,
m:math,
name,
note,
noteref,
num,
object,
object,
pagebreak,
ref,
rend:linebreak,
s,
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 or
wor text
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>