LEMDO: Build and Customize an Anthology

Build and Customize an Anthology

In the LEMDO universe, an anthology is a collection of texts along with supporting information and documentation, presented through a web interface which is based on a set of defaults, but is customized through CSS styling, menu configuration, and so on.

¶ The lemdo-dev Anthology

The lemdo-dev anthology is a special instance which includes all the texts that exist in the repository, whatever their state of development. It is never published at any formal URL, but is available through a continuous integration build server which enables everyone working on any LEMDO project to see the latest state of their own data. The process of building lemdo-dev also detects and reports errors, invalidities and other problems related to any texts in the collection.

¶ Other Anthologies

All other anthologies exist as subfolders of the data/anthologies folder in the LEMDO repository. Each anthology is based primarily on these features:

A subfolder in data/anthologies named for the id of the anthology (for example qme or dre).

A TEI Corpus file (a TEI file whose root element is


                                                <teiCorpus>

rather than


                                                <TEI>

), with an


                                             @xml:id

attribute identical to the anthology id. This file contains several key components:


                                                      <teiHeader>

element which holds the anthology-level metadata (the anthology editor(s), publication statements, etc.).

A hard-coded


                                                      <TEI>

element with


                                                   @xml:id

="{anthId}_index". This file contains the content for the anthology home page. The presence of this


                                                      <TEI>

element makes the anthologyʼs


                                                      <teiCorpus>

valid.

A sequence of import instructions in the form of Processing Instructions, looking like this: <?lemdo-import ref="emdFV_edition"?>. Each one of these points to the id of an edition file, whose contents are to be published in the anthology.

A collection of other XML files populating folders within the anthology folder, each of which consists of a TEI document that is to be turned into a web page in the rendered anthology site. These are all in the category ldtBornDigital, and they have filenames and IDs beginning with the anthology ID followed by an underscore. All such files found in the anthology folder will be converted into web pages. Note that these files are also transformed as part of the regular lemdo-dev build, so you can see them in their default state in that build; when the anthology itself is built, those files will be converted to the anthology rendering style, and will have their prefixes removed (so qme_index.html will become simply index.html in the products/qme/site output folder).

A site folder containing all the site-level customizations which apply to the anthology output, including template/sitePage.html, which will form the basic template for all pages in the site. This is where the banner, menu, footer and other standard site components are defined. Other folders include images, for images needed on the site; fonts, for any specialized fonts that need to be included; and css, which contains one or more SCSS files which will be transformed to CSS using SASS, and added to the output pages after the standard CSS inherited from the main lemdo-dev project, enabling a designer to override any display defaults. There should be one main SCSS file named {anthId}.scss which imports any other files and that will be built into {anthId}.css and linked into all the output files.

¶ Build Process

The build process for anthologies is quite complex:

Before anything else happens, the main lemdo-dev build process must run. This processes all the texts and identifies problems that might need to be rectified before an anthology build can proceed.

Next, the main build process runs a diagnostic for each anthology that is in the repository, checking to see whether it is in a state where it can be successfully built. That process produces two outputs: an HTML file (products/{anthId}/anthologyStatus.html) which lists problems found, and a text file (products/{anthId}/anthologyStatus.txt) which simply says "OK" or "FAIL". The checking process is described below.

The anthology file itself is then checked for two things: the


                                                <revisionDesc>


                                             @status

for the anthology itself must be set to "published", and so must the


                                                <revisionDesc>


                                             @status

attribute in the first embedded


                                                <TEI>

element which contains the home page content. If either of these is not published, the build does not proceed.

The anthology home page, which is the TEI element embedded in the anthology configuration corpus file, is processed into a page in a temporary folder.

Each item in the collection of site-page XML documents located in the anthology folder is first checked to make sure its


                                                <revisionDesc>


                                             @status

value is "published".

Each LEMDO edition which is claimed by the anthology (using a lemdo-import processing instruction, as described above) is processed as follows:

The edition file itself is checked to ensure that it has a


                                                      <licence>

element which permits the inclusion of the edition file itself in the anthology. This is an example of such a


                                                      <licence>

element:

<licence resp="pers:JENS1" from="2020-10-21" corresp="anth:dre"> This content is licensed for inclusion in the DRE anthology. </licence>

The text inside the


                                                      <licence>

element is informational and not required; the key components are a person taking responsibility for the licence, a starting date for it, and a pointer to the target anthology using the


                                                   @corresp

attribute and the anth prefix. The build process checks only that there is at least one valid


                                                   @resp

value in the attribute. It does not have any way to know whether the person concerned actually has the right to make such a declaration; this check is the responsibility of the anthology lead.

The


                                                      <revisionDesc>


                                                   @status

value for the edition file is checked to make sure it is set to "published".

If the edition is allowed for inclusion and is published, it is then parsed, and each text linked from it is checked for the same licence permission and publication status.

At this point, we have a complete list of all the documents needed for the anthology, but they are all in the vanilla lemdo-dev style etc. These documents are then processed into the output directory. During this process, all boilerplate components such as banners, menus, footers and so on are replaced with those from the anthologyʼs sitePage.html template file, and the anthologyʼs CSS and JS files are added into the headers of the files.

A post-build diagnostics process is now run on the built site to check that every link points to something which is where it is expected to be, and every file is valid. (Not yet implemented.)

¶ Customizing Anthologies

To customize the functionality and appearance of your anthology, you will need to have a complete checkout of the repository, and you must be working on a computer which is set up to run the required software. Practically speaking, this means that you need either a Linux or Mac operating system (Windows is not able to run required scripts), and you will need both curl and DART-SASS installed and working from the command line. Of course you will also need an svn client in order to check out and commit to the repository, as well as a NetLink ID and permission to commit to the required folders. In addition, if you want to follow the recommended working method described below, you will need to have ant and ant-contrib installed.

There are three aspects of an anthology that can be customized:

Some components of the basic HTML framework used to create pages can be changed, by editing the file data/anthologies/{anthId}/template/sitePage.html. This file basically contains a banner/header, a site menu, and a footer; these are used to replace the generic versions that come from the lemdo-dev build pages.

The style/design/appearance of the site can be modified by editing the SCSS file lemdo/data/anthologies/{anthId}/site/css/{anthId}.scss. This file is compiled to create {anthId}.css, which is then placed in the css folder in the anthology build output, and linked into the HTML files after the default lemdo-dev.css file, so that it can be used to override any rules in that file.

Site functionality can be customized by editing the file lemdo/data/anthologies/{anthId}/site/js/{anthId}.js, which is linked into the HTML files after any other JS, so it can override (for example) object methods and add new functionality.

¶ A Suggested Working Method for Customization Work

For developers or designers working on customization, we suggest the following working method.

First of all, if you are only working on the CSS, images, fonts and/or the JavaScript, you do not need to run a complete site build yourself. You can download a pre-built version of the site from our Jenkins server to your local machine, then make changes and simply rebuild the CSS. This is how: (In the following, {anthId} means the id of the target anthology, such as dre or qme.)

At the command line, in the lemdo folder, run the following command:

./getSiteFromJenkins.sh {anthId}

This will download a complete copy of the latest build of the anthology from the Jenkins server, and place it in the products folder inside the lemdo folder. The main site content appears in the site subfolder. You can view this content directly in a browser, but if you want to work on JavaScript interactivity, you may need to run a local web server in that folder so that browsers will permit all the code to run. Most developers will be familiar with this situation.

Now that you have a local copy, you can make changes to the CSS and JavaScript code in the lemdo data/anthologies/{anthId}/site folder, then run this command to update the local site and see your changes:

ant -f build_anthology.xml updateAnthology -Danthology.id={anthId}

This will copy all JS, images, and font files over to the local built site, and run SASS to build the SCSS file to create a CSS file in the css folder.

Once you are happy with the changes youʼve made, you can commit them to the svn repository (donʼt forget to svn add any new images or fonts files), and then Jenkins will rebuild the site in due course.

If you are editing the site template, then the process is much more complex, because every page will need to be rebuilt before your changes will appear. In that case, you will also need a complete local copy of the base lemdo-dev anthology. You can get that by running: ./getSiteFromJenkins.sh.

That will give you a copy of the lemdo-dev site, which is the source from which the anthology pages are built. After editing the anthology site template file in data/anthologies/{anthId}/template/sitePage.html, run this command to rebuild your entire anthology:

ant -f build_anthology.xml -Danthology.id={anthId} -DbuildFailedAnthologyAnyway=true
                                          buildAnthologies

This process may take a little time, depending on the size of your anthology.

Prosopography

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.

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.

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	Build and Customize an Anthology
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.