19.1. Links 19.1.1. Difference between Pointers and References
This chapter describes the use of elements for linking and referencing.
An element is a ‘link’ when it has an attribute whose value is a reference to the ID of one or more other elements. The links discussed in this chapter are the ptr and the ref elements. These elements indicate an association between themselves (or one of their ancestors) and one or more other entities, either inside the same document or elsewhere. An association between two elements in the same document is said to be an ‘internal’ link, while an association that involves an entity outside the current document is called an ‘external’ link. However, either element can be used for either purpose.
The two elements share a set of common attributes that are inherited from the att.pointing class:
@target: allows the use of one or more previously-undeclared URIs to identify an external electronic object.
@targettype: in contrast with the role attribute, allows the target resource to be characterized using any convenient classification scheme or typology.
@xlink:actuate: defines whether a link occurs automatically or must be requested by the user.
@xlink:show: defines how a remote resource is rendered.
@xlink:title: contains a human-readable description of the entire link.
@xlink:role: indicates a property of the entire link. The value of the role attribute must be a URI.
The @target attribute specifies the destination of a pointer or reference using a method standardized by the W3C consortium, known as the XPointer mechanism. The XPointer framework is described at http://www.w3.org/TR/xptr-framework/. This mechanism permits a range of complexity, from the very simple (a reference to the value of the target element’s @xml:id attribute) to the more complex usage of a full URI with embedded XPointers:
<!-- element ID --><ptr target="#SA"></ptr>
<!-- relative URL -->
<ptr target="myFile.xml"></ptr>
<!-- absolute URL -->
<ptr target="http://www.w3.org/TR/xptr-framework/"></ptr>
<!-- URL with fragment identifier -->
<ptr target="http://www.w3.org/TR/xptr-xpointer/#xpointer(id('chum')/quote)"></ptr>
<!-- URN -->
<ref target="urn:isan:0000-0000-9E59-0000-O-0000-0000-2">Spider-Man</ref>The @targettype attribute allows the target resource to be characterized using any convenient classification scheme or typology. This is often useful when the target requires special processing, e.g., for display purposes. The two pointers in the example below may be formatted differently, e.g., the bibliographic citation may result in special typography while the pointer to the audio file may be used to embed an audio player:
<ptr target="#cit1" targettype="biblioCitation"></ptr>
<ptr target="http://path.to.resource/myAudio.aiff" targettype="audioClip"></ptr>The @xlink:actuate and @xlink:show attributes are used in conjunction to determine the link’s behavior. The attribute @xlink:actuate defines whether the resolution of a link occurs automatically or must be requested by the user.
The following values are allowed for the @xlink:actuate attribute:
‘onLoad’: load the target resource immediately
‘onRequest’: load the target resource upon user request, e.g., after a mouse click
‘other’: traversal behavior is unconstrained; application should look for other markup to determine appropriate behavior
‘none’: traversal behavior is unconstrained; no other markup is provided to determine appropriate behavior
The value “none” may be used to indicate that the link is un-traversable; it may or may not render the link invisible to the user. When the value of @xlink:actuate is “other”, an application must base a determination of appropriate behavior on factors other than the value of @xlink:actuate.
The @show attribute defines how a remote resource is to be rendered. The following values are permitted:
‘new’: target of the link appears in a new window
‘replace’: target of the link replaces the current resource
‘embed’: the content of the target appears at the point of the link
‘other’: traversal behavior is unconstrained; application should look for other markup to determine appropriate behavior
‘none’: traversal behavior is unconstrained; no other markup is provided to determine appropriate behavior
When the value of @xlink:show is “other”, an application must base a determination of appropriate behavior on factors other than the value of @xlink:show. The value “none” may be used to indicate a link that is not displayed or is not displayable.
The following example illustrates a pointer that results in the automatic creation of a new window with the content of the target loaded in it:
<ptr xmlns="http://www.tei-c.org/ns/Examples" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:rng="http://relaxng.org/ns/structure/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" mimetype="text" target="http://www.ietf.org/rfc/rfc2046.txt" xlink:actuate="onLoad" xlink:show="new"></ptr>The @xlink:title and @xlink:role attributes describe the meaning of resources within the context of a link. The @xlink:title attribute is used to label or describe a link or resource in a human-readable fashion. The value here is highly dependent on the kind of processing being done. It may be used, for example, to make link titles available to applications used by visually impaired users, or to create a table of links, or to present help text that appears when a user’s mouse hovers over the link.
<ptr xmlns="http://www.tei-c.org/ns/Examples" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:rng="http://relaxng.org/ns/structure/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" target="http://www.music-encoding.org" xlink:title="hompage of the MEI Project"></ptr>The attribute@ xlink:role serves a similar function to that of @xlink:title. Whereas the value of @xlink:title may be any string, the value of @xlink:role must be an absolute URI reference as defined in IETF RFC 3986, available at http://tools.ietf.org/html/rfc3986. The URI reference identifies a resource that describes the intended property. When no value is supplied, no particular role value is to be inferred.
<ptr xmlns="http://www.tei-c.org/ns/Examples" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:rng="http://relaxng.org/ns/structure/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" target="joe.xml" xlink:role="http://www.example.com/linkprops/student" xlink:title="Click here"></ptr>
<ptr xmlns="http://www.tei-c.org/ns/Examples" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:rng="http://relaxng.org/ns/structure/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" target="joe.xml" xlink:role="http://www.example.com/linkprops/instructor" xlink:title="Click here"></ptr>In the preceding example, the value of the @xlink:role attribute may be used to re-write the value of @xlink:title, depending on the target resource role.
In addition to the attributes in the att.pointing class, the @mimetype attribute is also available on ptr and ref. The function of the @mimetype attribute is similar to that of @targettype in that they both allow classification of the destination. Unlike @targettype, however, @mimetype explicitly defines the destination type using a standard taxonomy. Its value should be a valid MIME (Multimedia Internet Mail Extension) type defined by the Internet Engineering Task Force in RFC 2046, available at http://www.ietf.org/rfc/rfc2046.txt. The following are all valid mimetype values:
<ptr mimetype="application/pdf" target="my.pdf"></ptr>
<ptr mimetype="text/xml" target="my.xml"></ptr>
<ptr mimetype="image/png" target="my.png"></ptr>The @mimetype attribute is particularly useful for documenting the nature of the destination when the value of @target does not provide a filename extension or when the destination is a non-standard file type:
<ptr mimetype="application/pdf" target="myFile1"></ptr>
<ptr mimetype="application/x-myApplicationSpecificFile" target="myFile2"></ptr>The ptr element is an empty linking element that uses only attributes to provide for movement from one place to another. Unlike the ref element, it cannot contain text or sub-elements to describe the referenced object. Its primary function is simply to point to another location. The next example shows targets that are page numbers; or more precisely, the targets are page break elements bearing these identifiers:
<list>
<li>
<!-- item description -->
<ptr target="#p123"></ptr>
</li>
<li>
<!-- item description -->
<ptr target="#p124"></ptr>
</li>
</list>As shown above, the ptr element can be used to ‘point to’ a digital image. However, when the intention is to display a digital image as part of the rendering of an MEI file, the graphic element provides a convenient and recommended alternative:
<graphic mimetype="image/png" target="myPic.png"></graphic>While ptr cannot contain other markup, the ref element can include text and sub-elements that name or describe the destination:
<repository>
<ref target="http://path.to.target/repo1.xml">
<title>...</title>
<address>
<addrLine></addrLine>
</address>
<identifier>...</identifier>
</ref>
</repository>The @target attribute is not required in order to mark the textual content as a cross-reference, as demonstrated in the example below; however, without this attribute the reference will not be resolvable.
<p>See
<ref>Hankinson, Roland, Fujinaga (2011)</ref>.
</p>