• Archival Finding Aids
• Best Practices at LC

Related Resources

• The EAD Standard
• SAA EAD Help Pages
• LC EAD Finding Aids (XML)

2.2 Linking Elements

2.2 SECTIONS: Internal Linking | External Linking

Description:

There are seventeen elements in EAD that can be used to establish links: fifteen manage links directly, while two (<daogrp> and <linkgrp>) are wrapper elements that consolidate multiple, related links. Linking elements are discussed here under the general categories of internal links (within the EAD document) and external links (to other documents).

See Also:

Section 2.2.1, Internal Linking Go to Section

Section 2.2.2, External Linking Go to Section

Subelements:

• <arc> See 2.2.1 Internal Linking and 2.2.2, External Linking
• <archref> See 2.2.2, External Linking
• <bibref> See 2.2.2, External Linking
• <dao> See 2.2.2, External Linking
• <daogrp> See 2.2.2, External Linking
• <daoloc> See 2.2.2, External Linking
• <extptr> See 2.2.2, External Linking
• <extptrloc> See 2.2.2, External Linking
• <extref> See 2.2.2, External Linking
• <extrefloc> See 2.2.2, External Linking
• <linkgrp> See 2.2.1, Internal Linking
• <ptr> See 2.2.1, Internal Linking
• <ptrloc> See 2.2.1, Internal Linking
• <ref> See 2.2.1, Internal Linking
• <refloc> See 2.2.1, Internal Linking
• <resource> See 2.2.1 Internal Linking and 2.2.2, External Linking
• <title> See 2.2.2, External Linking

Comments:

• Extensive information about linking can be found in Chapter 7 of the EAD Application Guidelines. Remember to check the EAD 2002 Tag Library for current values of attributes.

Revision Date: 05/01/08

 Back to Top

---

2.2.1 Internal Linking

Description:

Internal linking enhances the ability to navigate a finding aid via explicit links between related information appearing in different places in the finding aid. Extensive information about linking can be found in Chapter 7 of the EAD Application Guidelines.

LC Practice requires the use of the TARGET, ACTUATE, and SHOW attributes with internal linking elements, and recommends the use of <ref> over <ptr> for internal linking.

See Also:

Section 3.3.8.3, Indexes Go to Section

Section 2.2.2, External Linking Go to Section

Other Attributes:

• target (value of id assigned to target of link) Required
• actuate="onrequest" (means user needs to click on link for target to be displayed) Required
• show="replace" (target is displayed in place of the text just viewed) Required

See Tag Library for full list of attributes and their values.

Subelements:

Simple linking within the finding aid:

• <ref> (links with text)
• <ptr> (empty links--no text) may be bundled using <ptrgrp>

Additionally, <indexentry> may be used within the index to bundle <ref>, <ptr>, or <ptrgrp>.

Extended linking within the finding aid (must be bundled using <linkgrp>)

• <arc> (rules for traversal among resources in extended link)
• <refloc> (locator links with text)
• <ptrloc> (empty locator links--no text)
• <resource> (local resource participating in extended link)

Tagging Example 1:

Cross-reference from Hart linked to target (Rodgers)

Display Of Tagging Example 1:

Cross-reference from Hart linked to target (Rodgers)

Box 135     Hart, Lorenz See Container 176, Rodgers, Richard

Box 176     Rodgers, Richard, and Lorenz Hart, I Married an Angel, [1938] 

Comments:

• All links must have targets. Set the TARGET attribute for a reference with a brief unique alpha or alphanumeric identifier for the object of the link; id's must begin with an alphabetic character. For example, a container list cross reference, "See Container 17, Smith, Anna" might have attribute target="smith17". To make the link work, set the attribute id="smith17" for the <unittitle> in Container 17 to which the link should go. See Example 1.
• See Section 3.3.8.3 for a discussion of <ptrgrp>, <ptr>, and <ref> in relation to indexes.
• See the Application Guidelines, 7.2.3 for an explanation of the extended linking and elements <refloc> and <ptrloc>. Remember to check the EAD 2002 Tag Library for new elements <arc> and <resource>, and for current values of attributes for linking elements.

Revision Date: 1/26/08

 Back to Top

---

2.2.2 External Linking

Description:

External linking refers to links from a finding aid to another electronic resource, which may be another encoded finding aid, a digital archival object (<dao>), an external image or file not from the archival collection (e.g., the LC seal or an illustration), or a web page. Extensive information about linking can be found in Chapter 7 of the EAD Application Guidelines.

LC Practice requires the use of the HREF, ACTUATE, and SHOW attributes with external linking elements.

See Also:

Section 2.1.2, Paragraph (use of linking elements within) Go to Section

Section 2.2.1, Internal Linking Go to Section

Section 3.1.2, File Description (<extptr> to LC seal) Go to Section

Section 3.3.1.11, Digital Archival Object Group Go to Section

Section 3.3.3.8, Alternate Form of the Materials Available (examples of <extref> to URLs, discussion of <daogrp>) Go to Section

Section 3.3.7.4, Expanded Description of Components (<daogrp> at component level) Go to Section

Section 3.3.8.1, Bibliographies (<bibref> and <archref> as linking elements) Go to Section

Section 3.3.8.5, Related Material (<bibref> and <archref> as linking elements) Go to Section

Section 3.3.8.6, Separated Material (<bibref> and <archref> as linking elements) Go to Section

Other Attributes:

Simple linking:

• href (target of link) Required
• actuate="onrequest" (means user needs to click on link for target to be displayed) or "onload" (means target displayed automatically, e.g., LC seal) Required
• show="new" (target resource displayed in a new browser window) or "embed" (target resource displayed at point of link) Required

See Tag Library for full list of attributes and their values.

Extended linking (<daoloc>):

• href (target of link) Required
• role (MIME type of target)

See Tag Library for full list of valid attributes and their values for this and for other extended linking elements.

Subelements:

Simple linking:

• use <extptr> for the LC seal (in <eadheader>) or any illustrative matter which should be displayed inline and is not from the collection described
• use <extref> for external links such as to a Library web page
• use <archref> to link to other archival collections. For instance, this may be another finding aid (preferably EAD), or to a web page, database, or catalog record for the archival collection.
• use <bibref> to link from a bibliographic citation to an online version of the work
• use <title> to link to a title to an online version of the work

Extended linking:

• use <arc> to specify rules for traversal among resources in an extended link
• use <daoloc> for an object within <daogrp>. <daogrp> is used as a wrapper for one or more archival objects.
• rather than using <dao> for a single archival object, use <daoloc> within <daogrp> instead..
• use <extrefloc> for external reference extended references
• use <extptrloc> for external pointer extended references
• use <resource> to specify local resources participating in an extended link

Tagging Example 1a:

XML prolog with entity declarations, linking elements for Hannah Arendt Papers

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE ead PUBLIC "+//ISBN 1-931666-00-8//DTD ead.dtd (Encoded Archival Description
(EAD) Version 2002)//EN" "http://lcweb2.loc.gov/xmlcommon/dtds/ead2002/ead.dtd" 

[
<!ENTITY arendthome "http://memory.loc.gov/ammem/arendthtml/">
<!ENTITY eadmss.mhafol02 "http://memory.loc.gov/ammem/arendthtml/mharendtFolderP02.html">
<!ENTITY eadmss.mhafol03 "http://memory.loc.gov/ammem/arendthtml/mharendtFolderP03.html">
<!ENTITY lcseal SYSTEM "http://lcweb2.loc.gov/xmlcommon/lcseal.jpg" NDATA jpeg>
]>

<ead>[Beginning of EAD finding aid]</ead>

Tagging Example 1b:

<daoloc> has href value as an entity declared in prolog for Arendt

Display Of Tagging Example 1b:

<daoloc> link goes to American Memory presentation of series contents

Correspondence, 1938-1976
   Items available online.

Tagging Example 2a:

XML prolog with entity declarations and link to external "bell.ent" entity file for Bell papers

<?xml version="1.0" encoding="utf-8">
<!DOCTYPE ead PUBLIC "+//ISBN 1-931666-00-8//DTD ead.dtd (Encoded Archival Description
(EAD) Version 2002)//EN" "http://lcweb2.loc.gov/xmlcommon/dtds/ead2002/ead.dtd"
[

<!ENTITY lcseal SYSTEM "http://lcweb2.loc.gov/xmlcommon/lcseal.jpg" NDATA jpeg>
<!ENTITY % links SYSTEM "bell.ent">
%links;

]>        
<ead>[Beginning of EAD finding aid]</ead>

Tagging Example 2b:

Partial content of external "bell.ent" entity file; handle registered for each entity

<!ENTITY eadmss.mb003001 "http://hdl.loc.gov/loc.mss/eadmss.mb003001">
<!ENTITY eadmss.mb004001 "http://hdl.loc.gov/loc.mss/eadmss.mb004001">
<!ENTITY eadmss.mb004102 "http://hdl.loc.gov/loc.mss/eadmss.mb004102">
<!ENTITY eadmss.mb005003 "http://hdl.loc.gov/loc.mss/eadmss.mb005003">

Tagging Example 2c:

Shows <daoloc> with href value an entity declared in external entity file for Bell

Display Of Tagging Example 2c:

<daoloc> link resolves via handle server to search results linking to contents of partially digitized folder

Family correspondence
   Items available online.

Comments:

EAD linking elements

• Use the HREF attribute to set the target of the link from each linking element.
• Declare and use an entity for each link target rather than just embedding the URL in the HREF attribute of the linking element. For instance, in Example 1a, name the home page for the Hannah Arendt home page in American Memory as "arendthome". In the link from the <daoloc> in Example 1b, the name of the entity is preceded by an ampersand and followed by a semicolon. The entity declaration in the prolog (at the top of the finding aid) in Example 1a contains the information that the entity named "&arendthome;" is found at the URL http://memory.loc.gov/ammem/arendthtml/

XML prolog

• All finding aids should have information included in the XML prolog (the portion of the document which precedes the opening <ead> tag) in order to permit external linking. This information is included in the templates, and the full text of the prolog is provided in Examples 1a and 2a.
• The entity declaration, "<!ENTITY lcseal SYSTEM ...> enables linking to the LC seal, which is stored in the ITS file system and is displayed with every LC finding aid.
• If links are made to nine or fewer external entities, include the entity declarations in the document prolog. If there are ten or more entities, they will comprise a separate file to be stored in the same directory as the finding aid and its helper files, named with a .ent extension. The LC staff EAD web page contains further information on file structure and helper files.

Handles and external entities:

• If the target of a link is another EAD finding aid, a handle will be registered for the finding aid as part of standard procedures. The LC staff EAD web page contains examples of batch handle files for finding aids.
• If the target of a link is a stable web page, the entity declaration will include its URL, and there is no need to register a handle.
• If the target of a link is not a stable URL, for instance the response to a cgi-bin query, consider registering a handle. In Example 2b, handles should be registered for each entity, which would resolve to a URL that sends a search to InQuery, e.g., http://lcweb2.loc.gov/cgi-bin/query/S?ammem/magbell:@field(DOCID+@range (magbell37500200+magbell37500299))

Conversion from SGML to XML:

• In converting existing SGML finding aids to XML, processing instructions such as <?ATTLINK EXTPTR HREF URI> which were present in the SGML finding aids to enable external linking in the Panorama application have been converted to XML format in those finding aids, e.g. <?ATTLINK EXTPTR HREF URI?>. These instructions may be retained in a converted XML document; however, they should not be added to newly encoded finding aids.
• In the process of document conversion, the values of the declared entities are extracted from the declarations and appear as the value of the HREF attribute, and the entity declaration is no longer present (i.e., HREF="&arendthome;" will be changed to HREF="http://memory.loc.gov/ammem/arendthtml/".) This result for converted finding aids is acceptable, but newly encoded finding aids should continue to implement the practice described above concerning use of external entities.

Revision Date: 05/01/08

 Back to Top