Encoded Archival Description Tag Library, Version 2002
Tag Library Conventions
The EAD Elements section of the tag library contains descriptions of 146 elements, which are arranged alphabetically by their tag names. The Index by Element Name (Appendix D) makes it possible to locate those elements with tag names that might be hard to find alphabetically. For example, the index entry for Conditions Governing Use points to the tag name <userestrict>. The Index by Element Name also serves as a concise, easily browsable list of all EAD elements.
The EAD Elements section presents information for each element as shown in Figure 1. Some of a DTD's specialized terminology is explained on the following pages as a reminder of basic SGML/XML conventions involved in encoding documents with EAD (2).
Figure 1. Layout of element descriptions
This section also includes the three elements that occur in the EAD Group DTD: <eadgrp>, <archdescgrp>, and <dscgrp>. The EAD Group DTD allows several EAD-encoded finding aids to be combined into a single document and uses many EAD elements.
Short, mnemonic form of the element name that is used in the machine-readable encoded document. The tag name is the first word at the top of the page. Tag names appear between angle brackets, e.g., <archdesc>, except in the listings under "May occur within" and "May contain," and are always in lowercase.
Expanded version of the tag name which more fully describes the element's meaning. The full name of the element is usually a word or phrase that identifies the element's purpose. In the tag library, the element name follows the tag name on the page defining that element and appears with initial capital letters, e.g., <archdesc> Archival Description.
The first paragraph of the description defines the element by drawing from terminology in archival glossaries, basic dictionaries, and data dictionaries such as ISAD(G), MARC21, the Categories for the Description of Works of Art, and the Text Encoding Initiative DTD. (3) Any additional paragraphs describe how the element is used, differentiate it from similar elements, point out useful attributes, provide an illustrative example, or direct the reader to related elements. Stock phrases are used to suggest the kind of element being discussed. "Wrapper element" indicates an element that cannot contain text directly; a second, nested element must be opened first. Wrapper elements designate sets of elements that comprise a distinctive section of a finding aid, for example, the Descriptive Identification <did>. "Generic element" refers to elements common to many kinds of documents that contain information that does not specifically relate to the structural parts of a finding aid, e.g., <address> and <date>. "Formatting element" indicates elements that can be used to invoke special character or text presentation, such as block quotes, chronologies, and emphasis. When an element is required, that fact is also stated. Specific ISAD(G) data elements and/or MARC fields that relate to a given element are provided when applicable. For information on specified sequences of elements, consult the DTD itself. For example, you may wish to check the list of subelements in an XML authoring program or DTD visualization tool.
Identifies what may occur within the element being defined. Elements are listed in alphabetical order by tag name. Elements may be empty (e.g., containing only an attribute); or they may contain text (called #PCDATA); other elements; or a mixture of text and other elements.
The abbreviation #PCDATA (parsed character data) means that text content is allowed directly inside of an element, but the text cannot include characters that would be interpreted by a parser as action codes. For example, a left angle bracket has to be represented as the character entity reference ⟨ so that it is not misinterpreted as the start of an element name.
The list of nested elements usually includes more elements than are generally needed, because similar elements sharing the same content model travel together as a group. This is a device to ease the authoring of a DTD and to aid machine processing of encoded documents. For example, once one reference element such as <ref> is listed under May contain, all the reference elements appear, including <archref>, <bibref>, <extptr>, <extref>, and <ptr>, even though the simple internal <ref> element is the most likely choice in a particular context.
May occur within:
Identifies all of the parent elements within which the described element may appear, listed in alphabetical order by tag name. This information conveys the sense of where and how often an element is available throughout the DTD. Definitions for parent elements may provide additional information about an element's usage.
Identifies all attributes that can be associated with an element. Attributes are represented in lowercase letters in XML coding, but the Online EAD Tag Library uses the convention of capital letters to distinguish attributes from elements within the tag library context. See the EAD Attributes section of the tag library for definitions and additional information.
Most element descriptions include a tagged example to indicate how attributes and elements can be used together. Most of the examples are taken from real finding aids; others have been specially constructed for the tag library. The examples illustrate any required sequences of elements, as in the case of subelements within the <eadheader>, or required attributes such as LEVEL in <archdesc>. In other cases, the examples are intended simply to show what is possible. Some examples have ellipses, either between or within elements, where other elements or text have been omitted. Some elements have multiple examples -- one may show very dense markup that uses numerous attributes while another may illustrate a minimalist approach to the markup. Either approach is valid in EAD, and it is up to the repository to determine the optimal level of markup based on institutional resources and/or consortial guidelines.
2 - For basic information about SGML and XML and pointers to additional sources, consult the XML Cover Pages at http://www.oasis-open.org/cover/.
3 - See below
May 25, 2006