13. Linking Data

This chapter describes the use of elements in MEI for linking and referencing. This includes the elements, models, and attributes that are part of the MEI.ptrref module. This module contains declarations, techniques and approaches to establish references within a single MEI document, or to link out from one MEI document to another or to other external sources. This chapter also addresses possibilities to link into an MEI document from external sources which makes MEI highly interoperable and serviceable in the context of Linked (Open) Data approaches.

13.1. Links

An element is a ‘link’ when it has an attribute whose value is a reference to the ID of one or more other elements (cross-reference). These link 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 of the elements discussed in the following section can be used for either purpose.

13.2. Linking from MEI

This section describes techniques and approaches to establish references within a single MEI document, or to link out from one MEI document to another or to other external sources.

13.2.1. Pointers and References

The link elements discussed in this section are the ptr and the ref elements which are declared in the MEI.ptrref module.

The ptr element is a traversible pointer to another location. It is an empty linking element that uses only attributes to describe its link destination. It cannot contain text or sub-elements to describe the referenced object. The next example shows the use of the ptr element to target a certain identifier (here e.g. a page number, or more precisely, page break elements, pb, bearing these identifiers) from within a list of item descriptions:

<list>
  <li>
    <!-- item description -->
    <ptr target="#p123"/>
  </li>
  <li>
    <!-- item description -->
    <ptr target="#p124"/>
  </li>
</list>

The ref element defines a traversible reference to another location. While ptr cannot contain other markup, the ref element can include text or sub-elements that further specify the link destination:

<repository>
  <ref target="http://path.to.target/repo1.xml">
    <title>…</title>
    <address>
      <addrLine>…</addrLine>
    </address>
    <identifier>…</identifier>
  </ref>
</repository>

13.2.2. Specifying Link Elements

The ptr and ref elements share a set of common attributes that are inherited from the att.pointing class (a more detailed explanation is provided below):

In addition to the attributes in the att.pointing class, the @mimetype attribute from the att.internetMedia class is also available on ptr and ref (a more detailed explanation is provided below):

The att.linking class provides another set of common attributes (a more detailed explanation is provided in Analysis Markup and Harmonies: General Relationships Between Elements):

Additionally, the following attributes are also available on ptr and ref:

Via the att.metadataPointing class:

Via the att.classed class:

Via the att.responsibility class:

13.2.2.1. Define the link element’s target (XPointer mechanism)

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"/>

<!-- relative URL -->
<ptr target="myFile.xml"/>

<!-- absolute URL -->
<ptr target="http://www.w3.org/TR/xptr-framework/"/>

<!-- URL with fragment identifier -->
<ptr target="http://www.w3.org/TR/xptr-xpointer/#xpointer(id('chum')/quote)"/>

<!-- URN -->
<ref target="urn:isan:0000-0000-9E59-0000-O-0000-0000-2">Spider-Man</ref>

A @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>

13.2.2.2. Define the type of a link element’s target

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 pointers in the examples 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 target="http://path.to.resource/myAudio.aiff" targettype="audioClip"/>

13.2.2.3. Define the mimetype of a link element’s target

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 as defined by the Internet Engineering Task Force (IETF) 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 mimetype="text/xml" target="my.xml"/>
<ptr mimetype="image/png" target="my.png"/>

As shown above, the ptr element can be used to ‘point to’ a digital image (target="my.png"). 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="my.png"/>

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 mimetype="application/x-myApplicationSpecificFile" target="myFile2"/>

13.2.2.4. Determine the link element’s behaviour

The @xlink:actuate and @xlink:show attributes are used in conjunction to determine the link’s behavior.

The @xlink:actuate attribute 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(s) immediately

‘onRequest’: load the target resource(s) upon user request, e.g., after a mouse click

‘none’: do not permit loading of the target resource(s); no other markup is provided to determine appropriate behavior

‘other’: behavior other than permitted by the other values of this attribute; application should look for other markup to determine appropriate behavior

The value “none” may be used to indicate that the link is un-traversable and no other markup is provided to determine appropriate behavior; 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 @xlink: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 in the same window

‘embed’: the content of the target appears at the point of the link

‘none’: do not permit traversal to the target resource(s); no other markup is provided to determine appropriate behavior

‘other’: behavior other than permitted by the other values of this attribute; application should look for other markup to determine appropriate behavior

The value “none” may be used to indicate a link that is not displayed or is not displayable and 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 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"/>

13.2.2.5. Determine the link element’s role

The @xlink:role attribute describes the meaning of resources within the context of a link. It is used to label or describe a link or resource in a human- and machine-readable fashion. The value of @xlink:role must be an absolute URI (Uniform Resource Identifier) reference as defined by the Internet Engineering Task Force (IETF) in 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" />

<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" />

In the preceding examples, the value of the @xlink:role attribute may be used to specify the value of the link target’s role.

13.3. Linking and Alignment

The linkAlign module has been deprecated in MEI v3.