Injection and Pagination

This page discusses how to inject and paginate EPUB contents.

Injection

Depending on the platform and version you’re developing for, contents must be injected into:

• a web view;
• a chrome view;
• an iframe.

Indeed, we must provide authors with a reliable context in which their styles and scripts are scoped.

Margins and dimensions

Since we must take viewport units into account, especially vh (viewport height), at least the top and bottom margins must be set on this container, and not inside it.

You may also want to set left and right margins on this container so that all margins are equal in the two-column view.

Finally, on larger screens, you’ll have to set dimensions on this container so that it doesn’t become too large.

Background color

Please note you must deal with the background-color outside this container, especially as the user can set reading modes (night, sepia, etc.). In other words, it must be synced with this user setting so that the entire screen is the same background-color.

Pagination

Contents are paginated using CSS multicolumns, for several reasons:

• it’s been cross-platform for a long time;
• it’s responsive;
• it’s tried and tested;
• it brings some kind of interoperability since it has been used by a lot of Reading Systems and authors have been designing against them.

Default

Pagination is responsive by default, which means it is using relative values in order to adapt layout to the viewport and the current font size.

We’ve chosen this approach since it appears setting everything in pixels is more likely to create rounding errors and rendering issues (e.g. cut-off text) than letting the rendering engine deal with relative units on its own.

The responsive design provide other benefits. For instance, if the reader is using an iPad in landscape mode and sets a bigger font size, the two-column view will automatically switch to a single-page view if needed.

You can also limit line-length by setting a max-width for body.

Please note a user setting for the number of columns has been designed so that users can set the layout as they wish.

The RS owns :root and part of body

Since we must inject contents and columns are implemented at the :root level (i.e. html), the Reading System owns the entire styling for this selector.

Font size is an important metric since the responsive design relies entirely on rem (root em) so this style must be enforced by any means necessary.

For body, we own:

• overflow;
• sizing: (min-|max-) width, (min-|max-) height, box-sizing;
• spacing: margin and padding.

You can control horizontal margins in several ways:

1. using column-gap and padding for :root;
2. using column-gap and margin for the web view/chrome view/iframe;
3. using padding for :root and/or body.

Please note that when using padding, you must take it into account when sizing :root and/or body. Their widths contains the padding set for the element.

Patch and safeguards

We’ve designed two extras for pagination:

1. a patch for HTML5 Suggested Rendering, which takes care of paged media;
2. safeguards, which make sure some elements will be managed as expected by authors in columns.

Patch

The HTML5 patch deals with:

• fragmentation (widows, orphans and page-break);
• hyphenation;
• open type features;
• horizontal margins (pixels have been converted to %);
• normalization of abbr and wbr.

You can use it with or without pagination, it should not make any difference.

Safeguards

Safeguards deal with:

• media sizing (e.g. img, svg, audio, video);
• word wrap for long strings (headings and links);
• large table’s overflow.

Once again, you can use it with or without pagination, it should not make any difference.