EPUB samples should follow EPUB 3.1 prefixed properties’ guidelines

[JayPanoz]

I know all EPUB 3 samples have not been upgraded to EPUB 3.1 yet but this is something you might want to keep in mind: a lot of samples use the -epub- prefixed property only, and don’t have the standard one at all.

Prefixed properties are temporary by nature and not future-proof but, unfortunately, it seems like a lot of authors and authoring tools didn't get this concept. InDesign CC 2018, for instance, is still outputting the -epub- prefixed properties and nothing else, which builds an increasing debt (more on that in a few paragraphs).

Example output from InDesign:

body {
  -epub-writing-mode: vertical-rl;
}
span.j-tatechuyoko {
  -epub-text-combine: horizontal;
}

Now, there is a caution in the EPUB 3.1 spec and I guess it would be a good idea to set an example, esp. as the samples may be used as a reference by authors and authoring tools.

I’m obviously not criticizing the fact -epub- properties exist. That was how things were done at the time they were created, but a lot of things have changed since, and it looks like the de facto EPUB ecosystem is a little bit lagging as regards authoring practices.

But how are -epub- properties supported in the first place then?

For transparency’s sake…

When the Reading System is built on top of Blink and Webkit, we get support for free. Webkit indeed aliased -epub- properties to -webkit- properties. We don’t know whether Blink will deprecate and remove those aliases at some point, but they’re aggressively removing support for a lot of webkit CSS props to improve perfs so this could be a possibility. Also, God only knows what will happen when -webkit- properties are removed – will they alias -epub- properties to the standard one? will they forget about it? will they remove support as well?

When the Reading System is using Gecko/Quantum or Trident/EdgeHTML (i.e. a web app), we must polyfill those properties. But since they are not supported, we can’t get it using getComputedStyle so we must parse all the stylesheets, in full. And this is a huge issue, cf. the Dark Side of Polyfilling CSS.

As a result, it will add a lot of complexity to the Reading System, will highly impact performance, and might be buggy. We (Readium CSS) must deal with this issue right now for vertical writing, and we’re leaning towards pre-processing files to add the standard properties when they’re not used in the EPUB stylesheets (but we won’t be able to manage inline styles) because the perf impact is simply too high at runtime – just think about XHTML files taking 3+, perhaps 5+, seconds to load on low and middle-end devices to get the idea, I guess authors don’t want such a thing to happen.

There’s an app a PostCSS plugin for that

If it can help, I’ve created a PostCSS plugin, which will parse the stylesheets you feed it, find the -epub- properties, check if the standard one is in the same declaration and if it isn’t, add it. You can find the repo on my personal github account.

It’s obviously using the EPUB 3.1 mapping to do this task.

A word of caution: it was developed in a hurry and is more of a Proof of Concept at the moment. It can probably be improved but should be pretty reliable, although I didn't stress-test it yet.

On a related note, it’s such a complex issue that we’ve been thinking about creating a web app for authors to edit their stylesheets (and add the standard properties). So it might be a good idea to “promote” the EPUB 3.1 caution.