LEMDO: Create and Name Documentation Files

Create and Name Documentation Files

The process for creating documentation files and commiting them to the LEMDO repository differs from the process for creating and committing other types of files. This section explains how to name, create, and commit documentation files.

¶ Name Documentation Files

Name documentation files according to established LEMDO conventions. Come up with a name that is descriptive but keep it as short as possible. Begin every documentation file that you create with lemdo followed by an underscore.

Use camelCase for file names with more than one word following the underscore. Write the descriptive part of the file name (e.g. encodingQuotations) in camelCase without underscores, even if it is more than one word. Never put spaces in file names. If the name of your document contains an acronym (e.g., OED, TEI), keep the acronym in full capital letters in the file name.

Examples:

learn_encodeQuotations.xml

learn_remediateOED.xml

¶ Create an XML File and Commit it to the Repository

Move any documentation that you write in Teams into an XML file and encode it so it can appear on the site. This section explains how to add your documentation to an XML file, commit the file to the repository, and ensure that a developer publishes your documentation on the LEMDO site. See also Access the Repository and the links from that page for the relevant operating system.

Commit your encoded documentation files to the repository once they are complete and valid; otherwise, the files will exist only on your local computer. Committing documentation files to the repository is the first step to getting them to appear on the site. This process requires two steps:

adding the file to the repository (svn add)

committing this change (svn commit)

LEMDO’s repository includes a ../data/documentation/ directory containing all of our documentation files. Commit your documentation files to this directory. The organization of these files is done in a separate file, lemdo.odd, so you do not need to worry about where to place your file within the ../data/documentation/ directory. See also Add, Reorder, and Rename Documentation: The ODD File.

Whether you are creating a new file, using an existing file as a template and replacing the existing content with new content, or adding new content to an existing file, the first few steps are the same. Follow these four steps to create an XML file:

If you wrote the documentation in another platform (i.e., Microsoft Teams), make a note at the top of the shared document that the content therein is no longer the most up-to-date version. Make a link from the Teams document to the LEMDO page once the encoded documentation is visible on the site.

Ensure that you have the LEMDO repository checked out to your local computer and updated (svn up).

Open Oxygen.

Ensure that you have lemdo-all.xpr open. If not, click Project → Open Project → lemdo-all.xpr.

After completing these steps, decide whether you want to create a new file or add to an existing one and follow the corresponding instructions below.

¶ Create a New File

Choose between creating a file from scratch or using an existing file as a template. Both processes are explained in this section.

¶ Create a File from Scratch

Click File → New → XML Document → Create.

Click File → Save as. Give the document a name and save it in the documentation directory in your local copy of the repository. See also Name Documentation Files.

Add a


                                                   <div>

element as your root element and add an


                                                @xmlns

attribute to it with the value "http://www.tei-c.org/ns/1.0". Give the root


                                                   <div>

element an xml:id identical to the name of the file. See also Divisions.

Add your file to the repository (svn add) and commit your changes (svn commit).

Add a


                                                @resp

attribute to the root


                                                   <div>

element of the file. The value of the


                                                @resp

attribute is the role-specific xml:id of the technical writer and encoder. See also Give Credit for Documentation Files.

Add


                                                   <div>

and


                                                   <head>

elements as needed to structure the file. See also Structure Documentation Files.

Add

<p>

and


                                                   <list>

elements as needed, paste your content into them, and encode titles, names, etc. as required.

Tag any element names and sample code. See also Encode Sample XML.

Validate and save the file as you encode it.

Add the documentation file to the ODD file (see Add, Reorder, and Rename Documentation: The ODD File).

¶ Use an Existing File as a Template

Choose a file from LEMDO’s documentation directory and open it. Click File → Save as and save the file with a new name in the documentation directory in your local copy of the repository. See also Name Documentation Files.

Change the xml:id of the root


                                                   <div>

element to match the name of the new file. See also Structure Documentation Files.

Add your file to the repository (svn add) and commit your changes (svn commit).

Change the values of the


                                                @resp

attribute on the root


                                                   <div>

element of the file, if necessary. The value of the


                                                @resp

attribute is the role-specific xml:id of the technical writer and encoder. See also Give Credit for Documentation Files.

Change the content of the topmost


                                                   <head>

element to match the title of your document.

Add


                                                   <div>

and


                                                   <head>

elements as needed to structure the file. See also Structure of a Single Documentation File.

Add

<p>

and


                                                   <list>

elements as needed, paste your content into them, and encode titles, names, etc. as required.

Tag any element names and sample code. See also Encode Sample XML.

Validate and save the file as you encode it.

Add the documentation file to the ODD file (see Add, Reorder, and Rename Documentation: The ODD File)

¶ Add to an Existing File

You can also add your content to an existing documentation file by nesting a new


                                             <div>

by doing the following:

Choose a file from LEMDO’s documentation directory to add your content to and open it.

Add


                                                <div>

and


                                                <head>

elements as needed to structure the file. See also Structure of a Single Documentation File.

Add

<p>

and


                                                <list>

elements as needed, paste your content into them, and encode titles, names, etc. as required.

Tag any element names and sample code. See also Encode Sample XML.

Validate and save the file as you encode it.

Commit your changes.

Sometimes the addition of material warrants a change to the xml:id and filename. However, do not change the xml:id and filename of an existing file without a good reason. If you do change the xml:id and filename, be aware that:

any links to this file will need to be updated

the ODD file will also need to be updated. See Add, Reorder, and Rename Documentation: The ODD File

¶ Add, Reorder, and Rename Documentation: The ODD File

Unlike other XML files, documentation files are not automatically published on the site when you commit them. A developer has to write processing instructions in the ODD file (lemdo.odd) to include the documentation file in the build process. These processing instructions direct the ODD file to retrieve the documentation files and publish them on the site, organized into chapters and sections within chapters.

Ensure that the ODD file is updated in the following circumstances:

if you rename a file (i.e., give it a new xml:id)

if you add a new documentation file

if you split a documentation file into multiple shorter files, each with a new xml:id

Note that any changes of filename must be accompanied by a change of the value of the


                                       @xml:id

attribute. The value and the filename must be identical. Note also that any links to the file from other files in the documentation will have to be updated. In other words, changes in filenames and xml:ids need to be carefully planned and executed.

The ODD file drives the entire project. If you have not been given explicit permission by the lead developer (Martin Holmes) to edit the ODD file, do not attempt to edit the ODD file. Instead, delegate the task to a developer or to the project director (Janelle Jenstad).

¶ Delegate ODD Updates

Make a task in Teams in Developersʼ Tasks asking someone to list your new documentation file in the ODD file. Assign the task to Janelle or to any one of the Developers. On the task, provide the following three pieces of information:

the name of the file, i.e.,

the name of the new file

the new name if you have renamed a file, and its old name as well

the new names if you have split an existing file into multiple files (and indicate if you are keeping the existing (and now shorter) file or deleting it

the chapter to which the new documentation file belongs

where in the list of files in that chapter the new file belongs (before which file? after which file?)

¶ Update ODD Yourself

If you have permission to edit the ODD file, you may make the appropriate changes of filename and/or reorder files in a chapter.

Prosopography

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 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

Research assistant, remediator, encoder, 2021–present. Mahayla Galliford is a fourth-year student in the English Honours and Humanities Scholars programs at the University of Victoria. She researches early modern drama and her Jamie Cassels Undergraduate Research Award project focused on approaches to encoding early modern stage directions.

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

Project manager 2022–present. Textual remediator 2021–present. Navarra Houldin (they/them) completed their BA in History and Spanish at the University of Victoria in 2022. During their degree, they worked as a teaching assistant with the University of Victoriaʼs Department of Hispanic and Italian Studies. Their primary research was on gender and sexuality in early modern Europe and Latin America.

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.

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	Create and Name Documentation Files
Type of text	Documentation
Short title
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.