The
noteref element represents a textual reference to a
note (block)
.
Note references typically appear as superscripted numbers or symbols within the narrative flow but may also appear as linked
words, especially in electronic formats.
The
ref
attribute is used to establish the link between the note reference and its associated
note.
By default, the text content of the
noteref represents the link reference and is treated as document content. When superscripted numbers or symbols are used to identify
the corresponding
note, the
value
attribute should be used. The
noteref must be an empty element when attaching a
value attribute; it it not permitted to include text content and a
value attribute.
Usage details available in the Usage Details section.
Usage Example
<p>THE following pages contain Extracts from LETTERS addressed
to Professor HENSLOW<noteref ref="n2" value="2" /> by C. DARWIN, Esq. … </p>
…
<note xml:id="n2">
<p>John Stevens Henslow (1796-1861), Cambridge clergyman, botanist and mineralogist.
He became Darwin's scientific mentor when at Cambridge and received and
preserved Darwin's Beagle specimens during the voyage.</p>
</note>
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 (bibliography variant),
entry (glossary variant),
entry (index variant),
entry (toc 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,
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:spacea 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:textareaor 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 can only be used on empty
noteref elements.
- A
noteref element cannot be empty and not include a
value attribute.
- The IDREF(s) in the
ref attribute must resolve to
note elements.
- 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 notes. When a superscripted identifier is used, the
value attribute is required:
<p>THE following pages contain Extracts from LETTERS addressed
to Professor HENSLOW<noteref ref="n2" value="2" /> by C. DARWIN, Esq. … </p>
In the above example, the note identifier (the number 2) 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
noteref becomes the linkable text:
<p>THE following pages contain Extracts from LETTERS addressed
to <noteref ref="n2">Professor HENSLOW</noteref> by C. DARWIN, Esq. … </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>THE following pages contain Extracts from LETTERS addressed
to Professor HENSLOW<noteref ref="n2" /> by C. DARWIN, Esq. … </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>THE following pages contain Extracts from LETTERS addressed
to <noteref ref="n2" value="2">Professor HENSLOW</noteref> by C. DARWIN, Esq. … </p>