A guide for mass digitization, automated workflows, and promotion of interoperability with XML using the TEI
Editors: Kevin Hawkins, Michelle Dalmau, Elli Mylonas, and Syd Bauman
Creation of ODDs: Syd Bauman
Version: 4.0.0 (published September 2018)
This document is the fourth major revision of a document formerly known as TEI Text Encoding in Libraries: Guidelines for Best Encoding Practices, which has been updated to comply with the Text Encoding Initiative’s Guidelines for Text Encoding and Interchange (P5). These Best Practices were originally created for use in large, library-based digitization projects but are useful as a way of approaching digitization and encoding as a whole.
There are many different library text digitization projects, serving a variety of purposes. With this in mind, these Best Practices are meant to be as inclusive as possible by specifying five encoding levels. These levels are meant to allow for a range of practice, from wholly automated text creation and encoding, to encoding that requires expert content knowledge, analysis, and editing. The encoding levels are not strictly cumulative: while higher levels tend to build upon lower levels by including more elements, higher levels are not supersets because some elements used at lower levels are not used at higher levels—often because more specific elements replace generic elements.
In brief, the encoding levels (with approximate examples) are as follows:
| Level | Description | Example of encoding of Alger Hiss document | Display example |
|---|---|---|---|
| Level 1 | The text is generated through OCR, is subordinate to the page image, and is not intended to stand alone as an electronic text (without page images). | Alger Hiss document | example |
| Level 2 | The text is generated through OCR and is mainly subordinate to the page image, though navigational markers (suchg as textual divisions and headings) are captured. | Alger Hiss document | example |
| Level 3 | The text is created by conversion, either by way of OCR or keyboarding. Some structural elements of the text are encoded. The text may be used with or without page images. | Alger Hiss document | example |
| Level 4 | The text is generated either through corrected OCR or keyboarding and is able to stand alone without page images in order for them to be read by students, scholars, and general readers. | Alger Hiss document | example |
| Level 5 | The text is generated either through corrected OCR or keyboarding and is able to stand alone without page images, as in Level 4. In addition, the text includes semantic, linguistic, prosodic, or other types of tagging created through substantial human intervention by encoders with subject knowledge. | (none) | example |
In these Best Practices, use of elements and attributes tends toward explicitness for ease of processing even though a human or possibly machine reader might be able to make inferences based on context. Only those elements and attributes mentioned below are recommended for use in encoding based on these Best Practices; use of other TEI elements and attributes is not recommended. Consult the full TEI Guidelines (P5) for guidance on use of elements and attributes beyond what is described below.
As guidelines rather than a specification, these Best Practices use should or recommended instead of must to explain conformance to the practices described here; the only exception is a practice required by P5, indicated by required. Optional practices are indicated by may or optional. However, to encourage conformance to these Best Practices, the ODD files will generate schemas that require use of recommended elements (those indicated by should or recommended).
These Best Practices specify a recommended archival storage format. Local system needs may require transformation of documents in this archival format to another XML format (another TEI customization or another type of XML) for use by a local indexing or delivery software.
The TEI Tite customization of P5 was developed as a subset of the TEI to be used as a vendor specification for outsourced encoding of the type often initiated by libraries, archives and other cultural heritage organizations. These Best Practices were created to support in-house encoding that adheres as closely as possible to common TEI practice and library standards yet still leaves room for variation in local practice.
If a library uses TEI Tite for outsourced encoding, it should find that converting files from the TEI Tite format to a format conforming to these Best Practices is not difficult. TEI Tite files may be converted to Best Practices Level 3 with some loss of granularity; or to Level 4 with some additional markup with minimal human intervention. (The reason Level 3 does not contain as many elements as TEI Tite is to allow for use of this encoding level, whether for encoding of born-digital source documents or for upgrading Level 1 or Level 2 texts, with less human intervention than would be required by TEI Tite.)
These Best Practices are meant to complement the TEI Tite customization of P5. Whereas TEI Tite is meant for vendors who need exact specifications for encoding, these Best Practices document how a large-scale encoding project, whether based in a library or not, might create conformant TEI documents out of vendor-generated or locally-created TEI documents. TEI Tite lacks header metadata and elements for encoding textual structures of possible interest to libraries; however, once Tite documents are transformed to a TEI-conformant encoding used by an institution, these Best Practices can serve as a point of reference for developing the TEI header and applying richer markup as reflected in Level 4 or 5 of these Best Practices.
For a comparison of the TEI Tite schema to these Best Practices, see TEI Tite's Appendix A.
TEI simplePrint is a customization of P5 designed to be an entry point for a wide variety of encoding projects, especially those dealing with Western European early modern printed material. An implicit aim of the creators of this customization, as with these Best Practices, was to prescribe a single way to encode common features in source documents. The features to be encoded are more granular than those in Levels 1 through 4 of these Best Practices; therefore, TEI simplePrint is discussed below with Level 5. Note that unlike these Best Practices, TEI simplePrint specifies a processing model for each element, recommending how they should be displayed or otherwise processed.
The goal of the TEI is interchange, not interoperability. While seamless interoperability of texts created for different purposes is an elusive goal, use of a common markup vocabulary and syntax greatly aids interchange. Nevertheless, keep in mind that others—even within your organization—may use your texts in the future for other uses than you intended in your encoding.
An encoding project should strive for internal consistency and for use of standards so that the data can be modified or enhanced in the future with ease. In cases where local practice deviates from standards, there should at least be internal consistency in the local practice.
For the purpose of interchange, TEI documents should be saved in UTF-8 format, without beginning with a byte-order mark (U+FEFF). Furthermore, while TEI allows for capturing of glyph variants not distinguished by Unicode (see chapter 5 of P5), the special elements for this purpose are not recommended in these Best Practices in order to facilitate interchange.
When reformatting to digital media using any level of encoding, the electronic text should begin with the transcription of the first word on the first leaf of the original work. When using levels 1 to 3 of encoding, it may be impractical or undesirable to transcribe and encode certain features of the text, such as publisher’s advertisements or indexes. Any systematic omissions of material found in the original work should be noted in the <samplingDecl> in the TEI header. Non-systematic omissions should be indicated in the <notesStmt> of the <teiHeader>. At Level 4 and above, the transcription should be complete.
When encoding composite documents (an issue of a journal, a volume of conference papers, a book of poems, etc.) at Level 3 and above, consider creating separate TEI documents for each unit (journal article, conference paper, poem, etc.) so that more granular metadata may be attached to each unit in its own TEI header. A further step will be necessary in order to ensure that the structure of the composite document—how the units relate to each other—is adequately represented. A common way to accomplish this is to create a separate TEI document for the composite document that uses XInclude to include the relevant portions of the TEI documents for the units in the correct order.
Encoding of end-of-line, end-of-column, and end-of-page hyphenation varies considerably in the TEI community. Some capture all hyphens found on the printed page, while others remove those in the middle of words not normally hyphenated for easier implementation of full-text retrieval. If preserving hyphens, some will capture all hyphens using the same character, while others will distinguish hyphens that must be present in any case (often called hard hyphens) and those that are only present by virtue of being at the end of a line, column, or page (often called soft hyphens).
This issue is complicated by the fact that Unicode prescribes use of a soft hyphen not for a visible hyphen that might have been absent but instead for a place where a hyphen might occur. Furthermore, it includes a non-breaking hyphen, used in cases like ‘re-creation’ (meaning to create again, as opposed to ‘recreation’, meaning relaxation), in addition to a regular hyphen, which would normally count as a word boundary. In short, Unicode is oriented toward electronic text that may be processed with a computer in various ways, not toward capturing source documents.
Since OCR software relies on dictionaries to determine the probability not simply of characters but of whole words, it is often able to capture hyphenation in different ways, per the needs of a specific project.
At Levels 1 and 2, do not attempt to disambiguate different uses of hyphens. Encode all hyphens appearing in the source document using character U+2010 (HYPHEN) if possible; alternatively, use the semantically ambiguous U+002D (HYPHEN-MINUS).
At Level 3, if <lb>, <cb> and <pb> are used, optionally distinguish uses of the hyphen with <pc> and force. At Level 4, if <lb>, <cb> and <pb> are used, the use of <pc> and force on these elements is required when all original hyphenation and line breaks are being retained. This is important when encoding a text that may be republished in different formats causing line breaks and hyphenation to differ from the original.
Sample hyphenation markup follows, using the example of a word broken at the end of a line. (If such hyphens occur at a column or page break instead of a line break, use <cb> or <pb> instead.)
| Colloquial name | Appearance in source document | Encoding | Note |
| Hard hyphen | This is not a run- on sentence. |
This is not a run<pc force="weak">-</pc><lb break="no"/>on
sentence. |
The use of weak as the value of force indicates that the encoder considers "run-on" to be a single orthographic token, where the hyphen is not a word separator. The use of no as the value of break also indicates that the line break occurs inside an orthographic token (single word) which is broken across a line. |
| Hard hyphen |
This is not a run-
on sentence.
|
This is not a run<pc force="strong">-</pc><lb break="yes"/>on
sentence. |
The use of strong as the value of force indicates that the encoder considers "run-on" to be two orthographic tokens, where the hyphen is also a word separator. The use of yes as the value of break indicates that the line break occurs between two words. |
| Soft hyphen |
UTF-8 is a char-
acter encoding for Unicode.
|
UTF-8 is a char<pc force="strong">-</pc><lb break="yes"/>acter
encoding for Unicode. |
As in the first example, the use of weak as the value of force indicates that the encoder considers "character" to be a single orthographic token where the hyphen is only indicating that the word is broken across a line. The use of no as the value of break also indicates that the line break occurs inside an orthographic token (single word) which is broken across a line. |
| Unclear case |
Some people say TEI is a mark-
up language.
|
Some people say TEI is a mark<pc force="inter">-</pc><lb
break="maybe"/>up language. |
The use of inter as the value of force indicates that the encoder is not taking a position on whether "mark-up" is a single orthographic token or two words. The use of maybe as the value of break is also inconclusive on whether the line break occurs in between words or inside a word. |
Do not confuse the following characters with hyphens:
A filename scheme that is internally consistent should be established for any encoding project.
Consider the following best practices when determining the file name scheme for your project:
A number of attributes take a URI (Uniform Resource Identifier) as their
value. Note that in addition to the full form of reference defined by URI syntax, these
attributes can take a relative reference (e.g., filename.ext) or a fragment
identifier (e.g., #foo).
At Levels 2 and higher, when <text> is used, an encoding project should use only numbered divisions (i.e., <div1>, <div2>, etc.) or unnumbered divisions (i.e., <div>) but not both. This applies both within a TEI document (i.e., within <front>, <body>, <back>, even if nested within <group> or <floatingText>), and across TEI documents in any given collection. Keep in mind that numbering of textual subdivisions starts over (at <div1>) within <floatingText> elements nested inside a subdivision, so any software that expects to process nested numbered divisions within a document will need to account for this.
The choice of numbered or unnumbered divisions should be documented with the <tagUsage> element in the header. See section 4.1.8, Element and Attribute Recommendations for the TEI Header, below.
Whether numbered or unnumbered divisions are used, the type attribute of the division element is not recommended at Level 1 (because only one encoded division in the text exists), is optional at Level 2 (because the division-level metadata need not classify these divisions), is recommended at Level 3 (for broad yet useful analysis of text divisions), and is strongly recommended at Levels 4 and 5 (for full analysis of the text structure). Recommended values for the type attribute are listed below. Other values may be used if these are not applicable. See section 3.9.1, on the type attribute, below for a discussion of adding customized values to the project ODD.
| Attribute Value | Description |
| abstract | Usually appears in front matter. |
| acknowledgement | Usually appears in front matter. |
| contents | A table of contents. Usually appears in front matter. |
| dedication | A dedication. Usually appears in front matter. |
| docAuthorization | A statement indicating that the document's printing was officially authorized. |
| foreword | Usually appears in front matter. |
| frontispiece | A portrait or other image (usually of the author, usually full page) printed at the front of a document. Usually appears in front matter. |
| imprimatur | A formal indication (usually on the title page or in the front matter) that the document has received official license to be printed. |
| preface | A section of the front matter that does not carry a more specific designation. Usually appears in front matter. |
| Attribute Value | Description |
| book | A major structural component of a long work, identified explicitly in the text as a “book” |
| chapter | A chapter, typically in a prose document. |
| part | A major component of a work, containing further subdivisions. |
| section | A generic section of a larger work. |
| subsection | A generic subdivision of a section. |
| volume | A single printed volume in a multi-volume work. |
| drama | A dramatic text. |
| dramaPart | A portion of a drama other than a prologue, act, scene, or epilogue. |
| act | An act in a dramatic text. |
| scene | A scene in a dramatic text. |
| castlist | A list of characters in a dramatic text. |
| poem | A poem. |
| poemGroup | A group of two or more poems under a common heading. |
| argument | A short passage at the start of a document or section giving a prose description of its contents. |
| corrigenda | A section describing corrections to be made to the document. |
| entry | An entry in a document that is organized as a log or diary with dated entries. |
| epigraph | A short quotation at the start of a document or section, often accompanied by an attribution. |
| epilogue | A short concluding section, usually of a dramatic or fictional work. |
| prologue | An opening section of a literary work (typically drama or poetry). |
| narrative | An embedded narrative. |
| nonfictionProse | A text intended to be nonfiction consisting primarily of prose. |
| novelPart | A portion of a novel. |
| advert | An advertisement for a printed work or other product. |
| calendar | A formal calendar; a document or document section identifying itself as a calendar. |
| essay | A short prose non-fiction document. |
| examination | A section that is identified explicitly as an ‘examination’ in a text that uses this as a main structural division. |
| letter | Any document in epistolary form, i.e. addressed by a sender to a recipient. |
| prayer | A prayer. |
| recipe | A recipe in a cookbook. |
| speech | A section described as a speech or public lecture, in a document that uses this as a main structural division. |
| timeline | A timeline. |
| tract | A short treatise in pamphlet form often on a religious subject. |
| Attribute Value | Description |
| addendum | Additional material, typically omissions, added at the end of a publication. |
| appendix | Usually appears in back matter. |
| bibliography | Usually appears in back matter. |
| colophon | A short inscription, typically at the end of a book or manuscript, containing the title, printer, date and place of printing, etc. Usually appears in back matter. |
| concluding | Any section of the back matter that does not carry a more specific designation; includes afterwords, epilogues, codas, etc. |
| endnotes | A section containing endnotes for the document. |
| glossary | Usually appears in back matter. |
| index | An alphabetical listing of the topics in a document, usually with accompanying page references. Usually appears in back matter. |
| notes | Usually appears in back matter. |
Page breaks should be encoded using the <pb> element, with the value of the n attribute denoting the number of the page whose content follows this element. The <pb> element should always be contained within a text division for ease of retrieval with indexing software. For example, a page break that occurs between chapters 2 and 3 should be encoded right after the opening tag of the text division that opens chapter 3 rather than before the closing tag of the division that ends chapter 2 or between the two text divisions. In the case of a page break occurring at the boundary of nested textual divisions, the <pb> element should always be encoded within the lowest level division. For example, a page break that occurs between chapters 2 and 3, where chapter 3 begins with an editor's note requiring its own text division, would be encoded right after the opening tag of the text division for the editor's note.
Any divergence from this practice should be documented in a <p> in the <editorialDecl>.
There are three recommended mechanisms for linking between the encoded text and facsimile page images of source documents. Projects may use any of the following methods:
For those projects relying on METS, note that the xml:id attribute is used as a conceptual identifier for content as opposed to an explicit pointer to a specific representation of that content. (Conversely, the facs attribute is a pointer, not an identifier.) These identifiers are then used to generate a METS document that bundles the various content types (e.g., master image files, derivative image files for Web delivery, PDFs, etc.), explicitly lists all versions of the content, and defines the relationships between the constituent parts. This is achieved through the use of the <mets:fileSec> and <mets:structMap> sections of the METS document (see sample METS document for a TEI project).
The International Image Interoperability Framework (IIIF), with its growing user community, is likely to emerge as an alternative mechanism for linking between encoded text and images of source documents. The value of a facs attribute could be a IIIF Image API Request URI (e.g., to access a full-sized image). However, note that the TEI and IIIF communities have not yet agreed upon specific details of a mechanism for integrating data from these two communities of practice.
These Best Practices provide recommended usage of attributes as used in the TEI header and within the body of the TEI document (within the <text> element), as evidenced by attributes used in encoding example snippets and the prose description of this document.
This section contains general advice on the use of particular attributes commonly needed for library encoding projects. (All of the attributes below are commonly used on various elements, but not every element requires or even allows these attributes.)
Constructing a list of acceptable attribute values for the type attribute for each element, on which everyone could agree, is impossible. Instead, it is recommended that projects describe the type attribute values used in their texts in the project ODD file and that this list be made available to people using the texts. It is worth noting that, at present, Roma, the web front-end editor for ODD files, does not have a mechanism for providing this documentation; instead, this information should be added to the ODD file manually. For a list of standard names and definitions of bibliographic features of printed books, see ABC for Book Collectors by John Carter (8th edition, New Castle, Del. and London: Oak Knoll Books and the British Library, 2004, available online at https://www.ilab.org/articles/john-carter-abc-book-collectors).
This attribute is sometimes used to number elements for machine processing, but it often includes data represented in the source document, such as page numbers or footnote numbers. Example: <pb n="456"/>
The ref attribute is available on a variety of elements, including <persName>, <orgName> <author>, and <title>. Its value is a URI that identifies external metadata about the content of the element. Since Linked Data applications in libraries make many authority records accessible through URIs, this attribute can be used for disambiguation (authority control). For example:
XML software will then confirm
when it encounters ref="#geo_0034" that xml:id="geo_0034" exists
elsewhere in the document.
At levels 3 and above, the style, rend, and rendition attributes may be used when it is desirable to record information about how a textual feature was displayed in the source document.
Never use these attributes on header elements since, in the header, metadata is transcribed and possibly regularized, as in a catalog record, but its exact appearance is not meant to be captured.
If a project is normalizing the rendering of text objects (for example, such that all titles should be italicized, regardless of how they appeared in the source document), there is no need to use these attributes; instead, a stylesheet will determine that all titles are displayed in italics.
However, if a project is faithfully recording the rendering in the source document, one of these attributes should be used to indicate this rendering, either on all elements to be rendered differently from the surrounding text or on all elements whose rendering does not follow the default stylesheet.
For the value of the style attribute, use only valid CSS properties and values as in a CSS declaration-block but without curly braces. For example:
<foreign style="font-style: italic">
<title style="text-decoration: underline; font-size: x-large">
<foreign rendition="#i">documented with the <rendition> element in the header:
If there are formatting features in the source that cannot be expressed with CSS syntax, the rend attribute may be used instead of style or rendition to supply a rendering using a locally defined style language.
This attribute is used to indicate the natural language of the content of an element. It is generally not found on or within the <sourceDoc> or <text> elements at Level 1 or Level 2, but is common at Level 3 and above. See the documentation of the teidata.language datatype in P5 for information on the values of xml:lang.
| Element | Description | |
| <TEI xml:id="___" xmlns="http://www.tei-c.org/ns/1.0"> | The root element of a TEI document. Use of the xml:id attribute
is recommended, giving the same unique identifier for the TEI document as in
teiHeader/fileDesc/publicationStmt/idno. |
|
| ├ | <teiHeader xml:lang="___"> | [required] Contains metadata about the TEI document. The xml:lang is recommended; it indicates the language used for the metadata describing the document. |
| ├ | <sourceDoc> | [recommended at Level 1, optional at Levels 2–5] Contains a direct, generally machine-generated, transcription of document pages without further logical or structural information. |
| ├ | <facsimile> | [optional] Defines sets of images that correspond with the text. Should only be used if page images are included and if this particular mechanism for linking page images is chosen. See section 3.8, Linking Between Encoded Text and Images of Source Documents. |
| └ | <text xml:lang="___"> | [recommended at Levels 2–5] Contains the encoded transcription of the source document. The xml:lang attribute is recommended; it indicates the primary language of the source document. |
The child elements of these top-level elements are described below.
The TEI header is a metadata record for an encoded text. It includes bibliographic information related to the electronic document and, if appropriate, the bibliographic data for the original analog source document from which the electronic edition was created. The TEI header often includes a description of the encoding decisions or practices used to create the electronic document. While TEI Lite calls the header ‘the electronic title page’, it actually more closely resembles a catalog record with additional data not routinely stored in MARC records.
As with any descriptive metadata, the metadata in the TEI header can serve multiple audiences. In the local context, a TEI header provides metadata about the TEI document, its source, and its provenance. The TEI header may be used to enable metadata exchange, to automatically create indexes (author lists, title lists) for a collection of TEI documents, and to aid in browsing heterogeneous TEI documents. TEI headers may also be used as a basis for other metadata records (such as MARC or Dublin Core), though generation of other formats may require human intervention because they often are more granular, or have different granularity, than TEI headers.
While a TEI header is often perceived as similar to or at least related to a MARC bibliographic record, a TEI header does not typically have a one-to-one correspondence with a MARC record. For example, one MARC bibliographic record may be used to describe a collection of TEI documents with individual headers. Furthermore, while a MARC bibliographic record captures metadata about a bibliographic entity in a library’s collection, a TEI header records information both about an encoded text and about the source document for that encoded text.
Each institution and even each project may have a different approach to the way electronic texts are created in TEI and then represented in a larger public catalog through MARC bibliographic records. At one institution, the same unit (e.g., a cataloging department) may be responsible for creating both TEI headers and MARC bibliographic records, while at other institutions the work may be distributed among different units. Within the library domain, metadata or cataloging experts are usually required for at least review and standardization of both the TEI header and the MARC bibliographic record.
In order to allow automatic generation of TEI headers from MARC bibliographic records and MARC bibliographic records from TEI headers, according to these Best Practices, some elements should contain content not typical for TEI practice but necessary due to a lack of granularity in the MARC format.
The Metadata Encoding and Transmission Standard (METS) includes direct support for TEI Headers; that is, a complete <teiHeader> element can be included in a METS metadata record alongside MARC, MODS, and DC metadata. METS specifies an MDTYPE of TEIHDR to indicate a TEI Header. For an example of how this might be done, see this sample METS record for The “Sure to Rise” Cookery Book. We are unaware of any METS implementations which provide significant support for TEI headers out-of-the-box.
Functional Requirements for Bibliographic Records (FRBR)Note: https://www.ifla.org/publications/functional-requirements-for-bibliographic-records is a conceptual model developed by the International Federation of Library Associations (IFLA)Note: https://www.ifla.org/ ‘for relating the data that are stored in bibliographic records to the needs of the users of those records’ ((Functional Requirements for Bibliographic Records: Final Report, February 2009, p. 7, https://www.ifla.org/files/assets/cataloguing/frbr/frbr_2008.pdf)). It is best known for its model of four primary bibliographic entities: work, expression, manifestation, and item. The FRBR model also includes primary relationships between certain of these entities: a work may be realized through one or more expressions, an expression may be embodied in one or more manifestations, and a manifestation may be exemplified by one or more items. Since the publication of FRBR in 2008, the library metadata community has collaborated to develop more precise entity-relationship models relating to bibliographic metadata—notably FRBRooNote: http://www.cidoc-crm.org/frbroo/ and BIBFRAMENote: https://www.loc.gov/bibframe/, each with different configurations of bibliographic entities than the four primary entities in FRBR.
It is important to note that these Best Practices, like P5 as a whole, does not distinguish betwen work, expression, manifestation, and item according to their definitions in FRBR.
Due to sustained interest in the original FRBR model from within the TEI community, these Best Practices describe how an encoder might identify bibliographic entities relating to a TEI document and express relationships between them. For example, a TEI document might contain the text of a particular edition of a rare book (a FRBR manifestation), and the header could reference all extant copies (FRBR items) of this book. These relationships and references to bibliographic entities are encoded using the <listRelation> element, an optional child of <sourceDesc>.
Note that a TEI document
itself, like any other XML document, occupies an ambiguous territory between a FRBR expression
and a FRBR manifestation.Note:
, , , and . 2003. An XML
document corresponds to which FRBR Group 1 entity?
. Proceedings of
Extreme Markup Languages 2003. http://conferences.idealliance.org/extreme/html/2003/Lawton01/EML2003Lawton01.html.
Several other descriptive metadata schemas are prevalent within the library domain, including Dublin Core (DC), Dublin Core Qualified (DCQ), and the Metadata Object Description Schema (MODS). Each of these schemas contains elements that capture the same data as many of the elements in the TEI header. As with MARC, a variety of automated or manual workflows can be implemented to crosswalk metadata from one standard to another and provide for increased sharing of metadata about electronic texts in larger contexts. In particular, DC and MODS are common schemas used by the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) and may be particularly valuable for sharing metadata across institutions.
Unfortunately, there is currently no mechanism for specifying that the content of an element should be drawn from an outside metadata source or that this outside metadata source should supplement the content of the element. In the absence of such mechanisms, users of these Best Practices may use the <idno> element to supply identifiers for outside metadata records and may supply identifiers for certain authority records using the ref attribute, allowed on certain elements.
The header's <xenoData> element may be used to embed non-TEI metadata in a TEI document.
Within the library domain, there are several authoritative publications on how to create bibliographic and descriptive metadata for objects. These are usually called “descriptive cataloging standards”; two prominent examples are the International Standard Bibliographic Description (ISBD) and Resource Description and Access (RDA), an implementation of ISBD that has replaced the Anglo-American Cataloguing Rules, Second Edition (AACR2) and other national cataloging codes. These standards are extensive and outline a set of rules that enforce consistency across a voluminous amount of metadata.
It is recommended that metadata about the source document included in the header be taken from the catalog record for the source document. However, there may be cases when this information is incomplete or insufficient. The following sources of information are recommended in creating the TEI header:
Below is documentation on use of elements and attributes within the <teiHeader> element. These recommendations apply to all levels of encoding. The mapping to MARC for cataloging the TEI document assumes that the header is created based on the encoded text, not the source document. Note that the terms “work” and “item” are not used in the narrow way that they are defined in RDA.
| Element | Description | Equivalent in MARC when cataloging the TEI document according to RDA April 2017 update | Equivalent in MARC for the source document (whether cataloged according to RDA or AACR2) | ||||||
| <teiHeader xml:lang="___"> | [required] The <teiHeader> contains metadata about the TEI document. The xml:lang attribute is recommended; it indicates the language used for the metadata describing the document. | 040 $b | n/a | ||||||
| ├ | <fileDesc> | [required] The <fileDesc> contains bibliographic metadata about the TEI document. One of its child elements, <sourceDesc>, describes the source document from which the TEI document was created. | n/a | n/a | |||||
| │ | ├ | <titleStmt> | [required] | n/a | n/a | ||||
| │ | │ | ├ | <title type="___"> | [required] One or more <title> elements are required to give the title of the TEI document being created. It is suggested that titles be constructed based on the source document according to the descriptive cataloging standard used. Use of the level attribute is not recommended since it does not apply to a TEI document in a collection. Use of the type attribute is recommended. It should have one of the following values as suitable in local practice:
|
|
|
|||
| │ | │ | ├ | <author> | [recommended] One or more <author> elements (one name per
element) are used to encode the names of entities primarily responsible for the content of
the TEI document—usually, the author(s) of the source document. Use <persName> or <orgName> when applicable.
Whenever possible, establish or use the authorized form of the name from a name authority
file. Examples:
|
|
|
|||
| │ | │ | ├ | <editor> | [recommended] If applicable, use one or more <editor> elements (one name per element) to encode the names of entities besides those in <author> elements that acted as editors of the TEI document—usually, the editor(s) of the source document. If considered appropriate by the encoding project, the editor of the TEI document should be entered here. Use <persName> or <orgName> when applicable. Whenever possible, establish or use the authorized form of the name from a name authority file. Unlike in P5, do not use this element for translators, illustrators, compilers, or other roles not generally considered an editor. Therefore, do not use the role attribute. |
|
|
|||
| │ | │ | ├ | <respStmt> | [recommended] Record the names of other persons or organizations, one responsibility or
party per <respStmt>, that have responsibility for the
intellectual or artistic content of the TEI document—often by transitivity from the source
document—not covered by <author> and <editor>. This includes translators, illustrators, compilers, proofreaders,
encoders, and those who wrote a preface or introduction. Each <respStmt> should contain either:
|
|
|
|||
| │ | ├ | <editionStmt> <p> | [recommended] Include a statement about the edition of the TEI document produced, not the source document. | 250 | n/a | ||||
| │ | ├ | <publicationStmt> | [required] Use the child elements below (rather than <p> for a prose description). | n/a | n/a | ||||
| │ | │ | ├ | <publisher> | [recommended] The publisher is the party responsible for making the file (the TEI document, not the source document) public. | 264_1 $b | n/a | |||
| │ | │ | ├ | <distributor> | [recommended] The distributor is the party from whom copies of the file (the TEI document, not the source document) can be obtained. Often the same as <publisher>, in which case no <distributor> should be given. | 264_2 $b | n/a | |||
| │ | │ | ├ | <idno> | [recommended] Any unique identifier for the TEI document as determined by the publisher of the TEI document. Optionally use a type attribute to indicate the type of identifier. | 028 5_ | n/a | |||
| │ | │ | ├ | <availability> | [recommended] Provide a prose rights statement for the TEI document. If possible, provide a standard license, such as one from Creative Commons, using the <license> element. Otherwise, provide information on all applicable rights—rights in the original work, rights in page images of the source document, and rights in the encoded text—in a <p> element. | 540 | n/a | |||
| │ | │ | └ | <date when="___"/> | [recommended] Refers to the date of the first publication of this edition of the TEI document. The when attribute (see att.datable.w3c class) is used instead of free content to aid machine processing. (In this context, the <date> element should have no content.) | 264_1 $c | n/a | |||
| │ | ├ | <seriesStmt> | [optional] This element contains information about the electronic series being created. | n/a | n/a | ||||
| │ | │ | └ | <title level="s" type="___"> | [recommended] This element contains the title of the series. Whenever possible, establish or use the authorized form of the title from a name authority file. Use of the type attribute is optional, but if it is used, it should follow the instructions for use of this element in P5. |
|
n/a | |||
| │ | └ | <notesStmt> <note> | [optional] Use one <note> element for each note about the TEI document that does not have an appropriate location elsewhere in the header. | 5xx | 5xx | ||||
| │ | └ | <sourceDesc> | [required] Use one <sourceDesc> per source document. Metadata for the source document may be automatically generated from a MARC record. | n/a | n/a | ||||
| │ | ├ | <biblStruct> | [recommended] Use <biblStruct> with child elements arranged in the order below for ease of display according to ISBD. (This element is used instead of <bibl> to enforce structure, but <biblFull> is not used because it requires more elements than are typically available in library metadata sources.) | n/a | n/a | ||||
| │ | ├ | <analytic> | [recommended] Use this element and its children only if the object of encoding is part of a larger work—for example, an article in a journal issue, a chapter in a book, or a poem in a collection. Below the object of encoding that is part of a larger work is referred to as the analytic item. | n/a | n/a | ||||
| │ | │ | ├ | <author> | [recommended] One or more <author> elements (one name per element) are used to encode the name for the personal author or corporate body responsible for the creation of the intellectual or artistic content of the analytic item. Use <persName> or <orgName> when applicable. Whenever possible, establish or use the authorized form of the name from a name authority file. | n/a | n/a | |||
| │ | │ | ├ | <title level="a" type="___"> | [recommended] At least one <title> element is required for the title of the analytic item. Transcribe the title according to the the descriptive cataloging standard used. Use of the type attribute is recommended. It should have one of the following values as suitable in local practice:
|
n/a | n/a | |||
| │ | │ | └ | <ptr target="___"> | [optional] In the value of target, provide a URI for analytic item. For example, this could be link to a facsimile of the analytic item that is different from the TEI document. | n/a | n/a | |||
| │ | ├ | <monogr> | [required] Use this element to group together the elements describing the source document bibliographic item that is published as an independent item. The TEI definition of this element specifies that it is used even for works that might not otherwise be considered “monographs,” so, for example, bibliographic data about a journal title is included in this element. | n/a | n/a | ||||
| │ | │ | ├ | <author> | [recommended] One or more <author> elements (one name per element) are used to encode the name for the personal author or corporate body responsible for the creation of the intellectual or artistic content of the source document bibliographic item, even if this creator is not the main entry in the catalog record. Use <persName> or <orgName> when applicable. Whenever possible, establish or use the authorized form of the name from a name authority file. | 534 $a = 1st author |
|
|||
| │ | │ | ├ | <title level="___" type="___"> | [recommended] At least one <title> element is recommended for the title of the source document bibliographic item. Transcribe the title according to the descriptive cataloging standard used. Use of the level attribute is optional. If used, it should be used as in P5. Use of the type attribute is recommended. It should have one of the following values as suitable in local practice:
|
534 $t |
|
|||
| │ | │ | ├ | <respStmt> | [recommended] Statement of responsibility on the source document bibliographic item, according to the descriptive cataloging standard used. Record one responsibility or party per <respStmt>. Each <respStmt> should contain either:
Whenever possible, establish or use the form of the authorized name from a name authority file. If generating the <sourceDesc> from a MARC record, it will be difficult to split the content of the 245c field into <resp> and <persName> (or <orgName>) elements, so it is recommended to use <title type="marc245c"> instead of this element. |
500 | n/a | |||
| │ | │ | ├ | <edition> | [recommended] Edition statement (if present) according to the descriptive cataloging standard used. | 534 $b | 250 | |||
| │ | │ | ├ | <imprint> | [required] | n/a | n/a | |||
| │ | │ | │ | ├ | <pubPlace> | [recommended] Place of publication from the source document bibliographic item according to the descriptive cataloging standard used. Optionally remove ISBD punctuation for separating areas of the bibliographic description (such as a colon) when deriving from a MARC record. However, use brackets to indicate supplied information according to the descriptive cataloging standard used, e.g. “[Toronto?]” or “[Place of publication not identified]”. | 534 $c |
|
||
| │ | │ | │ | ├ | <publisher> | [recommended] Name of publisher, distributor, etc. from the source document bibliographic item according to the descriptive cataloging standard used. Optionally remove ISBD punctuation for separating areas of the bibliographic description (such as a comma) when deriving from a MARC record. However, leave brackets that indicate supplied information according to the descriptive cataloging standard used, e.g. “[publisher not identified]”. | 534 $c |
|
||
| │ | │ | │ | └ |
<date when="___">
or <date notBefore="___" notAfter="___"> or <date from="___"> or <date to="___"> or <date from="___" to="___"> |
[recommended] Date of publication, distribution, etc. from the source document bibliographic item. The content of the element is the statement of this data according to the descriptive cataloging standard used. Since the content of the element according to the descriptive cataloging standard used is not easily processed by machine, when possible include the following attribute(s) with valid values: either when, or both notBefore and notAfter, or one or both of from and to. Descriptive cataloging standards may distinguish between a possible range of dates for
publication (such as “[between 1860 and 1868?]”. In the case of uncertainty, use
If the date is unknown (for example, recorded according to the descriptive cataloging
standard used, e.g., “[date of publication not identified]" or "[date of distribution not
identified]”, use |
|
|
||
| │ | │ | ├ | <extent> | [recommended] Describes the extent of the source document bibliographic item. If the data is generated by hand, it should include a comprehensible statement of the size of the item, such as the number of pages or leaves. If generated from a catalog record, there should be two <extent> elements: one for the extent of the item (e.g., number of pages) and other physical details, and a second one for the dimension(s). Both should be recorded according to descriptive cataloging standard used. | 534 $e | 300 | |||
| │ | │ | ├ | <note> | [optional] Use for notes about the source document bibliographic item, given according to the descriptive cataloging standard used. | 534 $n | 5xx | |||
| │ | │ | ├ | <idno> | [optional] Use one or more <idno> elements to give
identifiers for the source document, text, or work of the bibliographic item, whether
assigned by the holding library (such as a call number), the publisher of the original
document (such as an ISBN), or a standard bibliography (such as an identifier from the
Short Title Catalogue or Books in
Maori). Use the following values for the type attribute if
applicable, and create other values if appropriate:
|
534 $z for ISBN |
|
|||
| │ | │ | └ | <ptr target="___"> | [optional] In the value of target, provide a URI for the source document. For example, this could be link to a facsimile of the source document. | 856 $u when 2nd indicator = 2 and $3 = “Source” | n/a | |||
| │ | ├ | <series> | [recommended] If applicable, give information about the series to which the source document bibliographic item belongs, given according to the descriptive cataloging standard used. | ||||||
| │ | │ | ├ | <title level="s"> | [recommended] Contains the title of the series. Whenever possible, establish or use the authorized form of the title from a name authority file. Use of the type attribute is optional, but if it is used, it should follow the instructions for use of this element in P5. | 534 $f |
|
|||
| │ | │ | ├ | <biblScope unit="volume"> | [recommended] If applicable, use for volume numbering of the source document within the series. | 534 $f |
|
|||
| │ | │ | ├ | <idno type="ISSN"> | [recommended] If applicable, use for an ISSN for the series. | |||||
| │ | │ | └ | <ptr target="___"> | [optional] In the value of target, provide a URI for a catalog record for the source document. | |||||
| │ | └ | <relatedItem> <biblStruct> | [recommended] If applicable, describe a work related to the source document, following the guidelines for the components of the <biblStruct> that is a child of <sourceDesc>. |
|
|
||||
| │ | └ | <listRelation> | [optional] Use <listRelation> with <relation> child elements to express any FRBR entities and relationships relating to the TEI document (see section 4.1.5, The TEI Header and FRBR, above). | n/a | n/a | ||||
| ├ | <encodingDesc> | [recommended] | n/a | n/a | |||||
| │ | ├ | <projectDesc> <p> | [optional] Include a description of the purpose for which the electronic file was encoded. | 500 | n/a | ||||
| │ | ├ | <schemaRef url="___"> | [recommended] Documents the encoding level according to these Best Practices. Use the url attribute for the value that indicates the encoding level:
|
|
n/a | ||||
| │ | ├ | <editorialDecl> | [optional] |
n/a | n/a | ||||
| │ | │ | ├ | <correction status="___" method="___"> | [optional] A <correction> element may be used to describe what corrections, if any, have been made to the source text, and how they were made. | n/a | n/a | |||
| │ | │ | ├ | <hyphenation eol="___"> | [optional] A <hyphenation> element may be used to describe how both soft and hard hyphens have been recorded. | n/a | n/a | |||
| │ | │ | ├ | <normalization method="___"> | [optional] One or more <normalization> elements may be provided to explicitly declare the extent of normalization or regularization. | n/a | n/a | |||
| │ | │ | ├ | <punctuation marks="___" placement="___"> | [optional] A <punctuation> element may be provided to explicitly declare whether punctuation marks have been retained or replaced by markup, and if retained where they have been placed with respect intra-paragraph elements. | n/a | n/a | |||
| │ | │ | ├ | <quotation> | [optional] A specialization of the <punctuation> element, the <quotation> element may be provided to explicitly declare whether quotation marks have been retained as content or not. Optionally use the <marks> attribute. | n/a | n/a | |||
| │ | │ | ├ | <p> | [optional] Include up to one <p> element for each of the
following in the order given, addressing in prose:
|
|
n/a | |||
| │ | ├ | <tagsDecl> | [recommended] | n/a | n/a | ||||
| │ | │ | ├ | <rendition selector="___" scheme="css"> | [recommended] Include one or more <rendition> elements to indicate the default renditions of various elements in the source document. Use the selector attribute to indicate to which elements this rendition should be applied. Alternatively, use an xml:id attribute and point to it from a rendition attribute. | n/a | n/a | |||
| │ | │ | └ | <namespace name="http://www.tei-c.org/ns/1.0"> <tagUsage> | [recommended] This element should have one and only one child <tagUsage> element for describing the encoding of logical divisions, which
should be one of the following:
|
n/a | n/a | |||
| │ | └ | <classDecl> <taxonomy xml:id="___"> <bibl> | [optional] Use to document classification schemes and controlled vocabularies referenced
by a scheme attribute elsewhere in the header or body of the TEI
document. For example:
|
||||||
| │ | ├ | <samplingDecl> <p> | [optional] Used to record a prose description of the rationale and methods used in selecting texts, or parts of text, for inclusion. | 500 | n/a | ||||
| │ | ├ | <appInfo> <app> | [optional] Used by external processes to record information about themselves and the changes they have made to the file. | ||||||
| │ | ├ | <listPrefixDef> <prefixDef ident="bptl" matchPattern="L([1-5])-v(\d+\.\d+\.\d+[aαβb]?)" replacementPattern="http://www.tei-c.org/SIG/Libraries/teiinlibraries/$2/"> | [recommended] Defines the “bptl:” prefix used on the value of the url attribute of the <schemaRef> element. Additional <prefixDef> elements may be specified if other private URI schemes are to be used. | ||||||
| ├ | <profileDesc> | [optional] | n/a | n/a | |||||
| │ | ├ | <langUsage> | [optional] Use this element and child <language> elements to list languages used in the text. This supplements the xml:lang attribute on the <text> (which is outside the header) in cases where more than one language is used in the text. It is not expected that the <langUsage> element will contain any description of language usage. | n/a | n/a | ||||
| │ | │ | └ | <language ident="___"> | [optional] Use one or more <language> elements to indicate language(s) used in the source document. Use of the ident attribute is required as in P5. Since the value of this attribute is usually sufficient to indicate the language, the <language> element should normally have no content. In the unusual case where ident is insufficient, provide additional information about the language as content of the element. |
|
|
|||
| │ | └ | <textClass> | [optional] | n/a | n/a | ||||
| │ | ├ | <classCode scheme="___"> | [optional] True classification numbers as opposed to call numbers may be entered here.
The value of the scheme attribute corresponds to a classification scheme defined previously
in <classDecl>. Example: scheme="#LCC" |
050-099 | 050-099 | ||||
| │ | └ | <keywords scheme="___"> | [optional] Repeat this element as many times as there are keyword schemes. The value of
the scheme attribute is a URI for a controlled or uncontrolled
vocabulary. The URI may be absolute to a version online or to one defined previously in
<classDecl>. Example: scheme="#LCSH" |
6xx 2nd indicator or 6xx $2 when 2nd indicator = 7 | 6xx 2nd indicator or 6xx $2 when 2nd indicator = 7 | ||||
| │ | └ | <term> | [optional] Use for terms from controlled or uncontrolled vocabularies as defined according to the containing <keywords> element. | 6xx | 6xx | ||||
| │ | <xenoData> | [optional] Use as a wrapper for embedded non-TEI metadata. | n/a | n/a | |||||
| └ | <revisionDesc> <change when="YYYY-MM-DD" who="[URI]"> | [optional] Create a <change> element to record each significant change to the TEI document, in reverse chronological order (i.e., most recent first). A prose description of the change is recorded as the content of each <change> element. This prose may contain lists for organization, and phrase-level markup (like <gi>, <ptr>, or <date>), but not paragraphs. The date of the change should be recorded using the when attribute (see att.datable.w3c class). The person who is responsible for making the change should be indicated by the who attribute of <change>. Its value is
a URI that points to a <respStmt> or <person> that encodes information about the responsible party. Note that
this reference is a URI, not an IDREF, and thus is typically not checked by validation
software. Small projects sometimes take advantage of this by putting information into the
URI itself, and not having a <respStmt> or <person> element. For example, the document might simply give
|
n/a | n/a | |||||
In the examples given in the description of each encoding level below, XML comments are illustrative, and are not meant to be included in encoded documents. Here is an example of such a comment:
<!-- uncorrected OCR for first page image begins here -->
Note that for technical reasons the namespace is not shown in these examples, but it should always be supplied on the root <TEI> element, e.g.:
<TEI xmlns="http://www.tei-c.org/ns/1.0">
To create electronic text with the primary purpose of keyword searching and linking to page images. The primary advantage in using the TEI at this very strictly limited level of encoding is that a TEI header is attached to the text file.
The text is subordinate to the page image, and is not intended to stand alone as an electronic text without accompanying page images. Level 1 texts are not intended to be adequate for textual analysis; they are more likely to be suited to the goals of a preservation unit or mass digitization initiative. These texts are meant to be a faithful representation of the appearance of the source document derived from OCR, providing the basis for subsequent encoding at Level 2 or higher of these Best Practices.
Texts at Level 1 can be created and encoded by fully automated means. Page images are scanned and processed using OCR, but the text is generally left uncorrected (“dirty OCR”) and the XML is generated from the OCR output. If desired, such automated output can be enhanced by tagging individual page elements to indicate key textual features, such as a title page, front matter, or the start of a new chapter.
| <sourceDoc> | [recommended] There should be only one element following the <teiHeader>, a single <sourceDoc> containing a raw transcription of the text of the source document. |
| <surface> | [recommended] Defines a written surface as a two-dimensional coordinate space. There should be one <surface> for each encoded page, whether it is represented via a facsimile image file, a transcription, or, most likely, a textual representation obtained from OCR. |
| <zone> | [optional] A two-dimensional region. May be used to divide a <surface> or <line> into two dimensional regions, e.g. a column, a dropped initial capital, or a word of interest. A <zone> may itself be divided into <line>s or <zone>s. |
| <line> | [recommended] Contains text appearing in a single physical line on the page. |
See section 3.8, Linking Between Encoded Texts and Images of Source Documents.
Note that this is a ‘syntactically conformant’ customization, in that documents that are valid against this scheme will also be valid against the TEI_all schema. However, it is unclear whether or not it is truly ‘TEI conformant’, as P5 does not make clear whether or not encoding of individual paragraphs is mandatory.
To create electronic text for full-text searching, linking to page images, and identifying simple structural hierarchy to improve navigation. (For example, you can generate a table of contents automatically from such encoding.)
The text is mainly subordinate to the page image, though navigational markers (textual divisions, headings) are captured. However, the text could stand alone as electronic text (without page images) if the accuracy of its contents is suitable to its intended use and it is not necessary to display low-level typographic or structural information. Use cases for Level 2 require a set of elements more granular than those of Level 1, including bibliographic or structural information below the monographic or volume level. One of the motivations for using Level 2 is to avoid expensive analysis of textual elements and/or the expense of accurate text conversion, e.g., double-keying or detailed proofreading of automatic OCR.
For the most part, though, Level 2 texts are not intended to be displayed separately from their page images. Level 2 encoding of sections and headings provides greater navigational possibilities than Level 1 encoding, and enables searching to be restricted within particular textual divisions (for example, searching for two phrases within the same chapter).
Level 2 generally can be created and encoded by automated means. Pagination is identified as in Level 1, and metadata for the textual divisions is created, likely based on the page images. The textual division metadata might contain the page number on which the division begins and a transcription of that division's heading. This metadata is inserted into the OCR at the appropriate points, forming a valid XML document. Level 2 texts do not require any special knowledge or manual intervention below the section level.
Optionally use the elements specified in Level 1. In addition, use the following:
| <text> | [recommended] Used as a wrapper for the encoded transcription of the source document. |
| <front>, <back> | [optional] Contains one or more <div> or <div1>. |
| <body> | [recommended] Contains one or more <div> or <div1>. |
| <div1> or <div> | [recommended] One <div> or <div1> is used per section of the text identified with division-level metadata. If no type attribute is specified, a type value of section should be presumed. |
| <head> | [recommended] Use if headings are present. As in P5, this element must appear before the <ab> for that division. |
| <ab> | [recommended] There should be only one child of the <div> (or <div1>): a single <ab> wrapping all of the OCR text. If the TEI document is ever ‘upgraded’ to Level 3 or higher, the <ab> element will be replaced by structural elements like <p> and <table>. |
| <lb> | [optional] Indicates the beginning of a new line. |
| <cb> | [optional] indicates the beginning of a new column. |
Note that this is intended to be a ‘TEI conformant’ customization, per P5, section 23.3.
To create a stand-alone electronic text and identify hierarchy (logical structure) and typography without content analysis being of primary importance.
Encoding at this level provides the foundation for upgrading to higher levels of encoding. Level 3 generally requires some human editing, but the features to be encoded are determined by the logical structure and appearance of the text and not specialized content analysis.
Level 3 texts identify front and back matter, textual divisions, and all paragraph breaks. Floating texts (sub-texts like a poem or letter embedded in the greater text) are supported in this level. The finer granularity of encoding these features, as well as figures, notes, and all changes of typography, allows a range of options for display, delivery, and searching. For example, one has the option of identifying, and therefore specifying, the display characteristics of different typographic styles, and regularizing the display and placement of note text.
Level 3 texts can stand alone as text without page images and therefore can be uploaded, downloaded, and delivered to users quickly. In addition, they require less storage space than digital collections with page images. However, the simple level of structural analysis and absence of specialized content analysis reflected in Level 3 encoding may make it desirable for some, depending on project priorities, to include page images in order to provide users with a fuller set of resources on the source document.
Level 3 texts can be created by semi-automated conversion from an electronic source such as an HTML file or word-processor document or from a print source, either through OCR or keyboarding; some human intervention is likely necessary. Level 3 texts can also be generated trivially by converting from outsourced double-keyboarded texts conforming to TEI Tite, though some granularity of encoding will be lost in the translation.
Use all elements specified in Level 2 except <ab> as defined for that level, plus the following:
| <front>, <back> | [recommended] Use if front or back matter is present. |
| <div> or <div1> | [recommended] At least one <div> or <div1> is recommended within each of <front>, <body>, and <back>; type attribute is recommended. If a bibliography is included in the document, it is recommended that it be encoded within a <div> whose type attribute has the value bibliography. |
| <p> | [recommended] Use for paragraphs in prose. |
| <lg> and <l> | [recommended] Use for identifying groups of lines and lines, respectively. |
| <figure> and appropriate child elements | [recommended] Use to refer to illustrative images and descriptive information about those images. |
| <floatingText> | [optional] Use to indicate a floating text. |
| <note> | [recommended] Use for notes. |
| <ptr> or <ref> | [recommended] If a table of contents is encoded, <ptr> or <ref> is recommended for linking to sections of the document. If notes are encoded at the point they occur in the text or at another point convenient when converting from a born-digital source document, recommended for encoding the point of reference. |
| <hi> | [recommended] Indicates changes in typeface; rend attribute is optional. |
| <list> and <item> | [optional] Use to indicate ordered and unordered list structures. |
| <table>, <row>, and <cell> | [optional] Use to indicate table structures. |
| <listBibl> | [recommended] If a bibliography is present and encoded, use for identifying the bibliographic entries. Note that any header or title should be encoded by a <head> in the containing <div>. |
| <bibl> | [recommended] Contains a single bibliographic entry. Phrase level markup (e.g., <hi>) is optional. Further structural markup (e.g., <author>) is not used at level 3. |
Running heads, catch words, page numbers, signatures, and other artifacts derived from printing should not be included in Level 3, with the exception of page numbers, which are recorded using the n attribute on <pb>. If upgrading a text from Level 1 or Level 2 that was generated using OCR, discard any forme work text.
<figure> groups elements representing or containing graphic information such as an illustration or figure. A <figure> should contain the following elements:
You may wish not to include in your TEI document front matter such as a table of contents or a list of illustrations, especially if you plan to automatically generate these from the encoded text. If you do, however, plan to manually encode such textual features, use a <div> (or <div1>) element with an appropriate type attribute (e.g., <div type="contents">) to surround the encoding of the feature. Within this division, use the <list> element to mark up the table of contents, list of illustrations, etc. Each list item should have a <ptr> or <ref> element with a target attribute referencing an xml:id attribute on the <pb> or on the <div> (or <div1>) of the referenced page or section. Use <ref> if you wish to transcribe page numbers in the table of contents; use <ptr> if you do not.
Use the <note> element to encode the text of a margin note, footnote, endnote, or other note found in the source document. If a point of attachment is marked with a siglum (such as an asterisk or superscript number), encode the siglum with a <ref> element. Alternatively, if there is no marked point of attachment, insert a <ptr> at the most likely implied point of attachment for the note.
The text of the note (inside a <note> element) may either (a) be left where it occurs in the layout of the page (as may be more convenient in the case of conversion from OCR text) or may (b) be moved so that the <note> occurs just following the <ref> or <ptr> marking the point of attachment. If a note span pages, be sure to insert a <pb> to mark the start of a new page. Similarly, if the note in the source document begins on a different page from the place of reference, a <pb> should be inserted before the first word of the note within the <note> to record this.
The siglum is often repeated at the beginning of the note to aid the reader in matching the siglum in the text to the note. Encode any siglum within the note using <label>.
And then the annotations themselves, encoded as <note> elements inside a division in the backmatter that holds the endnotes:
Note that this is intended to be a ‘TEI conformant’ customization, per section 23.3 of P5.
To create text that can stand alone as electronic text, identifies hierarchy and typography, specifies the function of textual and structural elements, and describes the nature of the content and not merely its appearance. However, this level is not meant to encode or identify all structural, semantic, or bibliographic features of the text.
Greater description of function and content at this level of encoding allows for:
Level 4 texts contain elements and attributes that describe content, not just appearance, of the text. Texts encoded at Level 4 are able to stand alone without page images in order for them to be read by students, scholars, and general readers, and the encoding of content allows these texts to work effectively with screen readers and other applications that rely on the structure of a text, not just its appearance.
Finally, functionally accurate encoding in Level 4 texts allows them to be searched or displayed in sophisticated ways. For example, perhaps a searcher could limit their search in a dramatic text to stage directions or in a verse text to only first lines. Alternatively, in a political tract published by subscription, a search could be confined to names that appear in lists, thus limiting a search to names of people who subscribed to a particular volume. This ability to limit searches becomes more significant as textbases become larger, and thus is of great importance to the library community as it attempts to build into the initial design and implementation of textbases the features needed to enhance interoperability.
Text is generated by keyboarding (likely outsourced double keyboarding from page images using TEI Tite) or possibly by correcting OCR text using software that identifies spelling mistakes or consults a log from the OCR software to find regions of uncertainty in the OCR text. If converting from TEI Tite, minimal additional markup should be added, as discussed in Appendix A of TEI Tite.
Use all elements specified in Levels 2 and 3 except <ab> as defined for Level 2, plus elements in the following table. Note that some of these elements are defined in Level 3 as well, but their use in Level 4 is more strict.
| <titlePage> and appropriate child elements | [recommended] |
| <group> | [recommended] Use to encode a collection of independent texts that are regarded as a single group for processing or other purposes. |
| <div>or<div1>, <div2>, <div3>, etc. | [recommended] Use for encoding a hierarchy of textual divisions. Use as many levels of hierarchy as needed to represent the source document. |
| <floatingText> | [recommended] Use when a floating text is identified. |
| <list> and <item> | [recommended] Use to indicate ordered and unordered list structures. |
| <table>, <row>, and <cell> | [recommended] Use to indicate table structures. |
| <hi> | [recommended] Use to indicate change in rendition when a more specific element is not being used; rend attribute is optional. |
| <opener>, <dateline>, <salute><closer>, <signed>, <postscript> | [recommended] Use to indicate specific parts of letters. |
| <castList>, <castItem>, <sp>, <speaker>, and <stage> | [recommended] Use to encode different structures in performance texts (i.e. drama). |
| <sp> and <speaker> | [recommended] Use to encode oral history interviews. |
| <epigraph> | [recommended] Use for encoding epigraphs found as front matter |
| <quote rend="___"> | [recommended] Use for encoding blockquotes that appear outside the flow of a paragraph. Use style, rendition, or rend to describe the appearance (such as <style="padding-left: 0.5in;">) |
| <argument> | [recommended] Use to encode a list of topics sometimes found at the start of a chapter or other textual division. |
| <trailer> | [recommended] Use to encode a closing title or footer at the end of a division. |
| <quote>, <said>, <mentioned>, and <soCalled> | [optional] |
| <emph>, <distinct>, <foreign>, <gloss>, and <term> | [optional] |
| <title type="_"> | [optional] Use of this element within the <text> (not the <teiHeader>) is optional, especially when text is typographically distinct. Optionally use the type attribute with a value as given in P5 except for main titles. (The main value should be used, when appropriate, for <title>s within a TEI header, but is not needed for <title>s elsewhere in a document.) |
| <ptr> or <ref> | [optional] In addition to using to point to notes (as in Level 3), use for identifying cross-references within the text. |
| <sic>, <corr>, or <choice> | [optional] Use to encode errors or typos. |
| <add>, <del>, <gap>, and <unclear> | [optional] Use to encode material that is added, marked for deletion, or is illegible, invisible, or inaudible. |
| <persName>, <placeName>, <geogName>, <orgName>, and <name type="___"> | [optional] Use to encode personal, place, organizational, and other names used in a text. The <persName> element is also used to indicate a personal name inside a <person> element (see below). |
| <listName>, <listPlace>, and <listOrg> | [optional] Use in support of personal, place, and organizational names normalization and to capture additional information about the names. Should be captured in an external TEI file or database for easier maintenance of names. |
| <listPerson> | [optional] Use in support of transcriptions of oral interviews. |
| <person> | [optional] Use in support of transcriptions of oral interviews. The use of the role attribute is strongly recommended, particularly to differentiate interviewer(s) from interviewee(s). |
| <birth> | [optional] Use inside a <person> to indicate the date or place of birth of the person being documented. |
| <bibl> | [optional] Contains a single bibliographic entry. Use of at least one <author> or <editor> child element is recommended. Other valid child elements given in P5 may also be used to encode a bibliographic citation, such as <title>, <publisher> and, <biblScope>. It is recommended that the <date> always appear with a when attribute in order to provide a canonical form of the date. |
| <ab type="typography"> | [recommended] Use to mark typographical elements that indicate a structural break or boundary. |
As shown above, there are many optional elements at Level 4. While content for many of these elements can be identified within running prose based on changes in typography or use of quotation marks in the source document, they are not always so easily identified, or they may occur so often that identification of each instance is impractical. Use only those optional elements that are appropriate for your users' needs and your encoding budget.
Encode each section of front and back matter as their own textual division. Beyond what is described in the P5 Guidelines, note the following:
Names should be encoded using <persName>, <placeName>, <geogName>, and <orgName> elements. For names of entities other than persons, places, and organizations, use <name> with a type attribute containing an appropriate value, such as event for the name of an event.
For all of these elements, use the ref attribute (see section 3.9.3 above) to provide a reference to a <person>, <place>, <org>, <event>, or other element in an external file or database for managing name normalization and compilation of additional information such as biographical or geospatial information. An external TEI file may contain an entry for each name, grouped accordingly under <listPerson>, <listPlace>, <listOrg>, or <listEvent>, with each name uniquely identified with an xml:id attribute. In this case the value of the ref attribute in the main TEI document (the transcription of the source document) references the value of the xml:id attribute in the external file. (In the examples below, the external file is named context.xml for ‘contextual information’ and is in the same directory as the source file, but it may be named anything and placed anywhere that can be referenced by a URI.)
When referencing external files or databases by tag URI, it is strongly recommended to provide an explanation in a <p> element in the <editorialDecl> section of the TEI header. When referencing a controlled vocabulary by relative URI, be sure to specify the controlled vocabulary in the <classDecl> section of the TEI header.
If the embedded text is more than a short quotation, use <floatingText> even if the instance is still only an excerpt of the embedded text.
Within the front matter (<front>) of a performance text, cast lists should be encoded as <castList>s, with each item in that list encoded as a <castItem>. If desired, each <castItem> may be uniquely identified with an xml:id attribute.
Within the body of performative texts:
The list of participants in the transcription of an oral history may be encoded in the body of the TEI document using the structured <listPerson> element containing <person> elements for each participant. Alternatively, the list of participants may be encoded as a free-form <list> in the body. The latter approach is especially useful when the list is included in the source document in an unstructured form.
If an oral history document has no title of its own, the speakers in oral history interviews, i.e., interviewee(s) and interviewer(s), may also be identified in the <teiHeader> as a list of <author> elements (typically each with its own <persName>) within <fileDesc> / <titleStmt>.
Regardless, use an xml:id on the <persName> element to uniquely identify the individual participant.
Questions and answers from interviewees and interviewers are encoded as <sp>, with each speaker identified either:
Use <lg> and <l> as in Level 3. In addition, use the style, rendition, or rend attribute to indicate lines that are indented.
Like <pb> elements, these should always be placed within the lowest-level text division.
Level 5 texts are those that require substantial human intervention by encoders with subject knowledge. These texts might include encodings of semantic, linguistic, prosodic, or other features well beyond the basic structural elements discussed for Levels 1-4 above. They might also include elements for editorial, critical, or analytical additions; manuscript descriptions; translations; or other textual apparatus.
To create deeply analytical encoded texts that might be appropriate for specific research purposes, as part of a scholarly publishing project, or for other encoding practices in library-based text encoding.
A significant number of library-based projects engage in high-level analytical text encoding as part of their efforts in digitization, scholarly editing, academic support, or other research. Level 5 is intended to represent that work, which can take advantage of the full richness of the complete TEI Guidelines (P5), while still acknowledging the impact of library-specific practices on encoded text that is created under the auspices of a library.
Because of the vast range of possibilities for Level 5 encoding, these Best Practices have chosen to provide neither a list of recommended elements nor any specific examples for encoding a transcription of a source document at this level. Please refer to the TEI Header section above for recommendations for the <teiHeader>.
Those encoding Western European early modern printed material may find that TEI simplePrint, a TEI customization, provides appropriate guidance for encoding a transcription of the source document. Otherwise, refer to the General Recommendations section above and the Complete TEI P5 Guidelines for element recommendations and usage examples within the <text>.
This document is the result of a group of individuals with a range of experience with TEI text encoding, which formed together under the TEI Special Interest Group on Libraries and Digital Library Federation umbrellas. We would like to thank and acknowledge all of those who have given their time and expertise to develop these Best Practices.
The individuals who served as editors of this document are:
The individuals who have contributed to the writing of this document are:
The individuals who have contributed to the planning of this document are:
The individuals who have contributed complementary tools to this document are:
The individuals who have contributed to copyediting of this document are:
Lastly, we would like to thank the Digital Library Federation (DLF) for sponsoring two in-person meetings as part of the Spring 2008 Forum in Minneapolis, Minnesota, and the Spring 2009 Forum in Raleigh, North Carolina, in support of our revision work. The DLF also provided teleconferencing support for our regularly scheduled meetings.
This document was formerly known as TEI Text Encoding in Libraries Guidelines for Best Encoding Practices.
The Text Encoding Initiative Guidelines for Electronic Text Encoding and Interchange (referred to as the TEI Guidelines) were first published in 1994 and represent a tremendous achievement in electronic text standards by providing a highly sophisticated structure for encoding electronic text. Digital librarians have benefited greatly from the standardization provided by these guidelines, and the potential for interoperability and long-term preservation of digital collections facilitated by their wide adoption.
In 1998, the Digital Library Federation (DLF) sponsored the TEI and XML in Digital Libraries Workshop at the Library of Congress to discuss the use of the TEI Guidelines in libraries for electronic text, and to create a set of best practices for librarians implementing them. From this workshop, three working groups were formed, the members of which represented some of the largest and most mature digital library programs in the U.S.
Group 1 was charged to recommend some best practices for TEI header content and to review the relationship between the Text Encoding Initiative header and MARC. To this end, representatives of the University of Virginia Library and the University of Michigan Library gathered in Ann Arbor in early October 1998 to develop a recommended practice guide. This work was assisted by similar efforts that had taken place in the United Kingdom under the auspices of the Oxford Text Archive the previous year. The section on the header is based on a draft of those recommended practices. It was submitted to various constituencies for comment. In 2008 and 2009, it was heavily revised by Melanie Schlosser, Kevin Hawkins, and other members of the TEI SIG on Libraries.
Group 2 was charged with developing a set of recommendations for libraries using the TEI Guidelines in electronic text encoding. This group included the following representatives from six libraries:
At the ALA Midwinter Meeting (January 1999), the DLF task force revised a draft set of best practices, called TEI Text Encoding in Libraries: Guidelines for Best Practices (often referred to as TEI in Libraries Guidelines). The revised recommendations were circulated to the conference working group in May 1999 and presented at the joint annual meeting of the Association of Computers and the Humanities and Association of Literary and Linguistic Computing in June 1999. Version 1.0 was circulated for comments in August 1999. These guidelines were endorsed by the DLF, and have been used by many digital libraries, including those of the task force members, as a model for their own local best practices. Libraries, museums, and end-users have benefitted from a set of best practices for electronic text in a number of ways, including better interoperability between electronic text collections, better documented practices among digital libraries, and a starting point for discussion of best practices with commercial publishers regarding electronic text creation.
Written in 1998, this first iteration of TEI in Libraries Guidelines made no mention of XML, XSLT, or any of the other powerful tools that have now become common parlance and practice in creating digital documents and collections. Based on these important changes in markup technology, it came to the attention of the DLF and members of the original Task Force that the TEI in Libraries Guidelines required substantial revision. In 2002, the TEI Consortium published a new edition of the complete TEI Guidelines that conformed to XML specifications. In order to remain useful, the TEI in Libraries Guidelines had to be updated to reflect these developments.
Furthermore, librarians need more guidance than the original TEI in Libraries Guidelines provided. There are many library-specific encoding issues which need to be addressed and documented to ensure consistency. The intention of this document is to provide recommended paths of encoding for these issues.
In addition, these library guidelines have the potential to be much more useful if they can serve as a training document from which librarians can learn about text encoding and addressing particular encoding challenges. To fulfill this role, the guidelines require more examples and detailed explanations, giving documentation of the use of TEI in a library context. Librarians also need a set of standards and best practices for vendors and publishers who create electronic text for digital libraries, so that these collections adhere to the same archival standards as locally-created electronic text collections. With detailed guidelines that could serve as an encoding specification, librarians might encourage vendors to follow the principles in these standards, to facilitate the long-term preservation of commercially published electronic text collections, and more readily allow for cross-collection searching.
In order to facilitate the evolution of this document, another DLF-sponsored Task Force—some of the representatives of which were on the original Task Force—met on October 24-25, 2003 at the Cosmos Club in Washington, D.C.:
These representatives met to revise the original TEI in Libraries Guidelines in order that they:
After producing Version 2.0 of the Guidelines, this group (with some changes in membership) met again at the Cosmos Club on February 13-14, 2006. Those in attendance were:
The group then released Version 2.1 in March 2006.
In April 2008, select members from the TEI Consortium Libraries Special Interest Group (SIG) and the DLF-sponsored TEI Task Force partnered to update the Best Practices. The revision was prompted by the release of P5, the newest version of the TEI, and the desire to create a true library-centric customization of the TEI. The group convened for a DLF-sponsored meeting at the Spring Forum in Minneapolis, Minnesota to tackle the revision work. Those in attendance were
Work continued through conference calls, in which Renee McBride (University of North Carolina, Chapel Hill) and Richard Wisneski (Case Western University) also participated, and at a DLF-sponsored meeting that took place as part of the DLF Spring Forum in Raleigh, North Carolina on May 6, 2009.
In April 2009, a year after the revision work began, the significantly revamped Best Practices, soon to be known as Best Practices for TEI in Libraries (version 3.0), were disseminated for public comment. At the DLF Spring Forum in Raleigh, a Birds-of-a-Feather session entitled TEI Text Encoding in Libraries was held to gather in-person public feedback. Comments received at the in-person meeting, from the TEILIB-L listserv, through a survey, and by direct email were gathered and prioritized at the DLF meeting. Renee McBride (University of North Carolina, Chapel Hill) agreed to map header elements to MARC elements, and Vitus Tang (Stanford University) provided valuable comments. In addition to addressing most of the comments received, it was resolved that Syd Bauman would generate an ODD document (containing both schema constraints and prose) for levels 1-4, further ensuring interoperability of texts encoded according to these Best Practices.
Version 3.0 contained updated versions of the widely adopted encoding ‘levels’ — from fully automated conversion to content analysis and scholarly encoding. They also contained a substantially revised section on the TEI header, designed to support interoperability between text collections and the use of complementary metadata schemas such as MARC. Furthermore, they explored the relationship between METS and TEI and the relationship between these Best Practices and the new vendor specification, TEI Tite.
The new Best Practices also reflected an organizational shift. Originally authored by the DLF-sponsored TEI Task Force, the new revision was a partnership between members of the Task Force and the TEI SIG on Libraries. As a result of this partnership, responsibility for the Best Practices moved to the SIG, allowing closer work with the TEI Consortium as a whole and a stronger basis for advocating for the needs of libraries in future TEI releases.
At its meeting in November 2015, the SIG decided to undertake a revision to these Best Practices. A workgroup met approximately monthly from early 2016 to 2018 to carry out this work, releasing version 3.1.0a in November 2017 and version 4.0.0 in September 2018.