[3 February 2016]

My evil twin Enrique came by in a rage the other day. He had spent the entire weekend trying to figure out why Google Play Books, the ebook reader made by Google, was ignoring large parts of the CSS styling in an EPub3 ebook he has been working on. The CSS worked fine in an earlier test, but he has made numerous changes and improvements, and in the latest test GPB ignores not just the new stylesheet rules but most of the old ones.

His approach involved making test book after test book, trying to split the difference between the version that worked (but did not style everything as desired) and the version that didn’t work — the same sort of binary search depressingly familiar to developers of all kinds working with mysterious problems in the absence of useful diagnostics.

On the plus side, Enrique learned something from the experience; he has hints for those who have to do this with ebooks:

• Make the testbook as short and small as possible, to minimize the wait time while you upload to Google Play from the development machine and then download again to the Android device you are targeting.
• Make at least one change to the metadata in the ebook’s OPF file (often called content.opf, though that’s not required); otherwise some reading software can conclude that they already have the book, and not bother to download it or load it or show it to the user. Changing the title and last-modified date seems to help. (Changing the title is important, actually, since otherwise the test book will be impossible to identify in a list of ebook titles.)
• Give each test book a distinctive cover (any PNG will do); otherwise it’s impossible to tell them apart in the cover-thumbnails view offered by many reading systems.

And what was the problem? Why did GPB object to the CSS?

That, said Enrique, was the infuriating thing. GPB had no trouble with any rules in the CSS files; it had no trouble with the same CSS, if all the comments were deleted.

Were the comments ill-formed? No, not according to W3C’s CSS validator or any other validator Enrique could find.

But GPB ignored the main CSS file if it began with an identifying comment, a revision history, and an overview of the structure of the file. Delete the revision history and the overview, and all was well. Move them to the end of the file, and all was well. Put them at the top of the file, and GPB ignored the file. As far as Enrique could tell, GPB was scanning the first 500 or 700 bytes of the file looking for a CSS rule, and ignored the file if it didn’t find one. An @import statement doesn’t count, he said. Moving the import instructions to the top of the file did not solve the problem; only deleting the long and useful comments solved the problem.

“Is this documented?” I asked. This only made Enrique sputter all the more. I didn’t hear everything he said (probably just as well; he curses like a sailor sometimes), but I gathered that it’s not documented anywhere he could see. (Pointers to documentation of the various ad-hoc restrictions imposed by Google Play Books, or to a GPB-oriented validator for ebooks, would be welcome. Enrique has sworn that he will never try to make a book readable in Google Play Books again, because it’s not worth the aggravation, but other people might still want to.)

It’s a shame that the conformance level of so many EPub3 readers is so abysmally low (and also a shame that even conforming EPub3 readers offer so little interoperability); it makes it hard to publish ebooks of any texts that are more complicated than a George Eliot novel (division into chapters and prose paragraphs are pretty much the only thing an epub publisher can count on; anything more complicated rapidly becomes a nightmare, in my limited experience).