Structure of a Single Documentation File
Introduction
Documentation files are unique compared to other files in the LEMDO repository because
they are rooted on the
<div>
element rather than the
<TEI>
element. This structure allows us to compile entire documentation chapters into one
Web page as described in The Relationship between Documentation and the ODD File.Note that the structure of documentation files are slightly different from the other TEI files that you may have worked on with LEMDO.
Unlike other TEI files, documentation files do not contain a
<teiHeader>
, a
<text>
element, or a
<body>
element. Instead, we provide metadata by linking to the ODD file (see The Relationship between Documentation and the ODD Fileand
Give Credit for Documentation Files) and encode all of our documentation content in
<div>
elements nested inside the root
<div>
.While you may nest
<div>
elements further to create a hierarchical structure in documentation files, LEMDO
advises against a deeply nested structure. If you find that you need to nest more
than sub-sections in a file, consider either reworking the content or, for complex
topics, dividing the content between multiple pages. If you do decide to make multiple
files rather than one very long file, remember that we can link between those files.Other than the differences necessitated by being rooted on a
<div>
element, the structure that we use in our documentation files is very similar to
that of LEMDO’s critical paratexts (see Structure of Critical Paratexts). The elements that we use to organize content and create structure in documentation files are:
<div>
(always with an
@xml:id attribute and a child
<head>
element)
<p>
<list>
<table>
Divisions
Sections (divisions) encoded using the
<div>
element are the highest-level structural unit of LEMDO documentation files. Each
documentation file is rooted on a
<div>
element that must contain a child
<head>
element1 and usually contains at least one child
<div>
element.XML is hierarchical and works by nesting content in a series of containers. In LEMDO
documentation, those containers are
<div>
elements. It is important to understand how to nest
<div>
elements to create structure with subsections when writing and encoding documentation.
We recommend plotting the structure of your document prior to encoding it so that
you have a good idea of how to arrange your content into sections and subsections
using
<div>
elements.Practice: Give xml:ids to Divisions in Documentation
Each
<div>
element must have an
@xml:id attribute with a logical value. As with all xml:ids in the LEMDO project, the xml:ids
on
<div>
elements in documentation must all start with the root xml:id for the file followed
by an underscore and then a unique value. Oxygen will give you a validation error
if an xml:id does not begin with the file’s xml:id. See Create a Unique Value for an xml:id Attribute.
If you have nested
<div>
elements, you may find it most clear to begin the xml:id for nested
<div>
elements with the xml:id of its predecessor, but this is not enforced with validation.
Note that following this practice quickly makes xml:ids unwieldy in deeply-nested
divisions. If you notice that your xml:ids are becoming overly long, it may be a sign
that you should reorganize the content in the file so that it does not contain deeply-nested
divisions.It is important to keep xml:ids unique, short, and descriptive. We use xml:ids to
create stable URLs for entities and to link to those entities. By keeping them short
and descriptive, we make it easier to link between documentation files.
Follow these principles to keep xml:ids short:
Think carefully about nesting
<div>
elements within
<div>
elements. Do you need deeply nested divisions? Is the content actually a set of paragraphs
or a list? One advantage of creating a new
<div>
is that we can link to it from elsewhere, but think about whether we really need
to link to the very specific information that would be contained within a deeply nested
<div>
or if users might more profitably be pointed to a higher level in the hierarchy.Be economical in the wording of the xml:id.
The final part of the xml:id on a
<div>
needs to be similar to the text node of the
<head>
element but does not have to replicate it. If possible, choose a single representative
word from the heading.The following example shows the xml:ids for a documentation file with the xml:id
"learn_encodeTerm". Note that each xml:id begins with the root
<div>
’s xml:id and ends with a short and unique descriptor:
<div xml:id="learn_encodeTerm" ana="audEncoder">
<head>Encode Terms</head>
<div xml:id="learn_encodeTerm_rationale">
<head>Rationale</head>
</div>
<div xml:id="learn_encodeTerm_practice">
<head>Practice: Tag Terms</head>
</div>
</div>
<head>Encode Terms</head>
<div xml:id="learn_encodeTerm_rationale">
<head>Rationale</head>
</div>
<div xml:id="learn_encodeTerm_practice">
<head>Practice: Tag Terms</head>
</div>
</div>
Practice: Add Section Headings
Every section of a documentation file must have a heading, tagged with the
<head>
element. Add an appropriate heading for that section of the document in the text
node of the
<head>
element.At processing time, the division heading is turned into the section heading on the
Web page and is added to the page’s table of contents. In addition, it is added as
hyperlinked text everywhere that the section is linked to using a
<ptr>
element.On the Web page, the hierarchy of
<div>
elements determines the level of heading for each section. Functionally, the hierarchy
impacts the formatting of the headings. Headings that are higher in the hierarchy
(e.g., the heading for the root
<div>
element) are displayed in a larger font while headings that are lower in the hierarchy
(e.g., the heading for a
<div>
element that is nested inside another
<div>
) are displayed in a smaller font.Tips for Encoding Divisions
You must close the
<div>
elements in your documents in the same order that you opened them. Since the first
<div>
element is the largest container, its opening and closing tags must enclose all the
other
<div>
elements. Be careful when closing
<div>
elements because a misplaced closing
<div>
tag can, in rare cases, disrupt the content hierarchy without being invalid. Furthermore,
it is easy to lose sight of your opening
<div>
tag in a long, complex document. Errors are most likely to occur when you are moving
<div>
elements and their contents to new places in your document. When moving elements
and their contents, you may well accidentally disrupt your document hierarchy.Strategies you can use to avoid misplaced closing tags:
Add tags by using the
Ctrl+E (Cmd+E on Mac) keyboard shortcut rather than manually typing in each opening and closing
tag.Use the
Outline viewin Oxygen (Window → Show View → Outline) and filter for
<div>
elements (by typing div in the filter box).Paragraphs
The basic structural unit within the
<div>
element is the paragraph, wrapped in the
<p>
element. Three paragraphs will often suffice instead of three divisions with headings,
especially if the paragraphs convey information that an editor or encoder is likely
to read as a unit. In other words, paragraphs are the obvious way of organizing information
when you do not want to split the information across multiple
<div>
elements.Prose is the default mode of writing documentation, but do think carefully about how
people will need to receive the information. You are not writing an argument. You
are giving explanations and instructions. Instructions are often for step-by-step
procedures and often include
forks in the roadwhere an editor has to make a forced choice between options. Step-by-step procedures lend themselves to numbered lists. Forced choices lend themselves to nested lists. A paragraph may contain a list and/or nested lists. A paragraph may be used to introduce or comment on a list.
Lists
Lists are an excellent way to organize information in documentation. They are highly
readable on screen and make it easy for readers scanning for a solution to find what
they need. If you find that you are creating comma-separated prose lists, consider
turning them into formal lists, wrapped in the
<list>
element with each item wrapped in the
<item>
element.Conversely, do not encode as lists long blocks of text that are really paragraphs.
If you find that your list items are becoming long, then consider converting the list
back to paragraphs or even to small
<div>
elements with
<head>
elements to guide the reader to the right information.Decide whether your list should be independent of a paragraph or embedded within a
paragraph. Consider the information in this table when deciding whether to embed a
list in a paragraph or keep it separate:
| Lists Independent of Paragraphs | Lists Embedded in Paragraphs |
| Usually longer | Usually shorter |
| Extrinsic to the paragraph in terms of content | Intrinsic to the paragraph in terms of content |
| Probably not discussed in the next paragraph | Discussed in the remainder of the paragraph |
Example: List independent of paragraph
<div>
<!-- ... -->
<p>Running prose about something.</p>
<list rend="bulleted">
<item>Item</item>
<item>Item</item>
</list>
<p>Running prose about something.</p>
<!-- ... -->
</div>
<!-- ... -->
<p>Running prose about something.</p>
<list rend="bulleted">
<item>Item</item>
<item>Item</item>
</list>
<p>Running prose about something.</p>
<!-- ... -->
</div>
Example: List embedded in paragraph
<div>
<!-- ... -->
<p>Running prose introducing the list: <list rend="bulleted">
<item>Item</item>
<item>Item</item>
</list> Running prose commenting on the list.</p>
<!-- ... -->
</div>
<!-- ... -->
<p>Running prose introducing the list: <list rend="bulleted">
<item>Item</item>
<item>Item</item>
</list> Running prose commenting on the list.</p>
<!-- ... -->
</div>
Types of Lists
LEMDO permits numbered, bulleted, and simple lists. All
<list>
elements should have a
@rend attribute specifying the type of list.Use
"numbered" as the value on the
@rend attribute if the items in the list are in a particular order (a step-by-step process
whereby one step must be completed before the next step) or if enumerating items is
important. In the latter case, there might be a preceding comment and an introductory
colon.
<div>
<!-- ... -->
<p>Follow these three steps: <list rend="numbered">
<item>Step One described.</item>
<item>Step Two described.</item>
<item>Step Three described.</item>
</list>
</p>
<!-- ... -->
</div>
<!-- ... -->
<p>Follow these three steps: <list rend="numbered">
<item>Step One described.</item>
<item>Step Two described.</item>
<item>Step Three described.</item>
</list>
</p>
<!-- ... -->
</div>
Use
"bulleted" as the value on the
@rend attribute if the items are not sequential or ordered in any particular way:
<div>
<!-- ... -->
<p>Tips for Encoding: <list rend="bulleted">
<item>Learn keyboard shortcuts to save time.</item>
<item>Update (<code>svn up</code>) often.</item>
<item>Use the outline view in Oxygen to quickly see the structure of your file.</item>
</list>
</p>
<!-- ... -->
</div>
<!-- ... -->
<p>Tips for Encoding: <list rend="bulleted">
<item>Learn keyboard shortcuts to save time.</item>
<item>Update (<code>svn up</code>) often.</item>
<item>Use the outline view in Oxygen to quickly see the structure of your file.</item>
</list>
</p>
<!-- ... -->
</div>
Simple lists have neither numbers nor bullets. We generally discourage the use of
simple lists because they have no distinguishing feature that marks them as a list
in the HTML output, other than indentation and a new line beginning. They are less
useful for the scanning reader than the two other types of lists.
Tables
Tables are an excellent way to display information. Use tables to convey information
that requires the user to look up something in order to learn how to encode or edit
that particular thing. For example, the list of abbreviations for various bibliographic
<idno>
elements lends itself to a two-column list with the name of the bibliographic resources
(e.g., Short Title Catalogue) in the first column and the abbreviation (STC) in the second.Tables have the advantage of being sortable in alphabetical and reverse alphabetical
order on either column. The table foreseen in the preceding paragraph would give the
editor or encoder the ability to sort on the second column if they need to know the
details of the value on an
<idno>
, or to sort on the first column if they know the name of the resource and want to
discover its
<idno>
value.Tables may have a
<head>
element. Use the first
<row>
element (with the
@role attribute and the "label") to label the columns. Each subsequent
<row>
will have the "data" value and must have the same number of cells as the
<row>
with the "label" value.Note that tables with more than four columns do not render well in our HTML output
and are therefore less usable to the editor/encoder.
To encode a table, use the following model:
<table>
<head>Optional Head</head>
<row role="label">
<cell>Head of first column</cell>
<cell>Head of second column</cell>
</row>
<row role="data">
<cell>Data for first column of first row</cell>
<cell>Data for second column of first row</cell>
</row>
<row role="data">
<cell>Data for first column of second row</cell>
<cell>Data for second column of second row</cell>
</row>
</table>
<head>Optional Head</head>
<row role="label">
<cell>Head of first column</cell>
<cell>Head of second column</cell>
</row>
<row role="data">
<cell>Data for first column of first row</cell>
<cell>Data for second column of first row</cell>
</row>
<row role="data">
<cell>Data for first column of second row</cell>
<cell>Data for second column of second row</cell>
</row>
</table>
Notes
1.Note that the root
<div>
element’s child
<head>
provides the title for the entire documentation page. This is the name that will
be listed in the documentation index and that will be generated as hyperlinked text
when the page is linked to using a
<ptr>
element.↑Prosopography
Illya
Illya has a BA in English and Sociocultural Anthropology and an MA in English. Prior
to joining the HCMC, he was a PhD candidate in English and Book History at the University
of Toronto and worked on Records of Early English Drama and on the Modernist Archives Publishing Project. His work at the HCMC focuses on creating web-based applications for research projects
led by members of the faculty of Humanities at the University of Victoria. This involves
creating schemas for new and existing datasets, writing XSLT and build files to transform
datasets into structured TEI and HTML formats, implementing staticSearch, and ensuring
that new projects are Endings Principles compliant.
Isabella Seales
Isabella Seales is a fourth year undergraduate completing her Bachelor of Arts in
English at the University of Victoria. She has a special interest in Renaissance and
Metaphysical Literature. She is assisting Dr. Jenstad with the MoEML Mayoral Shows
anthology as part of the Undergraduate Student Research Award program.
Janelle Jenstad
Janelle Jenstad is a Professor of English at the University of Victoria, Director
of The Map of Early Modern London, and Director of Linked Early Modern Drama Online. With Jennifer Roberts-Smith and Mark Beatrice Kaethler, she co-edited Shakespeare’s Language in Digital Media: Old Words, New Tools (Routledge). She has edited John Stow’s A Survey of London (1598 text) for MoEML and is currently editing The Merchant of Venice (with Stephen Wittek) and Heywood’s 2 If You Know Not Me You Know Nobody for DRE. Her articles have appeared in Digital Humanities Quarterly, Elizabethan Theatre, Early Modern Literary Studies, Shakespeare Bulletin, Renaissance and Reformation, and The Journal of Medieval and Early Modern Studies. She contributed chapters to Approaches to Teaching Othello (MLA); Teaching Early Modern Literature from the Archives (MLA); Institutional Culture in Early Modern England (Brill); Shakespeare, Language, and the Stage (Arden); Performing Maternity in Early Modern England (Ashgate); New Directions in the Geohumanities (Routledge); Early Modern Studies and the Digital Turn (Iter); Placing Names: Enriching and Integrating Gazetteers (Indiana); Making Things and Drawing Boundaries (Minnesota); Rethinking Shakespeare Source Study: Audiences, Authors, and Digital Technologies (Routledge); and Civic Performance: Pageantry and Entertainments in Early Modern London (Routledge). For more details, see janellejenstad.com.
Joey Takeda
Joey Takeda is LEMDO’s Consulting Programmer and Designer, a role he assumed in 2020
after three years as the Lead Developer on LEMDO.
Mahayla Galliford
Project Manager, 2025-present; Assistant Project Manager, 2024-2025; Research Assistant,
2021-present. Mahayla Galliford (she/her) graduated from the University of Victoria
with a BA (honours with distinction) in 2024, and an MA English in 2026. Mahayla’s
undergraduate research explored early modern stage directions and civic water pageantry.
Her SSHRC-funded MA thesis project focuses on transcribing, editing, and encoding
early modern girls’ manuscripts, specifically Lady Rachel Fane’s May Masque in collaboration with LEMDO.
Martin Holmes
Martin Holmes has worked as a developer in the UVic’s Humanities Computing and Media
Centre for over two decades, and has been involved with dozens of Digital Humanities
projects. He has served on the TEI Technical Council and as Managing Editor of the
Journal of the TEI. He took over from Joey Takeda as lead developer on LEMDO in 2020.
He is a collaborator on the SSHRC Partnership Grant led by Janelle Jenstad.
Navarra Houldin
Training and Documentation Lead 2025–present. LEMDO project manager 2022–2025. Textual
remediator 2021–present. Navarra Houldin (they/them) completed their BA with a major
in history and minor in Spanish at the University of Victoria in 2022. Their primary
research was on gender and sexuality in early modern Europe and Latin America. They
are continuing their education through an MA program in Gender and Social Justice
Studies at the University of Alberta where they will specialize in Digital Humanities.
Nicole Vatcher
Technical Documentation Writer, 2020–2022. Nicole Vatcher completed her BA (Hons.)
in English at the University of Victoria in 2021. Her primary research focus was women’s
writing in the modernist period.
Samuel Seaberg
Samuel Seaberg, a University of Victoria English undergrad, enjoys riding his bike.
During the summer of 2025, he began working with LEMDO as a recipient of the Valerie
Kuehne Undergraduate Research Award (VKURA). Unfortunately, due to his summer being
spent primarily in working to establish an edition of Thomas Heywood’s If You Know Not Me, You Know Nobody, Part 2 and consequently working out how to represent multi-text works in a digital space,
his bike has suffered severely of sheltered seclusion from the sun. Note: Samuel now
works for LEMDO as the Assistant Project Manager, much to his bike’s chagrin.
Tracey El Hajj
Junior Programmer 2019–2020. Research Associate 2020–2021. Tracey received her PhD
from the Department of English at the University of Victoria in the field of Science
and Technology Studies. Her research focuses on the algorhythmics of networked communications. She was a 2019–2020 President’s Fellow in Research-Enriched
Teaching at UVic, where she taught an advanced course on
Artificial Intelligence and Everyday Life.Tracey was also a member of the Map of Early Modern London team, between 2018 and 2021. Between 2020 and 2021, she was a fellow in residence at the Praxis Studio for Comparative Media Studies, where she investigated the relationships between artificial intelligence, creativity, health, and justice. As of July 2021, Tracey has moved into the alt-ac world for a term position, while also teaching in the English Department at the University of Victoria.
Orgography
LEMDO Team (LEMD1)
The LEMDO Team is based at the University of Victoria and normally comprises the project
director, the lead developer, project manager, junior developers(s), remediators,
encoders, and remediating editors.
Metadata
| Authority title | Structure of a Single Documentation File |
| Type of text | Documentation |
| Publisher | University of Victoria on the Linked Early Modern Drama Online Platform |
| Series | Linked Early Modern Drama Online |
| Source |
TEI Customization created by Martin Holmes, Joey Takeda, and Janelle Jenstad; documentation written by members of the LEMDO Team
|
| Editorial declaration | n/a |
| Edition | Released with Linked Early Modern Drama Online 1.0 |
| Encoding description | Encoded in TEI P5 according to the LEMDO Customization and Encoding Guidelines |
| Document status | prgGenerated |
| Funder(s) | Social Sciences and Humanities Research Council of Canada |
| License/availability |
This file is licensed under a CC BY-NC_ND 4.0 license, which means that it is freely downloadable without permission under the following
conditions: (1) credit must be given to the author and LEMDO in any subsequent use
of the files and/or data; (2) the content cannot be adapted or repurposed (except
in quotations for the purposes of academic review and citation); and (3) commercial
uses are not permitted without the knowledge and consent of the editor and LEMDO.
This license allows for pedagogical use of the documentation in the classroom.
|