Content Container: OCF

The internal directory structure of all EPUB files is described by the OCF specification. At the root level of the EPUB file there is one mimetype file, one folder named META-INF, and one or more content directories. The specification does not dictate the name of the content folders, but since content may be stored at this level in multiple formats or "renditions," the specification does recommend using one folder per rendition². In Figure 1, the OPS and PDF directories are the content directories. The OPS folder contains the content compliant with the OPS specification for EPUB and the PDF folder contains a PDF file of the document.

Fig. 1

Unzipped EPUB File.

The mimetype file identifies the EPUB file as such and is required for eReaders. Its only content is the string "application/epub+zip".

Within META-INF are files containing information about the EPUB document, including the container-level metadata, content, and encryption. At minimum, META-INF must contain one file called container.xml that points to the root file of the OPS rendition of the publication. If more than one rendition is included, the container.xml file should point to the root file of each rendition. In JATStoEPUB.epub, META-INF only contains container.xml, which points to the root file for the OPS rendition (OPS/epb.opf) and the root file for both the OPF and PDF renditions (for renditions that consist of only one file, that file is the root). Figure 2 shows the contents of container.xml.

Fig. 2

META-INF/container.xml.

Packaging Standards: OPF

The metadata requirements for EPUB publications is defined by the OPF specification. Specifically, the OPF:

• Describes and references all components of the electronic publication (e.g. markup files, images, navigation structures).

• Provides publication-level metadata.

• Specifies the linear reading-order of the publication.

• Provides fallback information for when extensions to OPS are employed.

• Provides a mechanism to specify a declarative global navigation structure (the NCX).

(Open Packaging Format 2.0.1 v1.0.1; see Ref. 4)

These requirements are all met with two files, the OPF and the NCX. In JATStoEPUB.epub, the files are called epb.opf and epb.ncx, respectively. As illustrated in Figure 3, these two files are stored in the OPS content directory. NCX (Navigation Control file for XML applications or Navigation Center eXtended) is part of the DAISY Consortium's Digital Talking Book (DTBook) specification and is used to define the publication's navigational structure. The OPF file includes all other information required by the OPF specification.

Fig. 3

OPS content directory.

The OPF uses the Dublin Core Metadata Initiative® (DCMI) element set as the vocabulary for the publication metadata. These elements are contained in a metadata element. The OPF specification adds attributes to these elements that are specific to the OPF namespace, but the element set is otherwise unchanged. The full content of epub.opf is shown in Figure 4.

Fig. 4

epb.opf file.

The other components of the epb.opf are the manifest element, which lists all files that make up the publication (OCF container files are excluded from this list), and the spine element, which defines the reading order for the publication. As shown in Figure 4, there is only one item referenced in the spine element, and that is the XHTML of the article. Not present in this example is an optional guide element which provides links to parts of the document that the document author wishes the reader to have quick access to (list of figures, glossary).

The NCX file defines the navigational structure for the document. This structure is accessed by the end users as a "clickable" table of contents to navigate to various parts of the document. The NCX differs from the spine element in that it is used by the end user whereas the spine is read by the eReading devide to load the content in the proper order.

Content Markup Standard: OPS

The OPS defines the preferred vocabularies and supported media types for EPUB documents. The specified content markup includes the DTBook and XHTML 1.1 vocabularies. CSS2 is also identified in the OPS as the method by which the EPUB documents are styled. The included vocabularies of both XHTML and CSS are subsets of the full specifications from the W3C, however. The IDPF imposed limits on what from those vocabuaries is included to reduce the burden on eReading systems—both hardware and software.

An eReading system may support more of the vocabularies than are included in the OPS and the specification states that in reference to styles, compliant eReaders are required to "gracefully degrade" unsupported properties⁶ and must not suffer catastrophic failure because of their presence in the data. Despite this safety measure, following the vocabularies set forth in the OPS will ensure that data is supported across the widest range of eReaders.

DTBook, XHTML, and CSS are all included in the OPS-specified list of core media types—those MIME types that must be supported by compliant eReading systems. The full list of supported types is GIF, PNG, JPEG, SVG, XML, and CSS. Files that are not of a core media type may be included in the EPUB document, but for each non-supported object, a fallback item of a supported MIME type must be included. EReaders may support more file types than those specified as core types, so including non-core media files is allowed. One object may have several formats, including more than one non-core media types, but there must be at least one object in the fallback chain that is of a core media type. For images, the required "alt" attribute that provides a short textual description of the image is defined as a sufficient fallback for that object. Figure 5 shows an example of a simple fallback chain.

Fig. 5

Fallback chain.

The Container

The EPUB container requires three things:

1. the prescribed directory structure,

2. a container.xml file pointing to the publication's OPF file, and

3. a MIME file to identify the EPUB document.

To meet these requirements, the XProc pipeline will creates the primary output directory with the META-INF and OPS subdirectories. It then calls an XSL transform to create the container.xml file, which references the OPF file containing the document's metadata, manifest, and reading order. Because there is only ever one OPF file per publication, this conversion always writes the file as epb.opf to simplify the container file generation.

Packaging

After creating the directory structure, the pipeline invokes a pair of XSL transforms to generate the packaging components from the JATS source data. The XSL to create the epb.opf file converts JATS metadata elements to the DCMI elements. As previously mentioned, the metadata is tagged with DCMI elements, some with OPF-specific attributes added. These attributes allow preservation of some of the granularity present in JATS metadata which is absent from the standard DCMI element set. Table 1 shows several Tag Suite metadata elements and their corresponding DCMI elements, some with OPF attributes.

Table 1

In the OPF file, the minimum metadata required is one title, one identifier, and one language element. The language attribute is always present in JATS data, but neither the title nor the identifier are required JATS elements. To meet the requirement for a unique identifier, this conversion invokes the XProc function to generate a Universally Unique Identifier (UUID) for the publication. The UUID is used in various places throughout the EPUB document, including both the OPF (see Figure 4) and NCX files.

The manifest element lists all files that make up the publication content. Any included objects that are not of a core media type must also have a fallback object identified. Generating the manifest requires several actions being taken on all of the referenced object files in the source XML. This includes JATS tags like graphic, media, inline-supplementary-material, and supplementary-material. The conversion must check whether or not the MIME type of each referenced object is core media type. For any object that is not, the conversion checks for any specified alternatives for the object. If none of the specified alternatives are of a core media type or there are no specified alternatives, the conversion must generate a warning message that alerts the user to the problem. All of these checks must be run on the value provided in the xlink:href attribute of the objects, which can also prove to be a challenge. Object references vary greatly across systems, and in some cases, the object reference includes neither the file extension nor the mimetype attribute, making it impossible to determine the object's MIME type.

This conversion will write out the file names of the referenced objects as they appear in the source data, however, regardless of whether or not the object's MIME information is available. If the MIME information either cannot be determined or is not among the core media types, the conversion will write a warning message, not an error. This allows the conversion process to complete but alerts users to the problem. Figure 7 shows the warning messages generated by the conversion in both the OPF file and on the command line during the conversion process.

Fig. 7

Non-supported MIME type warnings.

Following the OPF file generation, the XProc pipeline runs an XSL transform to generate the NCX file for the document, which provides all navigation information for the document. In the case of most articles, the primary navigation point is just the article itself. Figure 8 shows the NCX file as generated by this conversion.

Fig. 8

NCX file.

Content Markup

With the container and packaging complete, the only remaining piece is the content markup. Because XHTML is a preferred vocabulary for EPUB, this conversion process began by using the article preview XSL transform available on the Tag Suite website.¹¹ The XHTML output generated by that transform follows the transitional XHTML DTD rather than the strict subset required by the OPS. After making some modifications to a customized version of that stylesheet to produce the required XHTML, it became clear that the table structure employed in that page layout would not be appropriate for eReader display (see Figure 9).

Fig. 9

Screenshot of 2-column EPUB layout.

Despite the layout concerns, however, parts of the preview stylesheet can be repurposed for the conversion to EPUB. This project uses the NLM-style citation processor, which saves a great deal of time and an effort. The pipeline can be customized to choose preview stylesheet's APA citation processor, or any other citation conversion process to which the user has access.

As demonstrated in Figure 9, certain limitations of the target format must be kept in mind. The use of tables in formatting pages is one example. EReaders do not handle tables well, because they often prevent text reflowing easily. Reflowable text is a primary concern for EPUB data preparation because it ensures that no matter the eReader screen or text size, the content will be displayed correctly.

The last component for the EPUB package is the CSS. Unlike other implementations where the style sheet is referenced by a URI, here the style sheet must be delivered as a file within the package. At the present time, the XProc pipeline calls an XSL transform whose only purpose is to generate a CSS file. There is no actualy transformation in the XSL file, so it is, admittedly, an abuse of XSL. By housing the file's generation in a separate XSL, however, that XSL can easily be substituted in the pipeline for one of the user's choosing, allowing easy replacement of the included CSS.

Final Steps

Once the container, package, and content are all complete, there is still some manual work required in order to complete the EPUB document. The referenced media files must be copied into the output directory structure before creading the *.epub file. While this step could be included as part of the XProc pipeline, currently it must be done manually. This forced intervention gives the user a chance to review the included objects for possible unsupported file formats with no fallback items and to review the objects for their appropriateness for eReading systems.

The final step is to compress the contents, including the subdirectory structure, and save it with the epub extension. The JATS data is now an EPUB document, ready for delivery to eReading systems.