![[VIEW OF LC DOME]](http://www.loc.gov/homepage/lc2.gif)
The Library of Congress
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.
<!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 6.5.2.2 and section 6.5.2.4.1, 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.
<dao href="http://sunsite.berkeley.edu/arequipa/page1.gif"> </dao> 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.
<!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"> </dao> 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 address.
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 7.1.2.3). 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"> <did>[...]</did> <admininfo> [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> </accessrestrict> [other possible elements and text...] </admininfo> [other possible elements and text...] <dsc type="combined"> [other possible elements and text...] <c01 level="series"> <did> <unittitle>Series 2: Correspondence</unittitle> [...]</did> <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> </scopecontent> [other possible elements and text...] </c01> [other possible elements and text...] </dsc> </archdesc> 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 ...] <add> <relatedmaterial> <head>Related Collections</head> <archref entityref="tedschell" actuate="user" show="replace"> <origination label="Creator:"> <persname source="lcnaf" role="creator">Schellenberg, T. R., 1903-1970</persname> </origination> <unittitle>Theodore R. Schellenberg Papers, <unitdate type="inclusive">1938-1970</unitdate> </unittitle> <extptr entityref="schellpix" actuate="auto" show="embed"> <unitid type="collection number">MS-045</unitid> <repository><name>Archives R Us</name> </repository> </archref> [other possible elements and text ...] </relatedmaterial> </add> </ead> 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...] </did> <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> <daogrp> <daoloc entityref="f0042_1tmb" actuate="auto" show="embed" role="thumbnail"></daoloc> <daoloc entityref="f0042_1" actuate="user" show="new" role="reference"></daoloc></daogrp></did></c03> <c03 level="item"><did><unittitle>Wedding of John Smith and Stella Jones, Windsor, Ontario, <unitdate type="single" normal="18970606">June 6, 1897</unitdate></unittitle> <daogrp> <daoloc entityref="f0042_2tmb" actuate="auto" show="embed" role="thumbnail"></daoloc> <daoloc entityref="f0042_2" actuate="user" show="new" role="reference"></daoloc> </daogrp></did></c03> [other possible elements and text ...] </c02> [other possible elements and text ...] </c01></dsc> [other possible elements and text ...] </ead> Figure 7.6c.
The Library of Congress