Home > Project Documentation

MoEML’s ePub Developer Documentation

This document is currently in draft. When it has been reviewed and proofed, it will be published on the site.

View the draft document.

Please note that it is not of publishable quality yet.

MoEML’s ePub Developer Documentation

roseList documents mentioning MoEML’s ePub Developer Documentation

XSLT files responsible for creating MoEML ePubs.

  • Jenkins_to_epub.xsl
  • Epub_supplementary_files.xsl
  • List_css_for_epub.xsl
  • List_fonts_for_epub.xsl
  • List_images_for_epub.xsl
  • createEpubs.xml
This documentation details the XSL and XML files responsible for building the ePubs.

jenkins_to_epub.xsl

This XSL transformation processes the source XHTML file, retrieved from Jenkins, to make it compatible with the ePub output that we desire. It mainly deletes components that are not needed in the production of ePubs. It includes epub_globals.xsl, which has all the required variables and parameters.
This transformation results in a XHTML document with the $docId name, saved in the output folder (as defined in epub_globals.xsl). It removes the following items: top banner, related information, page XML, script elements, breadcrumbs, send feedback, footer menu, document mentions, people’s contributions, facsimiles, agas.css link, agas_embedded.css, people’s abbreviations, roles played, membership organizations, and social media logos.
Then, jenkins_to_epub.xsl replaces unused CSS links with new ePub CSS links, and rewrites local links into externals directing to the MoEML website when necessary. One of the templates rewrites links for graphics to images, and makes full sized images links into externals.
There are templates that move some elements from one position to another, such as variant spellings and historical figures. One template sorts the personography alphabetically.

epub_supplementary_files.xsl

This transformation writes the supplementary files needed for the generation of every ePub. It includes epub_globals.xsl. The root template calls the document’s named templates (explained below).
  • createMimetypeFile
    creates the mimetype file. It is a text output with one line: application/epub+zip.
  • createContainerFile
    creates the container.xml file and stores it in META-INF folder. It is a XML output file, with a rootfile element containing the path to package.opf.
  • createCoverFile
    The cover file is an XHTML file saved in the main document-specific EPUB folder. In its head element, this page gets the first title element with a property attribute of value titlePage. The actual cover is the cover image that we take from the corresponding PDF document that we build. It is in .png format.
  • createMetaHybridFile
    This 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.
  • createNavCssFile
    This template creates the CSS styling for the nav page. The resulting document is a .css file. The template body is written in CSS.
  • createmetaHybridCssFile
    This template creates the CSS styling for the metaHybrid page. The resulting document is a .css file. The template body is written in CSS.
  • createPackageFile
    The package file is in .opf format. It should list all the files – including images – that are mentioned in the ePub When a file is in the ePub but not mentioned in the package file, the validator will flag an error. It is also erroneous if an item is mentioned in the package file but is not saved in the ePub folder. The template gets the items from the lists that we generate for the creation of the ePub.
  • createNavFile
    This template is responsible for creating the nav.xhtml file. It lists the page contents submenu of a document when a list element with id attribute pageContents is available. It ends with a script element (javascript).
  • createTocFile
    This template also creates a table of content, with a <navMap> element. The contents have @id attributes and @playOrder attributes. It does not have a <script> element.
  • createEpubCssFile
    This template creates the CSS styling for the epub .xhtml file. The resulting document is a .css file. The template body is written in CSS. It overwrites other styling, unless the platform does not allow it.
  • createCoverCssFile
    This template creates the CSS styling for the cover image. The resulting document is a .css file. The template body is written in CSS. This XSLT also has unnamed templates. One template rewrites a local link to make it a link from the cover file to the content file, and removes breaks after the title for styling purposes. Another template deals with <ul> elements in ol in the nav.xhtml file, as well as rewrites a local link to make it a link from the nav file to the content file. A third template deals with some styling of lower level <list> elements, also rewriting their links appropriately.

list_css_for_epub.xsl

This XSLT creates the list of CSS files needed for the ePub, which will determine what files will be copied into the EPUB/CSS folder. The resulting document is a .txt file. The links are retrieved from the source file. Some additional links are hard coded.

list_fonts_for_epub.xsl

This XSLT creates the list of fonts needed for the ePub, which will determine what files will be copied into the EPUB/fonts folder. The resulting document is a .txt file. The root template contains a variable $cssFiles that reads the CSS files. Variable $tokenizedCss tokenizes the css files, so that variable $allCss can normalize them. The root template then analyzes the strings and applies the necessary changes to produce the list.

list_images_for_epub.xsl

This XSLT creates the list of images needed for the ePub, which will determine what images will be copied into the EPUB/images folder. It follows the same process as that of list_fonts_for_epub.xsl.

createEpubs.xml

This XML file is the Ant application responsible for creating the ePubs. It handles the processing of XHTML documents retrieved from MoEML’s Jenkins. It requires tools located in utilities, and assumes that ant-contrib is installed.
A list of properties are defined, most of which are for the paths of necessary files and/or folders. For instance, graphicsFolder defines the path of the graphics folder in the SVN repository, from which some images will be copied.
  • Target getEpubcheckLocalVersion
    Checks the current version of the epubcheck.jar file in utilities. If the file is not available, a value of 0.0.0 will be returned, which will trigger a download because it is (always) less than the current version.
  • Target getEpubcheckLatestVersion
    Checks the GitHub repository for the validator to determine the latest version number. This number will be compared against the current version; if it is lower, then a download is required.
  • Target getEpubcheck
    Checks whether or not epubcheck.jar is available and up to date. If it is absent or out of date, the latest version gets downloaded.
  • Target vaidateEpub
    This target depends on the availability of epubcheck.jar. It passes the file to the validator, which in turn outputs the results (including any warnings or errors).
  • Target getSourceFileFromJenkins
    Retrieves the appropriate HTML file from the latest Jenkins build, to be then processed into an ePub. This target creates the sourceFiles folder if it has not been already created.
  • Target sourceFileToEpubXhtml
    Processes the original source file into a simplified and ePub compatible version of the file. It relies on the jenkins_to_epub.xsl stylesheet.
  • Target createCssList
    Creates a list of CSS files which are in the repository and are referenced in the document being processed, so that we copy them into the corresponding folder, only as needed. It relies on the list_css_for_epub.xsl stylesheet.
  • Target copyCss
    Copies the set of required CSS files as per the list created in the previous target.
  • Target createFontsList
    Creates a list of fonts which are in the repository and are referenced in the document being processed, so that we copy them into the corresponding folder, only as needed. It relies on the list_fonts_for_epub.xsl stylesheet.
  • Target copyFonts
    Copies the set of required fonts as per the list created in the previous target.
  • Target createImagesList
    Creates a list of images which are in the repository and are referenced in the document being processed, so that we copy them into the corresponding folder, only as needed. It relies on the list_images_for_epub.xsl stylesheet.
  • Traget copyImages
    Copies the set of required images as per the list created in the previous target. This target also creates the EPUB/images directory, and copies files into it, from directories defined in the properties (as discussed above).
  • Target CreateSupplementaryFiles
    Creates the supplementary files needed for the ePub being generated. It relies on the epub_supplementary_files.xsl stylesheet.
  • Target addSupplementaryFiles
    Adds the supplementary files, creating the necessary directories: EPUB and META-INF.
  • Target processOneFile
    Uses the appropriate docId parameter, to retrieve the source document and then process it into the ePub. This target calls the following targets: getSourceFileFromJenkins, sourceFileToEpubXhtml, createCssList, createFontsList, createImagesList, copyCss, copyFonts, copyImages, createSupplementaryFiles, addSupplementaryFiles, buildEpub, and validateEpub.
  • Target processMultipleFiles
    This is the default target. It uses the idList input parameter to retrieve selected source documents, and then calls processOneFile to process the documents into ePubs.
  • Target buildEpub
    Creates an ePub file from the XHTML file. The XHTML file is found in the parameter inFile. After processing the XHTML as per jenkins_to_epub.xsl, the ePub folder (with all its contents and child folders) is zipped; the mimetype file should be zipped first, and other folders follow.