Chapter 3. Document structure

Version 3.1 (19 July 2020) – cf. version 3.0 (12 December 2019)

by Matthew Driscoll, Rune Kyrkjebø and Odd Einar Haugen

3.1 The structure of the manuscript vs. the structure of the work

Viewed as physical objects, rather than as vehicles for texts, manuscripts have a certain structural hierarchy. What is regarded as a single manuscript may in fact comprise more than one volume; Flateyjarbók, for example, is bound in two volumes, and the large rímur codex Acc. 22 in three. A manuscript book is made up of quires or gatherings, each of which contains a number of leaves, normally eight. Each leaf has a recto side and a verso side, and each side may be further divided into columns. The text is then written in lines across the page or column. In order to be able to locate a word quickly and easily, all, or at least most, of these structural divisions must be registered. We need to know that a given word appears e.g. in the fifth line of the right-hand or b column on the recto side of folio 34. As it is customary to foliate manuscripts without regard to their quire division, the quires will not normally need to be included in the hierarchical structure, but since the quiring can have implications for the text itself this division should be indicated, and will also generally form part of the <msDesc> element, found in the document header.

At the same time, of course, manuscripts obviously do contain texts, which is the reason why most of us are interested in them in the first place. A single manuscript will often contain more than one work, each of which may, in the case of lengthy prose works such as sagas, be divided into chapters or sections. In the case of Medieval Icelandic poetry, rímur for example, a single work (rímnaflokkur) will usually consist of several cantos or fits, each containing a number of stanzas, made up of a number of lines. It may be necessary to group these lines in some other ways as well. The stanzas comprising the mansöngur should be distinguished from the main body of the fit, for example, while to facilitate certain types of metrical analysis it might be desirable to divide the individual stanzas into couplets. Some types of poetry, such as the vikivakakvæði, will have a refrain or burden, which should ideally also be distinguished from the narrative section(s) of the stanza.

XML has at its foundation the notion of a text as a single hierarchical structure, which means that it does not work well where there are several concurrent hierarchies, as is obviously the case when one wishes for example to indicate the line divisions both in a poem and in the manuscript in which the poem is contained. The TEI Guidelines offer various solutions to this problem, enabling both the structure of the document and the structure of the text to be encoded.

3.1.1 Hierarchical divisions

The principal means of representing hierarchy is the <div> (i.e. “division”) element. <div> elements may freely nest within each other. The <div> element has, in addition to the universally available @id and @n attributes, a @type attribute, which specifies the name conventionally given to the level of division, e.g. ‘chapter’, ‘stanza’, ‘couplet’, if attempting to represent the structure of the text, or ‘page’, ‘column’, ‘line’ if the physical structure of the manuscript is to be preferred. It will be convenient to specify a value for the @type attribute in the <div> element at least each time a change of level occurs. The software, however, will keep count of the levels of nesting even if the type attribute is not used.

The complex structure of a work such as a set of rímur could be represented by using four levels of <div> elements, <div type="canto"> for the cantos or fits, <div type="part"> for the parts (for example the mansöngvar), <div type="stanza"> for the stanzas, and <div type="line"> for the lines. If the manuscript being encoded contains more than one set of rímur, as is frequently the case, it might be sensible to use <div type="canto"> for each set. A simpler form of mark-up is possible, however. Instead of <div> elements, the <l> element (for “line”) and the <lg> element (for “line-group”, i.e. a group of lines functioning as a formal unit) can be used, reserving the <div> element for larger structural units. The @type attribute is then used to identify the type of unit, e.g. ‘stanza’, ‘couplet’, like in <lg type="stanza">. Here again the type need only be defined once. Lines and line-groups can also be numbered and identified using the @n and @id attributes.

This type of markup focusses on the hierarchical structure of the text. The actual physical realisation of the text is considered of secondary importance – if of importance at all – when dealing with modern printed literary works: little significance is attached to the page and line beginnings in the various editions of, say, Orwell’s Nineteen Eighty-Four. In some cases, however, the early editions of Joyce’s works, for example, supervised by the author himself, the physical make-up of the text can be of great consequence. It may also be necessary to maintain the pagination and lineation of standard editions of major works, as these are frequently used in citations in scholarly works. In the case of chirographically transmitted material, the physical organisation of the text is more likely to be recognised as being of importance and in need of encoding. This can be done hierarchically, as above, using <div> elements, which are then given the appropriate @type attributes, e.g. ‘page’, ‘column’ or ‘line’, but it seems more appropriate to reserve these elements for structural divisions in the text, while indicating the physical structure of the document through the use of so-called “milestone” elements, i.e. <pb/>, <cb/> and <lb/>. These elements make up a separate hierarchy in the file and help to overcome the problem of overlapping structures in the mark-up; see also the discussion in ch. 16 below.

The rest of this chapter presents how the text may be encoded at higher structural levels than characters and words. Important elements here are the larger divisions of the text, like chapters, paragraphs (with headings), and stanzas. This chapter also presents how pagination and foliation, together with column and line beginnings, may be encoded. The following TEI elements are presented:

We will also discuss a few other elements which are relevant for the document structure:

3.2 Main divisions of a TEI document

The following presentation is based on the TEI P5 Guidelines, ch. 4.

A TEI document is always at its highest level enclosed by the start tag <TEI> and the end tag </TEI>. Within the <TEI> element, two other elements appear in a fixed order, namely the <teiHeader> and the <text> elements. Within the <text> element, the body text may appear, enclosed in the element <body>. If the text has front matter, there will be an element <front>, placed before <body> containing it. Similarly, there may be an element <back>, placed after <body> and containing back matter. The elements <teiHeader>, <text> and <body> are required in any TEI-conformant document, while <front> and <back> are optional. This, then, is the basic structure of a TEI document:

3.2.1 Another possible first division of the text: More than one <text> element

The transcriber may want to divide a document into more than one text. This can be done with the <group> element, which should be contained in the top level <text> element taking the place of <body> in the simpler scheme illustrated above. The following structure appears:

<text xml:lang="en">
  <front>. . .</front>
  <group>
    <text xml:lang="en">
      <front>. . .</front>
      <body>. . .</body>
      <back>. . .</back>
    </text>
    <text xml:lang="en">
      <front>. . .</front>
      <body>. . .</body>
      <back>. . .</back>
    </text>
  </group>
  <back>. . .</back>
</text>

The main structure of the text, at the levels of work, first main division, second main division, first chapter of first main division, second chapter of first main division and so on, can be encoded in different ways. If the electronic document consists of more than one work, the <group> structure illustrated above is the natural choice. In that case, one would get multiple sets of further structural divisions, one set within each of the <body> elements. If the electronic document is considered as a single work, and placed in one <text> element, there will only be a single <body> element that needs further divisions.

Each major section of a text, <front>, <body> and <back>, must have a minimum of contents, such as one or more <div> elements for chapters, and within each <div> element, one or more <p> elements containing paragraph text.

3.3 Chapters: <div>

Further division of the <body> block is achieved through <div> elements, with one level nesting inside the other as the transcriber moves down through the hierarchical structure of the text.

3.3.1 Type- and level-specified <div> elements

In a complex document, <div> elements may be specified by @type and @n attributes. In this example, the three first chapters of a work have been contained in <div> elements at the same hierarchical level (siblings):

3.3.2 Unspecified <div> elements

It is also possible to use <div> elements without specifying their type:

3.3.3 Nesting <div> elements

Note that <div> elements may nest inside each other. For example, the levels of work, chapter and then paragraph can be encoded in the following manner:

While <div> elements may nest as shown here, <p> elements may not. They must be encoded sequentially, i.e. as siblings.

3.4 Paragraph text: <p>

The basic-level element for prose text is the paragraph, <p>. Typically, the deepest level <div> element will contain one or more <p> elements:

The <p> element may appear in other contexts, such as in the <teiHeader> element. It may also contain a number of other elements, but – as underlined above – it may not contain other <p> elements, i.e. it is not allowed to nest.

3.5 Sentences: <s>

The text within a paragraph may be divided into sentences, <s>:

In TEI XML encoding, paragraphs are usually not divided into sentences, but will simply list the words in sequential order. However, if one would like to divide a text into sentences, an operational sentence definition is needed. Since the subject is not an obligatory constituent in Medieval Nordic, a single, finite predicate may be regarded as the basic sentence criterion, e.g. Rignir ‘It rains’. In the case of sentences linked by conjunctions (such as ok, en and eða) one might decide to declare a new sentence whenever there is a subject as well as a predicate following the conjunction. See Haugen and Øverland 2014, pp. 65–67, for a discussion of sentence boundaries in Old Norwegian (and, by extension, in Medieval Swedish and Danish).

3.5.1 Linking sentences in two files

If a medieval text is going to be linked to a translation, one may divide each file into chapters, using the <div> element, or into sentences, using the <s> element. Any smaller units such as words, would not be advisable. When linking sentences in two files, each <s> element should have an @xml:id attribute with corresponding values in each file. The following is a simplified example from a Christmas homily in the Old Norwegian Homily Book:

Old Norwegian text (AM 619 4to, fol. 16v, l. 9–10):
<s xml:id="s748">
  <w>Ec</w> <w>var</w> <w>grafen</w> <pc>.</pc>
  <w>ok</w> <w>ræis</w> <w>ec</w> <w>upp</w> <w>af</w> <w>dauða</w> <pc>.</pc>
</s>
 
Modern Norwegian translation (by Astrid Salvesen, 1971):
<s xml:id="s748">
  Jeg ble begravet,
  men stod opp fra de døde.
</s>

Note that while Medieval Nordic texts in Menota will have each word in a <w> element, this is not called for in a translation (unless the translated text should be searchable to the same extent as the medieval text).

3.5.2 Conflicts in the linking of sentences

If more than two files are going to be linked to the original XML file, for example one containing a translation and one containing a syntactic analysis, and if the division of sentences in these files are partly overlapping (which is highly likely), we recommend using the empty <milestone/> element for sentence divisions that do not correspond. The <milestone/> element must have a @unit attribute and (we suggest) an @n attribute with the same function as the @xml:id attribute in the <s> element. This way, conflicting sentence structures can be encoded without problems of overlap:

<s xml:id="s1" n="m1">
  this is one way of encoding the text
<milestone unit="sentence" n="m2"/>
  even if there are other ways of doing it
</s>
<s xml:id="s2">
  they may be rare
<milestone unit="sentence" n="m3"/>
  in spite of any efforts to come up with convincing examples
</s>
<s xml:id="s3">
  one should be able to suggest a valid encoding
<s xml:id="s4" n="m4">
  fortunately, sometimes sentence divisions are identical
</s>

The above example is an encoding of partly conflicting sentence divisions in two files. The primary file uses the <s> element with the @xml:id attribute (capitalisation and punctuation have been added for clarification):

[s1] This is one way of encoding the text, even if there are other ways of doing it.
[s2] They may be rare, in spite of any efforts to come up with convincing examples.
[s3] One should be able to suggest a valid encoding.
[s4] Fortunately, sometimes sentence divisions are identical.

The sentence division in the additional file can be encoded by a <milestone/> element with the @n attribute. Note that this attribute is also used in the <s> element wherever the sentence divisions are corresponding, such as between the 3rd and 4th sentence:

[m1] This is one way of encoding the text.
[m2] Even if there are other ways of doing it, they may be rare.
[m3] In spite of any efforts to come up with convincing examples, one should be able to suggest a valid encoding.
[m4] Fortunately, sometimes sentence divisions are identical.

The solution recommended here is analoguous to the division of a text into <div> elements and then adding another division, that of pages and lines, in milestone elements such as <pb/> and <lb>.

3.6 Words: <w>

Although words need not be delimited by anything else than white space, we recommend placing each word in a <w> element. This will be helpful for word constituent analysis as well as for any morphological (and lexicographical) annotation.

If the text is going to be annotated for morphology it is necessary to establish the exact word boundaries. The <w> element may be given several morphological attributes, in particular @lemma for the dictionary entry and @me:msa for the grammatical form. These attributes are discussed in ch. 11.2 and ch. 11.3 below.

Another motivation for delimiting words by the <w> element is the fact that a number of graphical words (i.e. sequences of characters with space on either side) should be split or merged according to standard dictionaries, e.g. “aveiðiskap” for “á veiðiskap” and “veiði kona” for “veiðikona”. Splitting and merging of graphical words will be discussed in ch. 5.3 below. The encoding of word constituents will also be discussed here.

If the text is transcribed on a single level, typically the diplomatic level, no specification within the <w> element needs to be made. If, however, the transcription comprises more than one level of transcription, each level should be clearly marked. It is recommended, but not strictly necessary, to place these levels within a <choice> element (cf. ch. 3.13 below). In a multi-level encoding, each <w> element thus includes several other elements, <choice> for stating the fact that the contents of this element are alternatives, <me:facs> for rendering on a facsimile level, <me:dipl> for rendering on a diplomatic level, and <me:norm> for rendering on a normalised level. See ch. 4.6 for examples of multi-level encoding. (The “me:” part of the latter element name means that they are part of the name space established for Menota, as explained in ch. 2.8 above.)

Hyphenation of words is discussed in ch. 5.5 below.

3.7 Punctuation: <pc>

We recommend that punctuation characters are encoded in the same manner as words.

If the text is transcribed on a single level, typically the diplomatic level, no specification within the <pc> element needs to be made. However, if the transcription comprises more than one level of transcription, each level should be clearly marked. The procedure is identical to the one specified for words above. See ch. 5.4 below for more details.

3.8 Metrical text: <lg> and <l>

The elements discussed here are defined and explained in the TEI P5 Guidelines, ch. 6.

Texts in verse should be encoded using <lg> (line group), which in turn contains one or more <l> elements (lines). As with <div>, <lg> elements can nest. According to the TEI Guidelines, <lg> is a sibling of, i.e. at at the same level as, <p>, and cannot be contained within it (unless it appears within a <q> element). Example:

Nesting of <lg> elements is useful for marking up longer poems. When a poem consists of two levels of line groups one may encode its structure as shown here:

The <lg> and <l> elements may have several attributes, among other things for encoding information about rhyme or other metrical phenomena. See ch. 13 of this handbook for a more detailed presentation of metrical encoding.

Having <p> and <lg> as siblings can create problems for the encoding of prosimetrum texts, where lines or verse or even whole poems can appear within prose text, often as part of direct speech. However, rather than including <lg> directly within the <p> element (which would not be valid), we recommend inserting the <p> and <lg> elements within <div> elements, using one <div> for each of them:

3.9 Headings: <head>

The element <head> is used for containing headings on all levels of the document.

The level of a heading follows from the enclosing element. A <head> element within a level three <div> element, is a heading for a level three partition of the text.

It is not required that a <div> contains a head, but if the <head> element is being used within a <div>, it should be the first element, followed by one or more <p> (or <lg>) elements. There can only be one <head> element within a <div>:

<div>
  <head>. . .</head>
  <p>. . .</p>
  <p>. . .<p>
</div>

From a logical point of view, a heading is located at the beginning of a new chapter. If one accepts that the heading may be located on the same line as the end of the previous chapter, this is not uncommon in manuscripts. One should not expect headings in manuscripts to be set out with blank lines above and below as in modern print.

Ill. 3.1. A chapter heading. Landslǫg Magnúss Hákonarsonar. Holm perg 34 4to, f. 10v, l. 1–10.

In ill. 3.1, the heading, which is written in red, is located after the end of one chapter and at the beginning of a new chapter. The sequence of elements is thus straight-forward (beginning with the 5th line in the illustration):

<div>
   . . .
  <p>
    raðe litizt annat loglegare
  </p>
</div>
<div type="chapter">
<head type="rubric">Um grið a frosta þingi Capitulus</head>
  <p>
    Aller þeir menn sem i frosto þings logum oc for ero skulu i griðum
  </p>
    . . . 
</div>

The fact that the heading is a rubric has been encoded by the @type="rubric" attribute.

Unfortunately (from the point of view of the encoder) many manuscripts locate headings so that they are in conflict with this simple sequencing, for example by positioning them at the end of more than one line, or even in the middle of a line containing the beginning of one chapter and the end of the previous chapter. Examples of these complications are discussed in some detail in ch. 16.3 below.

3.10 Initials and highlighted characters: <c>

As stated in ch. 3.3 above, the structuring of a medieval manuscript into chapters is marked up by <div> elements. Each chapter is usually indicated by an initial, often decorated and in colour, and a heading, a rubric, typically in red ink, as illustrated in fig. 3.2.

3.2. Initials and highlighted characters. The Old Norwegian Homily Book. AM 619 4to, f. 47r, l. 15–24.

The initial “S” marks the opening of a new homily, while the emphasised characters mark divisions at a lower level, such as the “Д in the 4th line of the image, the “H” in the 5th line, etc. An initial as well as an emphasised character (littera notabilior) should be encoded with the <c> element.

The <c> element is discussed in ch. 5.2.3 below, while ch. 7 explains the encoding of graphical elements of initials.

See also Kirsten Berg 2010, pp. 60–66, for a discussion of initials and highlighted characters in the structuring of a manuscript text like the Old Norwegian Homily Book.

3.11 Direct speech and quotations: <q> and <quote>

Dialogue are usually set out by quotation marks in edited copy, and in the encoding of a text, we recommend that the <q> element should be used for identifying dialogue. Medieval manuscripts did not use quotation marks, so adding quotation marks is an editorial intervention which basically belongs to the normalised level of text encoding.

Quotation from other sources should be tagged with the <quote> element. This is obviously another type of editorial intervention.

A quotation mark can be regarded as a type of punctuation character, <pc>, but since quotation marks are displayed in so many different ways, we suggest that it is convenient to use an element of its own for quotation marks. See the discussion and examples in ch. 5.6 below.

In some cases, there may be a structural conflict between the opening and closing of a <q> element, such as in this example, if it were to be encoded for <s> as well as for <q>:

• Eyvindr sagðisk eigi mundu brott undan ríða, “því at ek veit eigi hverir þessir eru. Mundi þat mǫrgum manni hlǿgiligt þykkja ef ek renn at ǫllu úreyndu.” (Hrafnkels saga Freysgoða, ch. 18)

A possibe work-around is to use the general empty element <milestone/> with the obligatory @unit attribute and a @rendition attribute specifying the opening and closing quotation mark:

<s>Eyvindr sagðisk eigi mundu brott undan ríða, 
<milestone unit="turn" rendition="opening-quote"/>því at ek veit eigi hverir þessir eru.</s>
<s>Mundi þat mǫrgum manni hlǿgiligt þykkja ef ek renn at ǫllu úreyndu.</s><milestone 
unit="turn" rendition="closing-quote"/>

There are several other ways of solving this type of conflict, as we discuss at some length in ch. 16 below. See also the TEI P5 Guidelines, ch. 20.

3.12 Page, column and line beginnings: <pb/>, <cb/>, <lb/>

3.12.1 Page beginnings and column beginnings

TEI uses the empty element <pb/> to indicate a page beginning. This element has an attribute @n which can be used for the page numbers. As it is customary to refer to the manuscript leaves, rather than pages, the value of the @n attribute should indicate front or back pages (recto, verso), e.g. 1r, 1v, 2r, 2v, 3r, 3v, and so on. Column beginnings, <cb/>, should also be indicated in manuscripts with two or more columns. Recommended values for the @n attribute of the <cb/> element are “A”, “B” and so on. For texts that are going to be displayed in the Menota archive, it is necessary to add an ed="ms" attribute to specify that the page and column beginning refer to the manuscript (and not to e.g. an edition of the text). Example:

Page beginning information from, for example, a printed standard edition, can be encoded in addition to the <pb ed="ms"/> elements that refers to the manuscript itself. If one for example would like to add page beginning information from a standard edition, one should use the @ed attribute with a suitable value:

<pb ed="Standard Edition" n="1"/>

Some of the texts in the Menota archive have been encoded with more than one document structure, such as Konungs skuggsjá in AM 243 bα fol. In addition to the document structure of the manuscript, ed="ms", it has the Arnamagnæan pagination, ed="AM", the one from Finnur Jónsson’s 1920–1921 edition, ed="FJ_utg", and the one from Holm-Olsen’s 1945 edition, ed="H-O".

The relevant editions should be declared in the header. As a rule, we suggest that the edition is identified by the initials of the editor + the year of publication, e.g. FJ1920-1921, LHO1945, etc.

3.12.2 Line beginnings

Line beginnings are also indicated with an empty element, the <lb/>, which is placed at the beginning of a new line and may be numbered by using the @n attribute. For texts that are going to be displayed in the Menota archive, it is necessary to add an ed="ms" attribute to specify that the line beginnings refer to the manuscript (and not to e.g. an edition of the text):

<lb ed="ms" n="1"/>Line number one begins here.

Each page, column and line should be identified with an element at the very beginning. So for a manuscript with two columns, the three first lines in the first column on the back of the third leaf (folio) would be encoded in this manner:

<pb ed="ms" n="3v"/>
<cb ed="ms" n="A"/>
<lb ed="ms" n="1"/>This is the first line.
<lb ed="ms" n="2"/>This is the second line.
<lb ed="ms" n="3"/>This is the third line.
etc.

In other words, there should be as many <pb/> elements as there are pages, as many <cb/> elements as there are columns, and as many <lb/> elements as there are lines. We strongly discourage the use of the <lb/> element in the same way as the <br> element in HTML, in which there typically is one <br> element less than the number of lines (as the <br> element is inserted between the lines).

As discussed above, one may include more than one layer of line beginnings, for example one according to the manuscript and another according to an edition, distinguishing them from each another with the @ed attribute.

It is not uncommon for a word to be continued on the next line, with or without a hyphenation mark in the margin. In a single-level encoding, the <lb/> element will be located within the relevant <w> element, and in a multi-level encoding it will be repeated for each level. See examples of this in ch. 5.5 below.

3.13 Alternative encoding: <choice>

The <choice> element should be used whenever the encoded text string offers parallel readings. In the context of Menota encoding, there are three major instances of this, (1) words transcribed on more than one level, (2) the combination of an <orig> and a <reg> element, and (3) the combination of a <sic> and a <corr> element.

The first type is what we refer to as multi-level transcription, and it is discussed in a number of chapters, in particular ch. 4.6 below. The second type is discussed and exemplified in ch. 9.2.3 below, while the third type is treated in ch. 9.3.3.

3.14 Scribal hands: <handShift/>

While some manuscripts are written in a single hand throughout, other manuscripts are the product of two or more scribes. It is not a requirement that the transcriber identifies changes of hands, since it can be demanding to decide the number of hands and the location of the breaks between them. However, a transcriber may want to add information on hands in the document, either based on existing research or the transcriber’s own observations.

Since a shift of hands in most cases will conflict with other divisions of the text, the recommended element is an empty one, <handShift/>. This is an element of the same type as the ones discussed in ch. 3.12 above. If there are two hands in a document there will thus be a single <handShift/> element, located at the break between hand 1 and hand 2.

Information on the hands of a document can be given as part of the header in the <handDesc> element. See ch. 14.3.3 below.

3.15 Generic empty element: <milestone/>

TEI offers the generic <milestone/> element for any division of a text outside the specified ones. The type of segment delimited by the <milestone/> element should be specified by a @unit attribute.

In ch. 3.5.2 above, we have been using the <milestone/> element for additional (and partly conflicting) sentence divisions. The value of the @unit attribute has in this case been ‘sentence’.

Updates to ch. 3

On 19 July 2020, two subchapters were added on the linking of sentences between files and possible conflicts that may arise in this connection, ch. 3.5.1 and ch. 3.5.2. On the same day, a new subchapter was added on the generic empty <milestone/> element, ch. 3.15.