EPUB Compat - Githubissues

JayPanoz commented 6 years ago

Just trying to learn the lessons from the Compatibility Living Standard there. This will be part of Readium CSS docs.

That’s quite some dirty work but I do believe it’s worth it and it can help in the longer term (interop + compat).

Please review this document and let me know if we can improve it.

This document describes a collection of non-standard CSS properties, metadata, and attributes that implementers should take into account to support for compatibility with the de facto EPUB ecosystem.

It also lists important standard features that authors are accustomed to.

Introduction

There exists an increasingly large corpus of ebook content that depends on non-standard CSS properties, metadata and attributes. This document aims to describe the minimal set that Reading Systems might be willing to support for optimal ebook compatibility.

CSS At-rules

`@page`

@page

The @page CSS at-rule is used to modify the page margins in Legacy RMSDK (the one for EPUB 2).

Margins applied in this rule will apply to any “screen” in paged views, unlike the ones set for html or body. It could therefore be used to apply extra margins to the web view or iframe.

The @page at-rule can be accessed via the CSS object model interface CSSPageRule.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/@page

`@supports`

@supports

The @supports CSS at-rule lets authors specify declarations that depend on a browser's support for one or more specific CSS features. This is called a feature query.

It is critical for the advancement of modern CSS that implementers try their best at supporting this rule, especially when pre-processing EPUB files before distribution, since it is one of the very few mechanisms allowing authors to do progressive enhancement (layout, typography, etc.) and to get around bugs in older Reading Systems that don’t support it.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/@supports

Non-standard Kindle Media queries

Since 2012, Amazon has been providing authors with non-standard media queries so that they can declare specific styles for the old format (Mobi7) and the latest ones (KF8 and above).

@media amzn-kf8

@media amzn-mobi

Authors expect the styles in those declarations to be ignored by EPUB Reading Systems. Do not try to support them.

Docs: Kindle Publishing Guidelines

Interactive and Fixed-layout EPUB 2

There exists a significant corpus of fixed-layout and/or interactive files which leveraged the display options created by iBooks and Kobo for EPUB 2.

Kobo

To declare an EPUB as a FLEPUB (Fixed-Layout EPUB), a file named com.kobobooks.display-options.xml must be present inside the EPUB’s META-INF folder (where the container.xml resides).

The contents of this display options file seem to always be:

<?xml version="1.0" encoding="UTF-8"?> 
<display_options>
  <platform name="*">
    <option name="fixed-layout">true</option>
  </platform>
</display_options>

As of November 2011, FLEPUB supports embedded fonts, audio, JavaScript (partially), media overlays (smil). It doesn't support video and SVG.

Apple

To declare an EPUB 2 file as fixed-layout or interactive, a file named com.apple.ibooks.display-options.xml must be present inside the EPUB’s META-INF folder (where the container.xml resides).

Display Options

Supported display options are:

platform: *, iphone, or ipad
specified-fonts: true or false
interactive: true or false
fixed-layout: true or false
open-to-spread: true or false
orientation-lock: landscape-only, portrait-only, or none (default).

Example

<?xml version="1.0" encoding="UTF-8"?>
<display_options>
  <platform name="*">
    <option name="specified-fonts">true</option>
    <option name="interactive">true</option>
    <option name="fixed-layout">true</option>
    <option name="open-to-spread">true</option>
  </platform>
  <platform name="iphone">
    <option name="orientation-lock">landscape-only</option>
  </platform>
</display_options>

Metadata

Calibre

Calibre is using specific metadata for series and rating.

This metadata has a calibre: prefix.

Series

<meta content="Title of the Series" name="calibre:series" />

This item indicates the series the publication is part of.

Series index

<meta content="1.0" name="calibre:series_index" />

This item designates the position (index) of the publication in this series.

Rating

<meta content="10.0" name="calibre:rating" />

This item stores the rating the user has explicitely set for the publication. 2.0 is one star, 10.0 is five.

iBooks

iBooks is using specific metadata for embedded fonts, versioning, gaiji, scroll axis, and the EPUB3 files created with iBooks Author.

This metadata has an ibooks: prefix.

Authors must add the following prefix attribute in their <package> first:

prefix="ibooks: http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/

Then, they can use the ibooks-specific metadata.

Book versioning

<meta property="ibooks:version">1.0.0</meta>

When using book versioning, content providers are allowing iBooks customers who have downloaded the old version of the book to be notified that a new version is available for download. If the customer chooses to download it, the new version will replace the prior version on its devices.

Unfortunately, there is no way to retrieve the changelog for each version since this is managed at the iTunes level.

Docs: iBooks Asset Guide

Embedded fonts

<meta property="ibooks:specified-fonts">true</meta>

Authors can use the specified-fonts attribute to indicate the EPUB files contains embedded fonts, or override a user’s justification and hyphenation preferences. In other words, it preserves the font-family, text-align, and hyphens declarations as specified in the CSS stylesheet, as long as the user does not choose a different typeface when reading the book.

Docs: iBooks Asset Guide

Gaiji and image sizing

<meta property="ibooks:respect-image-size-class">className</meta>

Gaiji are small, inline images that represent characters that are not available in a character or font set. Gaiji are typically used for older symbols or characters in Japanese that have fallen out of use. Authors can define a custom class name for which iBooks will respect an image's dimensions. Those inline images will then not be altered like other images, for which iBooks may force sizing.

Some authors may have used this metadata to force sizing for specific images, and not only gaiji. Moreover, some might use it to invert specific images like illustrations in night mode, since iBooks does it automatically in order for gaiji to be the same color as text’s.

Docs: iBooks Asset Guide

Scroll axis

<meta property="ibooks:scroll-axis">vertical | horizontal | default</meta>

iBooks’ scroll theme scrolls vertically for books with horizontal text, and scrolls horizontally for books with vertical text. By default, Japanese and Chinese books will thus scroll horizontally, while all other languages scroll vertically. This meta allows authors to redefine the scroll direction.

Docs: iBooks Asset Guide

iBooks Author EPUB3 output

<meta property="ibooks:format">RMT</meta>

This meta is automatically added to EPUB3 files generated with iBooks Author. It is probably used to trigger another rendering engine which supports very specific -ibooks- prefixed CSS properties (i.e. -ibooks-layout-hint, -ibooks-list-text-indent, -ibooks-strikethru-type, -ibooks-strikethru-width, -ibooks-underline-type, -ibooks-underline-width, -ibooks-stroke, -ibooks-popover-background, and -ibooks-popover-shadow) and the Tab Stops for CSS.

Moreover, this format is using interactive widgets which are managed at the Reading System level (the EPUB file contains <object> with a type of application/x-ibooks+widget and custom data-attributes for styling).

It could be used as a flag to indicate that the EPUB file was meant for iBooks and there will be rendering issues, especially interactive widgets since they won’t work as intended by the author.

Attributes

The iBooks Reading System is using a set of custom attributes to manage styling and features.

iBooks writing mode

__ibooks_writing_mode

Values can be the ones for the CSS property writing-mode i.e. horizontal-tb, vertical-rl, or vertical-lr.

This attribute is used to style pagination and scroll, the “page” dimensions, and vertical-alignment of some elements.

iBooks theme

__ibooks_internal_theme

Values can be BKWhiteStyleTheme, BKSepiaStyleTheme, BKGrayStyleTheme, or BKNightStyleTheme.

This attribute is used to apply reading modes (background-color, color and filter).

A handful of authors have been using them as a replacement to alternate stylesheets in iBooks.

iBooks font-family override

__ibooks_font_override

Value can be true.

This attribute is used to indicate DOM elements for which the font-family must be changed when the user applies a typeface.

iBooks text-align override

__ibooks_align_override

Value can be true.

This attribute is used to indicate DOM elements for which text-align must be changed when the user sets justification preferences.

iBooks respect image size (gaiji)

__ibooks_respect_image_size

Value can be true.

This attribute is used to style images which class have been explicitly set in the ibooks:respect-image-size-class meta.

Non-standard CSS properties

EPUB authors may have used the following non-standard properties to achieve specific styling or get around Reading Systems’ overrides.

Adobe text layout

adobe-text-layout

Values can be optimizeSpeed and (probably) optimizeLegibility, or auto.

Although this property and (especially) its values look like something close to text-rendering – so close that authors might have been using text-rendering instead –, it isn’t exactly the same.

At the time RMSDK 9.2 was released, this CSS property allowed authors to disable the typography enhancements, including hyphenation, by forcing the older text engine. It was thus primarily used to disable hyphenation, as some devices didn’t support adobe-hyphenate – and you could not disable hyphens for headings for instance.

Source: MobileRead Forums

Overflow scrolling

-webkit-overflow-scrolling

Values can be auto or touch.

The -webkit-overflow-scrolling CSS property controls whether or not touch devices use momentum-based scrolling for a given element.

Some authors may have been using this CSS property to improve the scrolling of overflowing elements, especially in fixed-layout.

Docs: Safari Docs

Non-breaking space mode

-webkit-nbsp-mode

Values can be normal or space.

The -webkit-nbsp-mode CSS property specifies the behavior of non-breaking spaces within an element.

This CSS property might pop up in files generated with the built-in MacOS’ (Cocoa) HTML generator.

Please note that although it might fix an issue in some languages like English, it might also create other issues in some languages, where non-breaking space shouldn’t be treated as a normal space (e.g. punctuation in French).

Docs: Safari Docs

Text fill

-webkit-text-fill-color

The -webkit-text-fill-color property defines the foreground fill color of an element’s text content.

Authors may have used this property to force a color for text in night mode, especially when targeting iBooks.

Text stroking

-webkit-text-stroke
-webkit-text-stroke-color
-webkit-text-stroke-width

The -webkit-text-stroke-color property specifies a stroke color for an element’s text, the -webkit-text-stroke-width property specifies the width of the stroke drawn at the edge of each glyph of an element’s text.

This can (rarely) be used to achieve text with a stroked effect, or faux bolding.

Background color and gradients

-webkit-linear-gradient()

The -webkit-linear-gradient() function must be treated as an alias of linear-gradient().

Some authors might have been using this to force a background-color in night mode, so it would be used in combination with -webkit-text-fill-color so that the text color is forced as well.

Mobile Text Size Adjustment

-webkit-text-size-adjust

The -webkit-text-size-adjust property allows control over the text inflation algorithm used on some mobile devices, many mobile browsers indeed apply a text inflation algorithm to make the text larger and more readable. By using this property, authors can simply opt out or modify this behavior.

Some web authors and/or authoring software might be using this property out of habit, but it actually breaks iBooks’ font-size user setting for instance. This should not be an issue in Readium CSS.

Docs: CSS Mobile Text Size Adjustment Module Level 1

Text decoration styling

-webkit-text-decoration-line
-webkit-text-decoration-color
-webkit-text-decoration-style

The -webkit-text-decoration-line CSS property sets the kind of decoration that is used on text in an element, the -webkit-text-decoration-color CSS property sets the color of the decorative additions to text and the -webkit-text-decoration-style CSS property sets the style of the lines.

There are standard unprefixed properties for these but some authors may have been using the -webkit- ones only.

MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Text_Decoration

Hyphenation

adobe-hyphenate

Values can be none, explicit, or auto.

This must be treated as an alias of hyphens.

A very large part of authors have been using this CSS property to control hyphenation. It should not be an issue as they probably at least used -webkit-hyphens and -epub-hyphens in addition to this adobe-hyphenate CSS property.

Source: MobileRead Forums

Hyphenate limit

-webkit-hyphenate-limit-before
-webkit-hyphenate-limit-after
-webkit-hyphenate-limit-lines

The -webkit-hyphenate-limit-before CSS property indicates the minimum number of characters in a hyphenated word before the hyphenation character, the -webkit-hyphenate-limit-after CSS property indicates the minimum number of characters in a hyphenated word after the hyphenation character, and the -webkit-hyphenate-limit-lines CSS property indicates the maximum number of successive hyphenated lines in an element.

Those properties are standardized in CSS Text Module Level 4, but -webkit-hyphenate-limit-before and -webkit-hyphenate-limit-after have been replaced with the hyphenate-limit-chars CSS property.

Docs: CSS Text Module Level 4

EPUB properties

Some authors might have used -epub- prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encourage to use unprefixed properties.

In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. A mapping is available in the EPUB 3.1 spec if needed.

JayPanoz commented 6 years ago

The underlying question is whether this must be treated as Readium CSS documentation or in another project entirely (interop)?

At first sight, I believe it could be useful to implementers, especially as it is related to CSS, but I’d be happy to be proven wrong.

JayPanoz commented 6 years ago

So here comes the first issue of scoping this to Readium CSS: the iBooks.js lib, which is an embedded JS file in fixed-layout books. To clarify, it is not related to iBooks Author widgets, it is something completely different.

The aim of this lib is to provide authors with a set of classes which ibooks.js will use to trigger animations, make elements draggable, play audio, defer events, etc.

As far as I can tell, this lib is self-contained but will fail in Reading Systems that don’t implement navigator.epubReadingSystem.hasFeature('touch-events').

The possibility authors have been using it in the wild (outside iBooks) is unclear though.

JayPanoz commented 6 years ago

Added ibooks:scroll-axis meta.

My assumption is that scroll mode is tied to the publication’s language and not writing-mode – so it is horizontal for Chinese and Japanese by default. As a consequence, they needed this meta so that authors could override this behavior and set it to vertical if writing-mode is horizontal (which can happen).

But this is just an educated guess.

JayPanoz commented 6 years ago

Closing this issue since it is now documented.

Authoring libs are out of scope.

JayPanoz commented 6 years ago

Updated first comment, so that it is aligned with docs, following this EPUB Revision discussion.

readium / readium-css

EPUB Compat #25

Introduction

CSS At-rules

@page

@supports

Non-standard Kindle Media queries

Interactive and Fixed-layout EPUB 2

Kobo

Apple

Display Options

Example

Metadata

Calibre

Series

Series index

Rating

iBooks

Book versioning

Embedded fonts

Gaiji and image sizing

Scroll axis

iBooks Author EPUB3 output

Attributes

iBooks writing mode

iBooks theme

iBooks font-family override

iBooks text-align override

iBooks respect image size (gaiji)

Non-standard CSS properties

Adobe text layout

Overflow scrolling

Non-breaking space mode

Text fill

Text stroking

Background color and gradients

Mobile Text Size Adjustment

Text decoration styling

Hyphenation

Hyphenate limit

EPUB properties

`@page`

`@supports`