Schema Documentation - DIAGRAM Description Profile
version 1.0

The noteref element

On this page:

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

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: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 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 w
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 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>