18. linkType

18. linkType
	Chapter 6. Configuration elements

<linkType
  name = NMTOKEN : "default"
>
  Content: [ class ]? | 
           [ link | anchor ]*
</linkType>

<class>
  Content: Java class name
</class>

<link
    match = XPath pattern
    ref = XPath expression
    refs = XPath expression
    href = XPath expression
    hrefs = XPath expression
    excludePath = Regular expression
    includePath = Regular expression
/>

<anchor
    match = XPath pattern
    name = XPath expression
/>

A linkType configuration element allows to define a generalization of the ID/IDREF/IDREFS mechanism for use in modular documents. Some modular documents examples are:

A DocBook book including (by the means of XInclude) chapter documents, each chapter element being found in its own file.
A DITA map referencing a number of topic files.
A set of XHTML pages (e.g. .html and .shtml files) found in the same directory.

Defining a linkType allows to follow a link even when this link points inside another file. See Section 18.1, “Using linkType to implement link navigation”.

Defining a linkType allows to check links even when some of the links point outside the file containing these links. See Section 18.2, “Using linkType to implement link validation”.

A linkType configuration element has a single optional attribute: name. The default value of attribute name is default. Giving a meaningful name to a linkType is useful in 3 cases:

When your configuration file contains several linkType elements. This is rarely needed, but it may happen. See example below.
The name of the linkType is xml:id. This special name means that the anchors defined by this link type are true XML IDs and thus, there is no need to create proprietary XPointers to implement link navigation. These proprietary XPointers are described in Section 18.1, “Using linkType to implement link navigation”.
When you want to allow removing this linkType from the configuration. This is possible because a linkType configuration element without any child element may be used to remove from a configuration a previously defined linkType having the same name.

A linkType configuration element contains either a single class child element or an number of anchor and link child elements:

class

This element contains the fully qualified name of a class which implements interface com.xmlmind.xmleditapp.linktype.LinkType.

An example of such class is com.xmlmind.xmleditapp.IDLinkType, which leverages the standard ID/IDREF/IDREFS mechanism to implement a link type. When no linkType element is found in a configuration file, XXE will behave as if the following one was defined:

<linkType>
  <class>com.xmlmind.xmleditapp.linktype.IDLinkType</class>
</linkType>

anchor

The anchor element is used to detect in a document all the elements which may be used as link targets. This kind of elements is called link target, or more simply anchor. XHTML 1.0 example:

<anchor match="*[@id]" name="@id" />
<anchor match="html:a[@name]" name="@name" />

For a given link type and in a given document, an anchor is uniquely identified by its name. That is, for a given link type and in a given document, it is an error to find several anchors having the same name.

link

The link element is used to detect in a document all elements acting as links pointing to targets. This kind of elements is called link source, or more simply link. XHTML example:

<link match="html:a[@href]" href="@href" />

A link must reference the name of an existing anchor and optionally, depending on the link type, the file containing this existing anchor. That is, it is an error to find a link pointing to an unknown anchor and/or pointing to a non-existent file.

For a given link type, the same element may be at the same time an anchor and also one or more links.

It is also possible to define several link types in the same configuration. Fictitious example:

<linkType>
  <link match="*[@ref]" ref="@ref" />
  <anchor match="*[@id]" name="@id" />
</linkType>

<linkType name="bug">    
  <link match="supportTicket[@bug]" href="@bug" />
  <anchor match="bugReport[@number]" name="@number" />
</linkType>

	The first `linkType` corresponds to general purpose ID/IDREF cross-references.
	The second `linkType` corresponds to specialized cross-references.

Attributes of the anchor child element:

match

Specifies an XPath pattern which is used to detect an element which may be used as a link target.

name

The XPath expression is evaluated in the context of the element matched by attribute match. It returns a string which is the name of the detected anchor.

The name of a anchor is any non-empty string which does not contain whitespace. Special value "-" may be used to ignore the element matched by attribute match.

Attributes of the link child element:

match

Specifies an XPath pattern which is used to detect an element which acts as a link source.

ref, refs, href, hrefs

One of the ref, refs, href, hrefs attributes must be specified. The XPath expression is evaluated in the context of the element matched by attribute match. It returns a string which specifies the target of the link. This string cannot be empty. Special value "-" may be used to ignore the element matched by attribute match.

The string returned by the ref XPath expression is expected to be an anchor name.
The string returned by the refs XPath expression is expected to be one or more anchor names separated by whitespace.
The string returned by the href XPath expression is expected to be an URI. A relative URI is relative to the base URI of the element matched by attribute match. An URI may end with (or may consist in just) a fragment specifying an anchor name. In other words, an URI may end with '#' anchor_name.
The string returned by the hrefs XPath expression is expected to a list of one or more URIs.

excludePath, includePath

These attributes are ignored unless the href attribute has been specified. They allow to make a difference between a link to an external resource and a link to some content found in a peer XML document. Of course, a linkType is about links pointing inside the local document or inside peer XML documents, and not about links to external resources.

The value of these attributes is a regular expression which must match the absolute_or_relative_URI part of the string returned by the href XPath expression.

An href returning an absolute_or_relative_URI which matches the excludePath regular expression is considered to be a link to an external resource and as such, is ignored. Example: ignore all absolute URIs:

excludePath="^[a-zA-Z][a-zA-Z0-9.+-]*:"

An href returning an absolute_or_relative_URI which does not match the includePath regular expression is considered to be a link to an external resource and as such, is ignored. Example: ignore URIs not ending with the .xml, .dbk and .db5 suffixes.

includePath="\.(xml|dbk|db5)$"

The excludePath and includePath attributes are rarely used because they are implicitly defined by XXE as:

Ignore absolute URIs which cannot be made relative to the URI of the document containing the element matched by match. For example, an "http://" URI cannot be made relative to a "file:/" URI, so ignore it.
Ignore URIs which do not have the same file extension as the document containing the element matched by match. For example, a link contained in packaging.dita and pointing to samples/manifest.xml is ignored.

An actual, commented, linkType for DocBook 5:

<linkType>
  <!-- link, xref, biblioref -->
  <link match="*[@linkend]" ref="@linkend" />
  <link match="*[@endterm]" ref="@endterm" />

  <!-- area, co -->
  <link match="*[@linkends]" refs="@linkends" />

  <!-- callout -->
  <link match="*[@arearefs]" refs="@arearefs" />

  <!-- glosssee, glossseealso -->
  <link match="*[@otherterm]" ref="@otherterm" />

  <!-- indexterm -->
  <link match="*[@startref]" ref="@startref" />
  <link match="*[@zone]" refs="@zone" />

  <!-- th, td -->
  <link match="*[@headers]" refs="@headers" />

  <!-- We'll assume that "*[@xlink:href]" is a replacement for 
       ulink and not an alternative to link and xref. -->

  <!-- Allows to use xi:include as a link when the transclusion 
       has been turned off. -->
  <link match="xi:include" href="xincl:toHref(.)" 
        xmlns:xincl="java:com.xmlmind.xml.xinclude.XInclude" />

  <anchor match="*[@xml:id]" name="@xml:id" />
</linkType>

TEI example:

<linkType>
  ...
  <link match="*[@target]" hrefs="@target"/>
  ...
  <link match="*[@spanTo]" href="@spanTo"/>
  ...
  <anchor match="*[@xml:id]" name="@xml:id"/>
</linkType>


17. inclusionScheme		18.1. Using `linkType` to implement link navigation