Schema Documentation - Generic Document Profile
version 1.0

The ref element

On this page:

The ref element represents a reference to an internal or external entity.

The referenced entity is not required to be resolvable or includable in a processing or rendering context: the ref element may point to conceptual or physical items.

The ref element may employ attributes from the xlink.attrib attributes collection to specify the nature of the hyperlink, including or excluding expressions of link activation behavior.

IDREF link relationships may also be established using the ref attribute, but not in conjunction with the xlink attributes collection.

Usage details available in the Usage Details section.

Usage Example

<index>
    <entry>origin of fruit-trees, <ref ref="page29">29</ref>,  <ref ref="page39">39</ref>.</entry> 
</index>

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

optional attributes: @about, @by, @class, @content, @continuation, @datatype, @desc, @its:dir, @its:translate, @property, @rel, @resource, @rev, @role, @sel:selid, @ssml:onlangfailure, @typeof, @xml:base, @xml:id, @xml:lang and @xml:space
a choice of
either optionally
@xlink:href
an optional @xlink:type
an optional @xlink:title
an optional @xlink:show
an optional @xlink:actuate
or an optional @ref
end of choice
optionally the following 2 co-ocurring attributes: @ssml:alphabet and @ssml:ph
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
Note that in addition to restrictions presented in the content model above, use of this element must also respect the following requirements:
  • The ref element must not contain descendant ref elements.
  • The ref element must neither be empty nor contain only whitespace.
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

The ref element can be used with the ref attribute to link to resources that are contained within the current document. Typical examples of this kind of usage occur in indexes and tables of contents, where the ref element is used to link to a corresponding page number or location: 

<toc>
    <entry>INTRODUCTION <ref ref="p1">Page 1</ref></entry>
</toc>

It is not necessary for the ref element to point to a location, even when used for page references as in the above example (e.g. if alternate methods of linking are expected in outputs). Marking the references without linking them can still be useful for formatting leader lines between the text and reference in a table of contents entry, for example.

Not all references are to internal locations, of course, and the ref elements allows attributes from the XLink feature to be attached instead for such situations: 

<p>For more information, refer to the 
    <ref xlink:href="http://en.wikipedia.org/wiki/Charles_Darwin">wikipedia article on Darwin</ref>.</p>

It is also not necessary for the ref element to point to an electronic resource at all. The element could be used to tag the coordinates of a physical location or object, for example: 

<p>San Cristóbal Island, the first Darwin visited, is located at 
    <ref><num role="coordinate">0°48′S</num> <num class="coordinate">89°24′W</num></ref>.</p>