Links In Xml Documents

THL Toolbox > Developers' Zone > Web Development > Xml Markup in THL > Links in XML Documents

Links in THL XML documents

Contributor(s): Than Grove

There are two basic types of links in an XML document. Internal links are links to a section within the same document, much like hash URLs and anchor tags in an HTML document. External links, as the name implies, are links to other, external documents.

Internal Links and Anchors

The two elements used for internal links in THL essays are <ref></ref> and <ptr />. The difference being that the <ref> element can be wrapped around text including other elements, whereas a <ptr /> element has no text within it but points to another location in the same document. The more common of these is the <ref> element. The only attribute that the <ref> element requires is a target attribute which must be set to the ID of another element, most likely a <div>, within the same document. For example,

.... See the section on <ref target="b2">the Dalai Lama</ref>.

where the div for that section has an id of "b2" as in:

<div id="b2">
   <head>The Dalai Lama</head>
....
</div>

This will work for <div>s that are a different section from where the link or <ref> element is. To link to another part of the same section, which appears on the same webpage, the markup is slightly different. To do this one must place an <anchor> tag with a unique ID just above the place where one wants to link to. An example is in Debreczeny article in JIATS 06. In the second section there are links to Figure 4 which is in that same section. To mark these up, an <anchor> tag with an id of "img04" was placed above the <figure> tag thus:

<anchor id="img04" />

And the <ref> links set their target to that same ID, but add a rend attribute equal to "samepage", as in:

<ref target="img04" rend="samepage">Fig. 4</ref>

Finally, if one wants to link to another section in the document and scroll to a specific anchor in that section, such as is done in Debreczeny section 3, one uses the section ID as the target value and the n attribute for the anchor's id, as in this link:

<ref target="b2" n="img04">Fig. 4, no. 14</ref>

The <ptr /> has not been implemented for THL because there has been no call for it.

  • Element: &lt;ref&gt; {text of link} &lt;/xref&gt;
  • Attributes and Values:
    • target: must be the ID value of another element in the same document.
    • rend: for internal links with in the same section that involve only scrolling to the position on the page, use rend="samepage"
    • n: for internal links to different sections from where the <ref> tag is located, use the n attribute to indicate an anchor name to scroll to on the target page.

External Links

External links are marked up using the &lt;xref type="url"&gt; element. In THL essays all external links open up in popup “lightboxes” unless the rend attribute is set to either "_self" or "_top" (to open the content in the same window as the present essay) or "_blank" (to open up the content in a new window). The &lt;xref&gt; element has a doc attribute that is set to the name of a predefined entity, which contains the actual URL for the link. The entities for links are defined in one of two files:

  1. external link: http://texts.thlib.org/essays/external-links.dtd
  2. external link: http://texts.thlib.org/essays/internal-links.dtd

An example entity declaration is:

&lt;!ENTITY dept-ed-us SYSTEM "http://www2.ed.gov/" NDATA HTML &gt;

This defines an entity by the name of "dept-ed-us" to have the value of "http://www2.ed.gov/" which is HTML. The doc attribute of the &lt;xref&gt; element would be then set to "dept-ed-us".

Summary

Below is a summary of the &lt;xref&gt; element:

  • Element: &lt;xref&gt; {text of link} &lt;/xref&gt;
  • Attributes and Values:
    • type: must be "url" for links
    • doc: contains the name of the URL link entity defined in either the external-links.dtd or files-links.dtd files, usually this is a site's home URL.
    • n: contains the internal path within the site that points to the page in question. Thus, to get to the grants page in the U.S. Department of Educations web-site. The doc attribute might be set to "dept-ed-us" which is defined as "http://www2.ed.gov/" and then the n attribute would be set to "fund/grants-apply.html".
    • rend: can contain the same values as the target attribute in an HTML &lt;a&gt; tag – "_blank" (opens in new window), "_top" or "_self" (opens in same window).

Example

<xref doc="moe" n="edoas/website18/en/laws_e.htm" type="url" rend="_blank">external link: http://www.moe.edu.cn/&#x200b;edoas/&#x200b;website18/&#x200b;en/laws_e.htm</xref>

The character entities “&amp;#x200b;” insert a zero-width space. This is used to allow the longer URLs in the text to break and line-wrap.

Provided for unrestricted use by the external link: Tibetan and Himalayan Library