The missing #eprdctn specs

So I hate being “that guy”, and I DO MEAN IT, but eBooks Reading Systems have broken so many things in reflow that someone must do the dirty work and raise the alarm.

Please note I don’t care about your test suites’ results, they are absolutely meaningless in real life and this is why, for instance, Can I Use’s got a tab called “Known Issues”.

“Supported” or a “Percentage score” mean nothing. I’ve reported enough bugs to know that. Period.

I’m tired. So tired actually that I’m publishing this because I’m insanely pissed off.

I’m pissed off at the current global situation in e-production, with Reading Systems breaking so many CSS and JS conceptual models that it’s honestly a freaking catastrophe waiting to happen.

I’m pissed off at the lack of interest for fixing the insane issues we’ve been dealing with for the last 5 years.

I’m pissed off at my 3-year-old bug reports still being unaddressed while some issues are so huge a fix is pretty urgent—looking at you, iBooks.

So here are a few proposals and oh yeah, I’ll probably update this list because the more I dig, the more things become nasty.

You can consider that a gentlemen’s agreement if you prefer… and turn my MUSTs into your SHOULDs, as usual.

1. Don’t mess with the viewport

Seriously.

Hey John, we have to mess with the viewport but what could go wrong? Nothing. Really…

I know things are tricky if you look at it from the specs angle but let’s be honest, what we badly need is LOGIC.

• A viewport width of 23,000 pixels in iBooks OS X
• A viewport height of 8000 pixels in Readium’s scroll mode (at least in Chrome extension)
• A viewport width that is 902px in iBooks iOS when the xhtml is a spread and 422px when the xhtml file starts on the right (or end on the left)

are not logic by human standards. Worse still, it can be harmful.

Use the vh unit to size an image height and all of a sudden, it becomes 6400-pixel tall in Readium’s scroll mode. To be fair, I didn’t report it yet since I must create a sample so that it be easier to see the issue.

Don’t pay attention and the styles in your media queries are applied when they shouldn’t be. As a result, pagination is computed with the wrong data (the styles for 422px are the basis while the styles for 902px are being applied on every spread on iOS), contents overflow and are not displayed at the end of the xhtml file.

For your information, that was reported to iBooks’ developers in November 2014, with samples. They didn’t give the slightest fuck about that. And it’s not an edge case, it’s a fucking fundamental GODDAMMIT!

2. Don’t lie to me

Say I want to check dimensions, offsets, etc. in JavaScript because I need this data to do something dynamically.

So yeah, it’s 300px wide and then, a few milliseconds later, it’s 920px. How come? And oh yeah, it’s actually the viewport width in landscape (iPad Mini) but you don’t update it on orientation change!

An awful lot of Reading Systems will return corrupted data to me if I don’t set a timeout. Now, if I use a timeout, I can’t do something on the fly because the paginating process is over and good luck updating that.

I need the real data ASAP, without a timeout or a poor-performing listener checking a critical change; I need an API to update pagination when needed. If you can’t do that, just disable support for JavaScript in reflow.

I shouldn’t have to engineer a freaking 1000-line checker to do things depending on conditions, like others have done before me. Firstly I would get abysmal perf and mediocre UX. Then there is a critical update or a new RS and I’m screwed? I mean I can’t even rely on navigator.epubReadingSystem because they don’t return “scroll” but “paginated” when they are in scroll mode!

And when I feature query using supports, don’t tell me you support “prop: value;” while you don’t. If I’m asking for a specific feature, I NEED IT PRETTY BADLY to make the whole stuff works—looking at you ADE.

3. Don’t break CSS for pagination’s sake

Position: absolute;

Nuff said.

4. If you use columns to fake a spread, the width I target is the column’s width

So OK, yes it is if you check using JavaScript but no, it obviously shouldn’t.

I’m not even supposed to know you are using columns so, that’s HUMAN LOGIC again.

If my media query is (max-width: 35em), I am targeting the width of the content, not the width of the two columns + their gap.

Besides, I don’t have anything to target the column’s width in the media queries specs. I could do a polyfill but since I must set a timeout to get correct data and can’t push your pagination, I’m screwed.

If you can’t understand that, don’t do spread… or ignore the styles in media queries—prevention is better than cure.

If I’m being so bullish about media queries, it’s because it is critical for good UX.

A type scale can’t suit every configuration, especially when users can increase font-size so much that a 2em heading becomes gigantic (like 12.4em, which is 200px).

A floating image should perhaps be displayed as a block on a 4-inch display or when the font-size is huge… To be fair, Kindle Format X does that automatically, and that’s not a bad idea if you think about it.

And so on, and so forth.

If you can’t understand why it’s terrible to apply 600+px width media queries to less than 300px width content, please stop providing Reading Systems.

This is an accessibility issue as well. Check this and see for yourself.

And I don’t want to rely on queries targeting specific devices to achieve that, they become an over-engineered unmaintainable bloat over the long term.

5. For each global feature you set I need a way to disable it

So you’ve just implemented a cool feature like pop-up footnotes and you’re applying it globally?

Cool, give me a switch to disable it at will. And that’s a MUST in my specs.

All links targeting an id are not footnotes, there are edge cases for which this cool feature, which may improve the UX of the majority of eBooks, will actually hurt UX pretty badly.

Like say I’m using icons and instead of jumping directly to the targeted id, a fucking pop-up with a giant icon will be displayed. That’s crap, and I can’t rely on JavaScript to prevent this default because it is optional per spec and you don’t support it everywhere in your ecosystem.

6. If you provide users with night modes, give authors a way to target that

It’s in the specs.

And implementing this would fix the many issues you get yourselves by overriding styles in night mode, which will undoubtedly fail because borders, backgrounds & al. are super difficult to override unless you go with the nuclear option a.k.a. “the almighty invert filter”.

So this is what I must do in my CSS because iBooks can’t override borders. All I want to do is not killing your retinas with those red borders when the “night gray mode” is active.

And, oh yeah, WCAG 2.0. Color contrast and stuff, especially when one of your default night modes is a #6d6d6f gray.

7. I’m trying hard to accommodate your default CSS, your overrides and your settings…

But sometimes I must override your overrides, by any means necessary.

Respect my !importants.

Pay attention to my rems (and don’t override html’s font-size in that case).

Ask yourself why those styles are declared for my images.

I get why you’re doing that in the first place but let’s be honest, CSS is too complex: you just can’t imagine automating style overrides and not run into issues because the slightest change from what you’re usually overriding is an edge-case.

Or you could build yourself a neural network which can understand CSS and its creepy alleys, alter our files and witness it cry at some point, because everything breaks everywhere and it doesn’t understand why. And then your neural network is able to have nightmares at night so yeah, congrats, you got yourself a new child.

Or stop trying to make it up for the crappy files you must deal with, either by stopping overrides or ignoring the authors’ stylesheets. I’m quite sure it would make some aware of their responsibilities, the situation will improve and soon you won’t have to deal with those crappy files anymore. But if you prefer to impose a technical-debt-that-makes-your-software-unscalable-and-punish-the-people-trying-to-do-their-job-well-and-getting-out-of-eBooks-asap-because-they-can’t-accept-it-anymore upon yourself, so be it.

8. If you support X, just make it work

Oh cool! you support media queries?

Except you don’t update when there is a change…

So you don’t really support it because my queries in em don’t respond to the user changing font-size—Looking at you, ADE.

To sum up

Don’t break HTML, CSS and JS.

If you have to then something is fundamentally broken in eBooks and we should probably call for a moratorium so that we can start thinking about how to fix all the issues we’ve currently got.

Sorry but all the “fixed-layout-oriented specs” that have been designed lately, I don’t really need. Reflow is 95% of my clients’ workflow and they badly need something better, especially when it comes to non-fiction.

I’m not saying FXL is harmful per se but when your clients increasingly don’t want to go fixed-layout because they’ve experienced FXL text-heavy non-fiction and they judge the UX pathetic—some RS don’t allow you to take notes for instance—I’m starting to think they would be better served with a middle-ground: a blank page which is not paginated by default but provides reflow user settings and features. In other words, that is a web browser.

Some are actually devastated with or can’t understand the current limitations. Truth is you can’t probably hear them because they can’t be active participants in specs, orgs, etc. So yeah, I’m not just speaking on my behalf… for what it’s worth.

Or we could continue building on quicksand and see when reflow will collapse. It’s up to you.

¯\_(ツ)_/¯

PS: if you consider the following “public shaming”, so be it.

Please also consider I’m spending hours testing, reporting bugs and tailoring samples from actual eBooks — which means I must replace contents and isolate the pieces that trigger issues. Some RS devs are super responsive and I thank them for that, others won’t communicate at all — sometimes you can’t even report bugs to them…

Please also consider I’ve spent 18 months creating an ebook framework which doesn’t break user settings in RS and is compliant with RS default CSS and overrides. Some of the following issues have dramatically limited the framework e.g. media queries.

Please also consider I’ve created a test suite for text-to-speech in French, a CSS boilerplate addressing dyslexia and a starter kit for InDesign.

Then, please also consider that I am doing all of this on my spare time, including the bug reports since I’m a freelance and I can’t obviously bill my clients for doing that.

Finally, please also consider that if the web and ePub are getting closer — and this will happen — , you won’t have to deal with one tiny Jiminy but an annoyed army of web developers and designers which won’t likely accept the fact you broke the concepts they’re used to.

So it’s absolutely not about saying “Hey, your RS is crap.” It’s about improving something that is not “good enough” anymore. Or we could reimplement pagination, reflow settings and its features in fixed-layout… and drop it like it’s a hot eBook framework, but that would be nonsense.

And oh yeah, this is a follow-up of sorts, in case you can’t understand why I’m being so pissed off.