EAD Application Guidelines for Version 1.0

Chapter 7: EAD Linking Elements

7.5. Managing External Links(123)

Although EAD may seem at first glance to offer a bewildering array of choices for establishing and managing links, you will likely select a standardized method from among these choices, based largely on the constraints or opportunities offered by the particular system or systems in which you will author and publish EAD-encoded finding aids. Once these choices have been made and documented, encoders will not have to wrestle with choices for each link they want to establish. Do not underestimate the importance of establishing guidelines and documentation for linking within your institutional or collaborative project! Establishing such standards early and rigorously enforcing them in the encoding process will make it much easier in the future to move encoded finding aids and to enhance them for new delivery systems as these inevitably increase in functionality and decrease in both cost and implementation difficulty.

Internal links within any document instance are by their nature fairly simple and do not require any conscious management beyond making certain that your ID and TARGET attributes match up, something a final validating parse of the EAD instance will confirm. This section focuses solely on decisions that must be made about encoding destination addresses for external links and, indirectly, implications for managing the files to which they point.

When processing links from your finding aids to external resources such as text or image files like those shown in Figures 7.3.4a and 7.4.1c, your SGML application needs to know the following two things:

The latter is a particularly vexing problem since file locations tend to change as servers are replaced or directory structures reconfigured. Ensuring that such links remain current and accurate over time is a continuing maintenance issue, one that increases as you add more and more of them to your encoded finding aids.

The remainder of this section concentrates on options available for addressing EAD links to external files generally, but emphasizing those residing on your own server(s). There are two broadly categorized options available: use the ENTITYREF attribute or use the HREF attribute.

The strengths and weaknesses of each will be considered. Neither of these options is absolutely correct or incorrect, so these Guidelines will not make a final recommendation one way or the other. The decision as to which method to use must be made within the context of your own local administrative and technical realities.

7.5.1. Using ENTITYREF

Declaring external files as entities using a formal public identifier (FPI)(124) and then using the ENTITYREF attribute to provide the name of a declared entity as a destination for a link, as illustrated in figure 7.5.1a, is perhaps the most widely employed and technically elegant link management strategy used in SGML-based systems.

	<!ENTITY pageimage1 PUBLIC "-//University of California, Berkeley::
	Bancroft Library//TEXT (US::CU-BANC::BANC MSS 92/894c::The Arequipa Sanatorium
	Records::Letter page image 1)" NDATA gif>

	<dao entityref="pageimage1"></dao>

	Figure 7.5.1a.  An entity declaration using only a public identifier
	(in this case, an FPI), followed by an entity reference to the declared entity.

In this method, the ENTITYREF attribute in the linking element specifies the location of the resource indirectly, through an entity name, rather than by specifying an absolute computer address such as a URL. This approach has distinct advantages. Declaring an entity using an FPI allows you to use a separate file, such as an SGML catalog file or a handle server(125), to provide an appropriate address or location for the resource based on the type of processing application. These tools serve as roadmaps between entity names (which can be referenced easily from any point within an encoded document instance) and the address or physical location of the resources to which those entity names refer. When the physical locations of resources change over time, only the SGML catalog file needs to be modified; the individual EAD instances containing stable entity names that reference the SGML catalog file need not be edited.

There are technical disadvantages to this approach. Web browsers that support XML and the use of XSL or CSS stylesheets are unable to access and resolve such entity names into explicit resource addresses such as URLs. It would require specialized programming to create workarounds for this problem. In addition, the overhead of supplying a well-formed FPI (as specified by the ISO 9070 standard) for each digital resource is not insignificant.

For systems that do not support the use of FPIs and catalog files, a system identifier may be specified in an entity declaration in addition to or instead of an FPI, as illustrated in figure 7.5.1b. As discussed in section and section, a system identifier provides a direct address, in the form of a URI, in the entity declaration.

	<!ENTITY pageimage1 PUBLIC "-//University of California, Berkeley::
	Bancroft Library//TEXT (US::CU-BANC::BANC MSS 92/894c::The Arequipa Sanatorium
	Records::Letter page image 1)" "http://sunsite.berkeley.edu/arequipa/page1.gif"
	NDATA gif>

	<dao entityref="pageimage1"></dao>

	Figure 7.5.1b.  An entity declaration using both a public identifier
	and a system identifier (in this case an absolute URL), followed by an entity
	reference to the declared entity.

This combined approach provides an explicit resource address in the entity declaration, but still relies on the use of a delivery application that can access that resource address indirectly from its location in an entity declaration at the beginning of a document instance. For this reason, it will not work with current XML applications that are Web browser based and use XSL or CSS stylesheets to render their display, though this may change as XSL and XSL applications mature.

Additionally, the use of system identifiers in entity declarations may require that individual EAD-encoded files be edited whenever the server location of a particular resource changes, obviating the benefits of using entities to provide indirect file addresses in finding aids. This potential drawback may be mitigated through the use of the search-and-replace capabilities of most standard text editors and also by careful planning of the directory structures you create on the server(s) on which your files are stored.

7.5.2. Using HREF

Using the HREF attribute directly at the source of each link to establish a destination address, as illustrated in figure 7.5.2a, eliminates the indirection of the ENTITYREF approach that may be problematic for some applications. Currently and freely available Web browser technology can readily deal with links encoded using this option. Encoding is far easier, particularly for those repositories with little technical expertise or limited resources who may be going it alone in their implementation of EAD. No SGML catalog file is required with this option. If the location of any destination resource changes, linking elements throughout individual finding aid instances must be edited, though this may be easily accomplished using a global search-and-replace operation within a repository's encoded finding aids. Finally, encoders who have experience with HTML certainly will find the HREF notation easier to read and use.

	<dao href="http://sunsite.berkeley.edu/arequipa/page1.gif">

	Figure 7.5.2a.  An external link established without the
	use of entity declarations by the direct use of the HREF attribute
	(in this case using an absolute URL).

While all these plusses may make this seem an obvious choice, there are definite drawbacks. Certainly keeping references to file location current will be a major maintenance issue, as it is with all Web applications. This process can be supported by the use of any of a number of tools currently available to Web managers that search out and report broken links. The maintenance of local files can be expedited further if only the file name itself ("page1.gif") is embedded in the HREF attribute, with the balance of file path ("http://sunsite.berkeley.edu/ arequipa/") being specified in a stylesheet. Finally, it must be noted that this option presents major challenges for finding aid interchangeability and the implementation of union databases of finding aids because of the problems associated with maintaining location information for external resources.

When using HREF, it is not sufficient simply to specify a URL or system identifier. The processing application needs additional direction as to how to display the resource. Is the image to be inserted into the finding aid at the point where the link occurs or is there to be a hyperlink to an external text file, such an entry in an electronic biographical dictionary? Unless a default option applies to all links, the type of display needs to be specified through the use of the SHOW and ACTUATE attributes.

7.5.3. Combining Both Approaches

This option combines the entity-based and HREF-based approaches to encoding URLs for external digital resources. Although this approach presents both addressing options and allows a processing application to determine which to use, it should be noted that including both has caused indexing problems for some SGML-based systems. This method creates an obvious redundancy in the duplication of URLs in both the entity declaration and at the point of the link itself, which would certainly increase both the amount of work in encoding each finding aid and the complexity in editing that would be required when URLs change. Nonetheless, in terms of interchange and in view of the current rapid pace of change in information management and delivery technologies, this may be the most flexible option. The provision of a URL in both the entity declaration and the linking element itself should ideally allow most application software to process whichever resource address it can and ignore the others.

	<!ENTITY pageimage1 PUBLIC "-//University of California, Berkeley::
	Bancroft Library//TEXT (US::CU-BANC::BANC MSS 92/894c::The Arequipa Sanatorium
	Records::Letter page image 1)" "http://sunsite.berkeley.edu/arequipa/page1.gif"
	NDATA gif>

	<dao entityref="pageimage1" href="http://sunsite.berkeley.edu/arequipa/page1.gif">

	Figure 7.5.3a. An entity declaration using both a Public Identifier
	and a System Identifier (in this case an absolute URL), followed by a link that
	includes an entity reference to the declared entity as well as a hard-coded HREF

7.6. Examples of Optimally Encoded Linking Elements

The following examples illustrate optimal encoding of EAD links, both internal and external. How do we define the term "optimal?" For the purposes of these Guidelines the term "optimal" means the minimum amount of information about a link that would be required for the link to function effectively in most encoded finding aid publishing systems. The requirements for optimal encoding of links in EAD are really quite simple. Each link must be supplied with two things:

Your choices are limited for meeting both of these requirements, which should make it easy to optimally encode links in your EAD documents. For internal links there is only one option for the first requirement: use TARGET. For external links there are three options for the first requirement: use ENTITYREF, use HREF, or use both. Refer to section 7.5 for more information about the issues involved in making this choice. The second requirement is equally easily met by using both the ACTUATE and SHOW attributes in all of your encoded links. Together these two attributes provide a minimum amount of information about how you intend the links to behave in whatever system will be processing them for presentation to an end user. While not recommended in all cases, the ROLE attribute, as demonstrated in figure 7.4.2a, may be useful to indicate unambiguously to application software the role of each link bundled together using one of the extended linking elements <daogrp> or <linkgrp> (in other words, bundling "thumbnail" and "reference" copies of the same image). Although at present most commercially available software cannot utilize the link behavior attributes ACTUATE, SHOW, and ROLE, it is nonetheless a good idea to supply this information when establishing links in your encoded finding aids.

While these Guidelines provide information on optimal encoding for linking attributes, they cannot do the same for questions such as when to establish links and how many links to establish. These questions must be answered locally based on the capability of the application software you are using to publish your encoded finding aids and the goals that your repository and funding sources have set for your encoding project. It is important, however, if you are establishing links within your EAD-encoded finding aids, that you do create local guidelines that address these questions, that documentation of the guidelines is readily available to all participants in your local project, and that you enforce the guidelines consistently across the body of encoded finding aids that your project creates over time. In the long run, consistency, standardization, and documentation will make the management of your investment in encoded data describing your archival collections simpler and will increase the ease with which you will be able to take advantage of the inevitable advances in hardware and software technology for the manipulation and delivery of that descriptive data in the future.

The examples below are drawn from other illustrations previously used in this chapter. All links established in these examples are inline (see section The INLINE attribute is not used, since its default value is set by the EAD DTD as "true". Use of the INLINE attribute would not make these examples any less illustrative of optimal encoding.

The illustration in figure 7.6a uses a simple internal link to allow users to check the text of an access restriction statement encoded at the collection level from a point in the component description where the restriction is applicable. Note that the use of the value "new" for the attribute SHOW should open a new window for the text of the access restriction rather than disorienting the user by replacing their current location within the finding aid, which would be the result if the value "replace" was used. Because <ref> was used, application software will likely highlight the text included between <ref> and </ref> to indicate to end users that a link is available.

	<archdesc level="collection" langmaterial="eng" type="inventory">
		[other possible elements and text...]
	<accessrestrict id="restrict1">
	<head>Access Restrictions</head>
	<p>This collection is open for research to all researchers with the following exception: Series 2 (Correspondence) contains 15 folders of student recommendations that are closed for 75 years under the jurisdiction of the state Student Records Act (1968:042). The first of these folders will be available to researchers on 1 January 2035 and the last on 1 January 2047.</p>
		[other possible elements and text...]
		[other possible elements and text...]
	<dsc type="combined">
		 [other possible elements and text...]
	<c01 level="series">
	<unittitle>Series 2: Correspondence</unittitle>
	<scopecontent><p>The Correspondence Series contains ...</p>
	<arrangement><p>The bulk of the contents of the series arrived at
	the repository in chronological order and this arrangement has been retained.
	<ref target="restrict1" actuate="user" show="new">The single
	exception is a file of student recommendations on which access restrictions
	have been imposed.</ref> These folders have been temporarily removed to a
	restricted box in the collection.</p></arrangement>
		[other possible elements and text...]
		[other possible elements and text...]

	Figure 7.6a.

The illustration in figure 7.6b uses an external linking element specifically intended to create links to other archival collections in order to give users access to the finding aid for a related collection of personal papers available at another repository. It also uses a simple external link to insert an illustrative image of the creator of that external set of papers. Because of the attribute values assigned, the text of the reference should be highlighted to alert the end user of the existence of a link, while the image should appear automatically in the text of the reference after the title of the related collection.

	<!DOCTYPE  ead  PUBLIC  "-//Society of American Archivists//DTD ead.dtd
	(Encoded Archival Description (EAD) Version 1.0)//EN"  [
	<!ENTITY  tedschell  SYSTEM  "http://www.archivesrus.gov/
	findaids/ead/ms045.sgm" NDATA sgml>
	<!ENTITY  schellpix  SYSTEM  "http://www.myserver.org/images/
	ms023_schell.gif"  NDATA  gif>
	<ead audience="external">
		[other possible elements and text ...]
	<head>Related Collections</head>
	<archref entityref="tedschell" actuate="user" show="replace">
	<origination label="Creator:">
	<persname source="lcnaf" role="creator">Schellenberg, T. R.,
	<unittitle>Theodore R. Schellenberg Papers,
	<unitdate type="inclusive">1938-1970</unitdate>
	<extptr entityref="schellpix" actuate="auto" show="embed">
	<unitid type="collection number">MS-045</unitid>
	<repository><name>Archives R Us</name>
		 [other possible elements and text ...]

	Figure 7.6b.

Figure 7.6c illustrates the use of <daogrp> to bundle pairs of thumbnail and reference images for each item. The encoding of the attributes ACTUATE and SHOW in this example would most likely result in the thumbnail image being automatically embedded in the text of the finding aid after the <unittitle> for each item, while the larger reference image would appear in a new browser window when the user activated the link traversal.

	<!DOCTYPE  ead  PUBLIC  "-//Society of American Archivists//DTD ead.dtd (Encoded Archival Description (EAD) Version 1.0)//EN"  [
	<!ENTITY  f0042_1  SYSTEM  "../images/fonds0042_image1.jpg" NDATA jpeg>
	<!ENTITY  f0042_2  SYSTEM  "../images/fonds0042_image2.jpg" NDATA jpeg>
	<!ENTITY  f0042_1tmb  SYSTEM  "../images/fonds0042_image1_thumb.jpg" NDATA jpeg>
	<!ENTITY  f0042_2tmb  SYSTEM  "../images/fonds0042_image2_thumb.jpg" NDATA jpeg>
	<ead audience="external">
		[other possible elements and text ...]
	<dsc type="combined">
		[other possible elements and text ...]
	<c01 level="series"><did> <unittitle>Series 3: Biographical Information </unittitle>
		[other possible elements and text...]
	<c02 level="file"><did><unittitle>Photographs,
	<unitdate type="inclusive">1895-1928</unitdate></unittitle>
	<physdesc><extent>5 items</extent></physdesc></did>
	<c03 level="item"><did><unittitle>John Smith graduation portrait,
	<unitdate type="single" normal="18950528">May 28, 1895</unitdate></unittitle>
	<daoloc entityref="f0042_1tmb" actuate="auto" show="embed"
	<daoloc entityref="f0042_1" actuate="user" show="new"
	<c03 level="item"><did><unittitle>Wedding of John Smith
	and Stella Jones, Windsor, Ontario, <unitdate type="single"
	normal="18970606">June 6, 1897</unitdate></unittitle>
	<daoloc entityref="f0042_2tmb" actuate="auto" show="embed"
	<daoloc entityref="f0042_2" actuate="user" show="new"
		[other possible elements and text ...]
		[other possible elements and text ...]
		[other possible elements and text ...]
	Figure 7.6c.


Main Menu


  1. The text of this section is loosely based, with his permission, on an unpublished discussion paper on external linking options prepared by Alvin Pollock, Electronic Text Unit, University of California, Berkeley.

  2. See section and section for more information on public identifiers.

  3. See section for more information on SGML catalog files and section 5.4 for more information on handle servers.

Table of Contents
Home Page Preface Acknowledgments How to Use
This Manual
Setting EAD
in Context
Creating Finding
Aids in EAD
Authoring EAD
Publishing EAD
EAD Linking

Go to:

Copyright Society of American Archivists, 1999.
All Rights Reserved.

[VIEW OF LC DOME] The Library of Congress

Library of Congress Help Desk (11/01/00)