Merge pull request #168 from music-encoding/revise-chapter-13

Revise chapter 13

_guidelines-v4/13-linkingdata.md

@@ -6,6 +6,4 @@ title: "Linking Data"
 sectionid: "linkingdata"
 ---
 
-{% include version-warning %}
-
-This is a placeholder that needs to be filled.
+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.

_guidelines-v4/13-linkingdata/01-links.md

@@ -0,0 +1,7 @@
+---
+sectionid: links
+title: "Links"
+version: "v4"
+---
+
+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.

_guidelines-v4/13-linkingdata/02-linkfrommei.md

@@ -0,0 +1,9 @@
+---
+layout: sidebar
+sidebar: s1
+version: "v4"
+title: "Linking from MEI"
+sectionid: "linkFromMei"
+---
+
+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.

_guidelines-v4/13-linkingdata/02-ptrref/01-ptrref.md

@@ -0,0 +1,20 @@
+---
+layout: sidebar
+sidebar: s1
+version: "v4"
+title: "Pointers and References"
+sectionid: "ptrRef"
+---
+
+The link elements discussed in this section are the {% include link elem="ptr" %} and the {% include link elem="ref" %} elements which are declared in the `MEI.ptrref` module.
+
+{% include desc elem="ptr" %}
+{% include desc elem="ref" %}
+
+The {% include link elem="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 {% include link elem="ptr" %} element to target a certain identifier (here e.g. a page number, or more precisely, page break elements, {% include link elem="pb" %}, bearing these identifiers) from within a {% include link elem="list" %} of item descriptions:
+
+{% include mei example="ptrRef/ptrRef-sample349.txt" valid="" %}
+
+The {% include link elem="ref" %} element defines a traversible reference to another location. While {% include link elem="ptr" %} cannot contain other markup, the {% include link elem="ref" %} element can include text or sub-elements that further specify the link destination:
+
+{% include mei example="ptrRef/ptrRef-sample351.txt" valid="" %}

_guidelines-v4/13-linkingdata/02-ptrref/02-ptrrefmodule.md

@@ -0,0 +1,44 @@
+---
+sectionid: ptrrefModule
+title: "Specifying Link Elements"
+version: "v4"
+---
+
+The {% include link elem="ptr" %} and {% include link elem="ref" %} elements share a set of common attributes that are inherited from the {% include link att="pointing" %} class (a more detailed explanation is provided below):
+
+{% include desc atts="att.pointing/target" %} 
+{% include desc atts="att.pointing/targettype" %} 
+{% include desc atts="att.pointing/xlink:actuate" %} 
+{% include desc atts="att.pointing/xlink:show" %}
+{% include desc atts=" att.pointing/xlink:role" %}
+
+In addition to the attributes in the {% include link att="pointing" %} class, the **@mimetype** attribute from the {% include link att="internetMedia" %} class is also available on {% include link elem="ptr" %} and {% include link elem="ref" %} (a more detailed explanation is provided below):
+
+{% include desc atts="att.internetMedia/mimetype" %} 
+
+The {% include link att="linking" %} class provides another set of common attributes (a more detailed explanation is provided in {% include link id="analysisharm" %}: {% include link id="analysisDescribingRelationships" %}): 
+
+{% include desc atts="att.linking/copyof" %} 
+{% include desc atts="att.linking/corresp" %} 
+{% include desc atts="att.linking/follows" %} 
+{% include desc atts="att.linking/next" %} 
+{% include desc atts="att.linking/precedes" %} 
+{% include desc atts="att.linking/prev" %} 
+{% include desc atts="att.linking/sameas" %} 
+{% include desc atts="att.linking/synch" %} 
+
+Additionally, the following attributes are also available on {% include link elem="ptr" %} and {% include link elem="ref" %}:
+
+Via the {% include link att="metadataPointing" %} class:
+
+{% include desc atts="att.metadataPointing/decls" %} 
+
+Via the {% include link att="classed" %} class:
+
+{% include desc atts="att.classed/class" %} 
+
+Via the {% include link att="responsibility" %} class:
+
+{% include desc atts="att.responsibility/resp" %} 
+
+

_guidelines-v4/13-linkingdata/02-ptrref/02-ptrrefmodule/01-ptrreftarget.md

@@ -0,0 +1,19 @@
+---
+sectionid: ptrRefTarget
+title: "Define the link element's target (XPointer mechanism)"
+version: "v4"
+---
+
+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/](http://www.w3.org/TR/xptr-framework/){:.link_ref}. 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:
+
+{% include mei example="ptrRef/ptrRef-sample336.txt" valid="" %}
+{% include mei example="ptrRef/ptrRef-sample337.txt" valid="" %}
+{% include mei example="ptrRef/ptrRef-sample338.txt" valid="" %}
+{% include mei example="ptrRef/ptrRef-sample339.txt" valid="" %}
+{% include mei example="ptrRef/ptrRef-sample340.txt" valid="" %}
+
+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.
+
+{% include mei example="ptrRef/ptrRef-sample352.txt" valid="" %}
+
+

_guidelines-v4/13-linkingdata/02-ptrref/02-ptrrefmodule/02-ptrreftargettype.md

@@ -0,0 +1,10 @@
+---
+sectionid: ptrRefTargettype
+title: "Define the type of a link element's target"
+version: "v4"
+---
+
+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:
+
+{% include mei example="ptrRef/ptrRef-sample341.txt" valid="" %}
+{% include mei example="ptrRef/ptrRef-sample342.txt" valid="" %}

_guidelines-v4/13-linkingdata/02-ptrref/02-ptrrefmodule/03-ptrrefmimetype.md

@@ -0,0 +1,19 @@
+---
+sectionid: ptrRefMimetype
+title: "Define the mimetype of a link element's target"
+version: "v4"
+---
+
+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](http://www.ietf.org/rfc/rfc2046.txt){:.link_ref}. The following are all valid mimetype values:
+
+{% include mei example="ptrRef/ptrRef-sample347.txt" valid="feasible" %}
+
+As shown above, the {% include link elem="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 {% include link elem="graphic" %} element provides a convenient and recommended alternative:
+
+{% include mei example="ptrRef/ptrRef-sample350.txt" valid="" %}
+
+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:
+
+{% include mei example="ptrRef/ptrRef-sample348.txt" valid="feasible" %}
+
+