MoEML’s PDF Developer Documentation Author Tracey El Hajj Junior Programmer Tracey El Hajj Programmer Joey Takeda Programmer Martin Holmes Project Manager Ryann McQuarrie-Salik Project Director Janelle Jenstad The Map of Early Modern Londonhttp://mapoflondon.uvic.ca/includes.xmlVictoria, BC, Canada
Department of English P.O.Box 3070 STNC CSC University of Victoria Victoria, BC Canada V8W 3W1
2016University of Victoria978-1-55058-519-3 Janelle Jenstad london@uvic.ca

Copyright held by The Map of Early Modern London on behalf of the contributors.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Further details of licences are available from our Licences page. For more information, contact the project director, Janelle Jenstad, for specific information on the availability and licensing of content found in files on this site.

 Provider: University of Victoria Database: The Map of Early Modern London Content: text/plain; charset="utf-8" TY - ELEC A1 - El Hajj, Tracey ED - Jenstad, Janelle T1 - MoEML’s PDF Developer Documentation T2 - The Map of Early Modern London ET - 7.0 PY - 2022 DA - 2022/05/05 CY - Victoria PB - University of Victoria LA - English UR - https://mapoflondon.uvic.ca/edition/7.0/pdfDev_about.htm UR - https://mapoflondon.uvic.ca/edition/7.0/xml/standalone/pdfDev_about.xml TY - UNP ER - El Hajj, Tracey. MoEML’s PDF Developer Documentation. The Map of Early Modern London, Edition 7.0, edited by Janelle Jenstad, U of Victoria, 05 May 2022, mapoflondon.uvic.ca/edition/7.0/pdfDev_about.htm. Draft. El Hajj, Tracey. MoEML’s PDF Developer Documentation. The Map of Early Modern London, Edition 7.0. Ed. Janelle Jenstad. Victoria: University of Victoria. Accessed May 05, 2022. mapoflondon.uvic.ca/edition/7.0/pdfDev_about.htm. Draft. El Hajj, T. 2022. MoEML’s PDF Developer Documentation. In J. Jenstad (Ed), The Map of Early Modern London (Edition 7.0). Victoria: University of Victoria. Retrieved from https://mapoflondon.uvic.ca/editions/7.0/pdfDev_about.htm. Draft. Born Digital

The Julian calendar, in use in the British Empire until September 1752. This calendar is used for dates where the date of the beginning of the year is ambigious.

The Julian calendar with the calendar year regularized to beginning on 1 January.

The Julian calendar with the calendar year beginning on 25 March. This was the calendar used in the British Empire until September 1752.

The Gregorian calendar, used in the British Empire from September 1752. Sometimes referred to as New Style (NS). Years run from January 1 through December 31.

The Anno Mundi (year of the world) calendar is based on the supposed date of the creation of the world, which is calculated from Biblical sources. At least two different creation dates are in common use. See Anno Mundi (Wikipedia).

Regnal dates are given as the number of years into the reign of a particular monarch. Our practice is to tag such dates with calendar=regnal, and provide an equivalent date using a more systematic calendar (usually Julian) in a custom dating attribute.

 Ryann McQuarrie-Salik Ryann McQuarrie-Salik RM

Project Manager, 2020.

 Tracey El Hajj Tracey El Hajj TEH

Junior Programmer 2018-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-20 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 Linked Early Modern Drama Online team, between 2019 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.

 Joey Takeda Joey Takeda JT

Programmer, 2018-present. Junior Programmer, 2015-2017. Research Assistant, 2014-2017. Joey Takeda was a graduate student at the University of British Columbia in the Department of English (Science and Technology research stream). He completed his BA honours in English (with a minor in Women’s Studies) at the University of Victoria in 2016. His primary research interests included diasporic and indigenous Canadian and American literature, critical theory, cultural studies, and the digital humanities.

 Janelle Jenstad Janelle Jenstad JJ

Janelle Jenstad is Associate Professor of English at the University of Victoria, Director of The Map of Early Modern London, and PI of Linked Early Modern Drama Online. She has taught at Queen’s University, the Summer Academy at the Stratford Festival, the University of Windsor, and the University of Victoria. With Jennifer Roberts-Smith and Mark Kaethler, she co-edited Shakespeare’s Language in Digital Media (Routledge). She has prepared a documentary edition of 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, Renaissance and Reformation,Journal of Medieval and Early Modern Studies, Early Modern Literary Studies, Elizabethan Theatre, Shakespeare Bulletin: A Journal of Performance Criticism, and The Silver Society Journal. Her book chapters have appeared (or will appear) in Institutional Culture in Early Modern Society (Brill, 2004), Shakespeare, Language and the Stage, The Fifth Wall: Approaches to Shakespeare from Criticism, Performance and Theatre Studies (Arden/Thomson Learning, 2005), Approaches to Teaching Othello (Modern Language Association, 2005), Performing Maternity in Early Modern England (Ashgate, 2007), New Directions in the Geohumanities: Art, Text, and History at the Edge of Place (Routledge, 2011), Early Modern Studies and the Digital Turn (Iter, 2016), Teaching Early Modern English Literature from the Archives (MLA, 2015), Placing Names: Enriching and Integrating Gazetteers (Indiana, 2016), Making Things and Drawing Boundaries (Minnesota, 2017), and Rethinking Shakespeare’s Source Study: Audiences, Authors, and Digital Technologies (Routledge, 2018).

 Martin D. Holmes Martin D. Holmes MDH

Programmer at the University of Victoria Humanities Computing and Media Centre (HCMC). Martin ported the MOL project from its original PHP incarnation to a pure eXist database implementation in the fall of 2011. Since then, he has been lead programmer on the project and has also been responsible for maintaining the project schemas. He was a co-applicant on MoEML’s 2012 SSHRC Insight Grant.

Most MoEML documents, or significant fragments with xml:id attributes, can be addressed using the mol: prefix and accessed through the web application with their id + .xml.

The molagas prefix points to the shape representation of a location on MoEML’s OpenLayers3-based rendering of the Agas Map.

Links to page-images in the Chadwyck-Healey Early English Books Online (EEBO) repository. Note that this is a subscription service, and may not be accessible to those accessing it from locations outside member institutions.

Links to page-images in the English Broadside Ballad Archive (EBBA).

The mdt (MoEML Document Type) prefix used on catRef/target points to a central taxonomy in the includes file.

The mdtlist (MoEML Document Type listing) prefix used in linking attributes points to a listings page constructed from a category in the central MDT taxonomy in the includes file. There are two variants, one with the plain xml:id of the category, meaning all documents in the specified category, and one with the suffix _subcategories, meaning all subcategories of the category.

The molgls (MoEML gloss) prefix used on term/corresp points to a a glossary entry in the GLOSS1.xml file.

This molvariant prefix is used on ref/target attributes during automated generation of gazetteer index files. It points to an element in the generated variant spellings listing file which lists all documents which contain a particular spelling variant for a location.

This molajax prefix is used on ref/target attributes during the static build process, to specify links which point to MoEML resources which should not be loaded into the source page during standalone processing; instead, these should be turned into links to the XML source documents, and at HTML page load time, these should be turned into AJAX calls. This is to handle the scenario in which a page such as an A-Z index of the whole site would end up containing virtually the whole site inside itself.

The molstow prefix is used on facs attributes to link to the HCMC verison of the Stow facsimiles. Usually the first group is the year (1633) and then last is the image number (0001).

The molshows prefix is used on facs attributes to link to the copies of page-images from mayoral shows stored in the london account on the HCMC server. The first group is the year (1633), the second is the source repository, and then last is the image file name.

The sb prefix is used on ref/target attributes to link to Stow’s Books URLs at UToronto.

Our editorial and encoding practices are documented in detail in the Praxis section of our website.

Author A person or organization chiefly responsible for the intellectual or artistic content of a work, usually printed text. This term may also be used when more than one person or body bears such responsibility. MoEML uses the term author to designate a contributor who is wholly or partly responsible for the original content of either a born-digital document, such as an encyclopedia entry, or a primary source document, such as a MoEML Library text. Project director A person or organization with primary responsibility for all essential aspects of a project, or that manages a very large project that demands senior level responsibility, or that has overall responsibility for managing projects, or provides overall direction to a project manager. MoEML’s Project Director directs the intellectual and scholarly aspects of the project, consults with the Advisory and Editorial Boards, and ensures the ongoing funding of the project. Programmer A person or organization responsible for the creation and/or maintenance of computer program design documents, source code, and machine-executable digital files and supporting documentation. MoEML uses the term programmer to designate a person or organization responsible for the creation and/or maintenance of computer program design documents, source code, and machine-executable digital files and supporting documentation. Project manager MoEML uses the term Project Manager for a person who handles the administration for the project. Created document. MoEML’s PDF Developer Documentation
XSLT files responsible for creating MoEML PDFs: pdf_globals.xsl createPdfs.xml (ant application) add_special_styles_to_fo_master.xsl get_attribute_sets_names.xsl list_classes_for_pdf.xsl list_fonts_for_pdf.xsl list_images_for_pdf.xsl xhtml5_to_fo_master.xsl xhtml5_to_fo_styles_module.xsl

This documentation goes through the XSL and XML files responsible for building the PDFs.

pdf_globals.xsl

The pdf_globals is an XSL file that contains the variables, parameters, and functions necessary for the creation of every PDF. $docId is the variable that gets the xml:id of the document, so that we can use it to build this particular file and all of its required components. $attSetDoc is a variable that gets the docId-specific styling module and the master styling module (used later to assign corresponding attribute sets as per the respective classes). Two parameters assign the locations of necessary folders: the FO folder and the output folder. Two other parameters get the titles of the document at hand: one for born digital files and one for primary sources. pdf_globals also contains a function, getAtts, that allows us to add attributes from the class’ corresponding attribute sets, in addition to the attributes that are unique to the class, which we retrieve from the style element in the original HTML source document. This function finds the appropriate attributes selected in the master styles module, and then finds the document specific attribute sets. Attributes get added if they were not already, and if they are already written in, they get overwritten by the specific styling. The same function also manipulates some attributes and their values, to accommodate the FO restrictions, such as rem (replaced with pt), and the small-caps font variant, which gets a specific font-family selected for this particular purpose.

createPdfs.xml

createPdfs.xml is the Ant application that builds the selected PDFs. This file runs through the terminal application. It checks for FOP; if it is not available it gets downloaded. If FOP is downloaded, it checks whether or not it is up to date and updates it if need be. Images and fonts folders are defined in properties, to be used later in retrieving the appropriate material. The listFiles property lists the document ids that need to be built into PDFs.

The Ant application creates a list of images mentioned and used in the source documents and then downloads said images. The same process is applied to the fonts. In addition, the ant application runs the following targets:

Creates a special styles module, particular to the document that is being processed. This special module contains the formatting from the html/head/style element.

Adds the special module to other XSLTs responsible for the creation of the PDFs.

Validates the resulting FO document.

Is responsible for retrieving the source HTML file from our server.

Is the main (though not the default) target that processes the file (docId) in the following order: gets the file from Jenkins, creates the special styles module, adds the special module to the master module, creates the images list, copies the images, creates the fonts list, copies the fonts, creates the FO file, creates the PDF, and finally gets the .png of the title (cover) page (which is used in the creation of ePubs).

Creates the XSL:FO file from the HTML source file, as per the docId_xhtml5_to_fo transformation.

Creates the PDF file from the docID.fo file using the FOP application.

Gets the PDF’s title page in .png format, so we can use it for the ePubs. For this we use pdftoppm execution.

Is the default target; it runs processOneFile to build all the documents listed in the listFiles property.
add_special_styles_to_fo_master.xsl

This XSL transformation is designed to include a special XSL styles module in the xhtml5_to_fo_master. It does so by creating a variable that gets the attributes from the special styles module. The file has templates that match onto the following elements: div, span, and img. These templates find the classes and their corresponding attribute sets to add the necessary attributes and their values, and apply other templates as required.

get_attribute_sets_names.xsl

This stylesheet is a rather simple one that reads the special styles module (docId_styles_module.xsl) and gets the attribute sets that need to be used. It stores them in an output file listOfSets.txt which gets used in xhtml5_to_fo_master.xsl.

list_classes_for_pdf.xsl

This XSL transformation is designed to read the style element in the HTML file and list the styling classes needed for the particular PDF being built. It starts by parsing the style element as a string, stored in a variable ($style). The variable $parsedClasses stores the name of the classes so that we use them later in naming the attribute-sets. $attribute is the variable that has the attribute names as well as their values.

The root template of this transformation creates the attribute sets corresponding to classes mentioned in the style element of the source file. It results in a document saved in db/data/static/xsl called $docId_styles_module.xsl. The template recreates the following variables: parsedClasses, and parsedStyle.

list_fonts_for_pdf.xsl

This XSLT is designed to read the CSS files and list the fonts needed for the particular PDF being built. We adopt it from the transformation designed for ePubs. The root (main) template creates a list of fonts mentioned in the corresponding CSS files, to be then used by the ant file to copy these fonts into the PDF container folder. It first creates a variable that lists the css files. The files are then tokenized in $tokenizedCss and normalized in $allCss. The variable $parsedCssFonts results in a document listOfFonts.txt that contains $distinctSiteFonts, which gets the distinct values of the $parsedCssFonts variable.

list_images_for_pdf.xsl

This XSLT reads the XHTML and CSS files and list the images needed for the particular PDF being built. It is very similar in its structure to list_fonts_for_pdf.xsl: The root template creates a list of images mentioned in the corresponding CSS files as well as the XHTML file, to be then used by the ant file to copy these images into the PDF container folder. This template first creates a variable that lists the CSS files. The files are then tokenized in $tokenizedCss and normalized in $allCss. The variable $parsedCssImages results in a document listOfImages.txt that contains $distinctSiteImages, which gets the distinct values of the $parsedCssImages variable. This transformation also has a few hard coded images, given that they are not present in the CSS or XHTML files.

xhtml5_to_fo_master.xsl

This XSLT is designed to convert a MoEML XHTML5 static site document into a PDF. It converts the document to XSL:FO, validates the FO, and then the calling Ant script uses FOP to generate a PDF. This file includes the styles module xhtml5_to_fo_styles_module.xsl (discussed below), and pfd_globals.xsl. The root template sets up the FO basics: four simple page masters (title page, first page, recto page, and verso page). The sequence of pages follows. The main page-sequence contains the footers (title page, recto, and verso) and headers (recto and verso). The headers differ in their code as per born digital or primary source, because of the structure of their titles. The template that matches on the html element applies templates (both named and unnamed as discussed below).

This template processes the metadata in the page header to get the key information. The aesthetic and stylistic components include: a background image, two flower logos (top and bottom), decorative lines (top and bottom) between which the title of the document sits, and a snippet of the agas map. The size of the title and the authors depends on the length of the title and the number of authors listed. The title page also contains the edition information (which is basically the release version at the time of the build).

This named template creates another title page that contains hybrid metadata, which includes the title, authors, compilers, and editors, in addition to the publication information. This template contains two conditions: one is when the document at hand is a born digital file, and the other is when it is a primary source file.

Unnamed Templates

divs are transformed into fo:blocks. Their ids are replicated into id attributes. Depending on the class attribute of the div, the fo:block element gets assigned the appropriate attribute set(s). divs that are children or descendant of the appendix div, get special attribute sets that correspond to the appendix styling of the PDF.

nav elements are transformed into fo:blocks, and their ids are copied into corresponding id attributes.

ul elements are transformed into fo:list-block elements. Their ids are replicated into corresponding id attributes. uls that are descendant of the appendix get special styling to correspond with the appendix styles.

ol elements are transformed into fo:list-block elements. Their ids are replicated into corresponding id attributes. ols that are descendant of the appendix get special styling to correspond with the appendix styles.

li elements are transformed into fo:list-item elements. Every fo:list-item contains an fo:list-item-label and an fo:list-item-body. Depending on their level in the list structure, fo:list-item-label and fo:list-item-body elements get the following attribute sets, respectively: list-item-label and list-item-body, list-item-label-descendant and list-item-body-descendant, list-item-label-level3 and list-item-body-level3, list-item-label-appendix and list-item-body-appendix. In tables, fo:list-item-label and fo:list-item-body get attribute sets list-item-label-table and list-item-body-table, respectively. The page menu fo:list-item gets the attribute set pageMenu.

tables are transformed into fo:table. When the table has a class attribute contentTable, the fo:table element gets the contentTable attribute set.

theads are transformed into fo:table-header elements, with attribute set table-head-td.

tbody elements are transformed into fo:table-body elements.

tr elements are transformed into fo:table-row elements.

td elements are transformed into fo:table-cell elements. td elements with parents or ancestor thead elements acquire the attribute set table-head-td; if the td element has an ancestor table that has attribute class contentTable, the fo:table-cell gets the attribute set contentTable-td; otherwise, fo:table-cell elements get the table-cell attribute set.

a elements are transformed into fo:basic-links, with attributes: id(if applicable), external-destination or internal-destination for the value of the href attribute of the a element, and color. If href ends with .htm, or contains http, jpg, mp3, the fo:basic-link gets an external destination attribute. The fo:basic-link also gets an external-destination attribute and other appropriate styling attributes, if the a element has a class attribute that is not noteMarker nor returnFromNote nor local. Otherwise, fo:basic-link gets an internal-destination attribute.

This template is responsible for links that refer to ids, mostly with internal references. We use the variable $thisid to identify the id of the current a element. If $thisid is not stated anywhere else in the document, then the fo:basic-link will have an external-destination, with https://mapoflondon.uvic.ca/$thisid.htm. Otherwise, the fo:basic-link will have an internal destination, without the #, and with the appropriate attribute sets as per the class attributes.

p elements become fo:blocks.

span elements become fo:inline elements.

strong elements become fo:block elements when they have a parent element li, and fo:inline elements otherwise.

pre elements become fo:block elements when they have a parent element li, and fo:inline elements otherwise.

q elements become fo:block elements when they have a parent element li, and fo:inline elements otherwise.

blockquote elements become fo:block elements with the blockquote attribute set.

code elements are transformed into fo:inline elements with the code attribute set.

img elements are transformed into fo:external-graphic elements. They all have the images attribute set, and when appropriate, they have an additional attribute set that corresponds to their appropriate class, including acknowledgementImg and socialMediaImg.

figure elements are transformed into fo:block elements.

ficgaption elements are transformed into fo:block elements. When the figcaption element contains the strings horizontal rule or Printer’s ornament, the fo:block element gets the attribute set figcaption_special; otherwise it gets the attribute set figcaption.

h1 elements are transformed into fo:block elements. When h1 has a child span that has a class attribute titlePart, it gets both attribute sets h1 and h1TitlePart, otherwise it only get the attribute set h1.

h2 elements are transformed into fo:block elements. When they are appendix headers, they get the attribute set appendixH2, otherwise they get the attribute set h2.

h3 elements are transformed into fo:block elements. When they are appendix headers, they get the attribute set appendixH3; when they are appendix list headers, they get the attribute set appendixListH3, otherwise they get the attribute set h3.

h4 elements are transformed into fo:block elements. When they are appendix headers, they get the attribute set appendixH4, otherwise they get the attribute set h4.

br elements are transformed into fo:block elements.

[Primary Source Element] hr elements are transformed into fo:leader elements, with id attributes when appropriate.

This transformation is also responsible for removing the following components from the document: the top banner, See XML, More Info, blackletter typeface and toggle, script elements, Send Feedback, the footer menu, the info popup, document mentions, person’s contributions, person’s mentions, the citation header, facsimile figures, links to agas.css and agas_embedded.css from the header, pilcrow (¶) links, and social media logos. It also replaces lightbox.css with nav.css, rewrites some links as necessary, renames Personography into Contributors, rearranges appendix lists (historical persons and variant spellings), and sorts the personography alphabetically.

Note that there are other removals that happen through add_special_styles_to_fo_master.xsl.

xhtml5_to_fo_styles_module.xsl

This XSLT module contains the styling and layout data for the XHTML5 to XSL:FO transformation, which turns MoEML XHTML5 static site pages into PDFs. We will set up the pages initially so recto and verso have slightly different margins, to allow for binding along the long edge. We may decide to eliminate this distinction at some point. This module works with the special one created for the particular files being transformed. It contains all the master attribute sets needed, which have been mostly inspired from the various MoEML site CSS files. The attribute sets in this document do not include attributes or values that do not agree with XSL:FO or FOP. The structure is straight-forward: the xsl:stylesheet element contains all xsl:attribute-set elements that must have a name attribute. These elements in turn contain xsl:attribute elements, which also must have a name attribute and a value.