A CSS API for eBooks

Or how I’m just trying to avoid using the term “micro format” as people don’t want to hear about this dirty word while it could solve a lot of CSS issues.

API stands for Application Programming Interface. It’s just a set of definitions, protocols, and tools for building software and applications. Basically, it’s like Lego: the building blocks are provided, you just put them together.

So yeah, maybe “CSS API” is far-fetched since we’re by no means talking about software and applications but I guess that you might at least grasp the spirit that drives it.

Why, oh why?

Whether we like it or not, #eprdctn is a strange beast: it’s kinda webby but it comes with its own challenges. And oh boy are those challenges hardcore…

First you’ve got all those rendering layers (i.e. pagination) to deal with. And it’s a mess since pagination in a web context is an awful hack. CSS 3 columns are often used but their implementation are always lacking, other times the files are simply altered to make pagination happen, etc.

Then you’ve got all those default CSS and their overrides, which are obviously undocumented. Needless to say some overrides are dynamically applied through JavaScript, which makes it even more difficult to debug.

Finally you’ve got mediocre CSS support e.g. if you do pagination, I can guarantee humans can’t cope with the idea you don’t support the whole set of “page-break-whatever”. Adding insult to injury, what works may be broken because RS went YOLO to achieve pagination.

So what if we made it easier for everyone?

And I know it sounds like a crazy idea considering the relationship between RS developers and eBook authors looks like trench warfare at times…

But truth is Reading System developers have way more control on rendering than we’ll ever do. So they are part of the solution. 🙂

Oh how how?

Let’s say you’re authoring non-fiction eBooks… Congrats! Your life is just terrible.

Why that? Because you must deal with images.

Figures blocking the flow…

Figures with captions…

Floating figures that you wish weren’t floating in narrow columns but since media queries are broken, you can’t do that reliably… 😟

Figures with a portrait aspect ratio… 😱

Figures with a portrait aspect ratio and a caption. 😭

It’s bad, it’s really REALLY bad.

And it seems that, for some unknown reason, some Reading System developers think all figures are landscape aspect ratio without a caption. And they will override based on that assumption…

¯\_(ツ)_/¯

Dear web fellow, if you don’t know how bad the situation is, please be informed that we can’t make sure a figure and its figcaption are displayed on the same page everywhere.

So… what if we shared a common set of building blocks?

Like say

<figure class="full-bleed">
  <img />
</figure>

or

<figure class="landscape-caption">
  <img />
  <figcaption>…</figcaption>
</figure>

or

<figure class="portrait-caption">
  <img />
  <figcaption>…</figcaption>
</figure>

or, let’s go YOLO TO THE MAX

<figure class="landscape-caption width-70">
  <img />
  <figcaption>…</figcaption>
</figure>

<figure class="portrait-caption height-80">
  <img />
  <figcaption>…</figcaption>
</figure>

Wouldn’t that be easier for everyone?

1. “full-bleed” implies the image should fit the page while keeping its aspect ratio (would be dope for… say… cover images);
2. “landscape-caption” implies a “break-inside: avoid” should be enforced so that the two related elements in the figure are kept together and displayed on the same page;
3. “portrait-caption” implies the image should not be full-height and some space must be saved for the caption (carte blanche to Reading Systems);
4. “width–70” implies that, if possible, the image should be 70% of the width.
5. “height–80” implies that, if possible, the image should be 80% of the height (or 80vh).

So yeah, it’s basically describing figures to Reading Systems which, in turn, style them accordingly.

What what

It’s not just about figures if you think about it for a minute.

Let’s imagine you use this

<aside class="bordered">
</aside>

BOOM, now RS know there is a border and they either provide a default one or they use it to override the border-color in night mode — something they don’t currently do.

Now, what if…

<blockquote class="epigraph">
</blockquote>

and

<ol class="image-grid one-third">
  <li><img /></li>
  <li><img /></li>
  <li><img /></li>
</ol>

and

<hr class="asterism" />

and

<pre class="css-syntax"><code>
</code></pre>

Wouldn’t it be awesome if you didn’t even have to CSS?

I mean, if you don’t want to. Obviously.

And what if that could lead to interactive widgets? As in…

<aside class="interactive-popup">
</aside>

Which should probably be more like this as a matter of fact…

<aside data-epubWidget="popup" class="bordered">
</aside>

With “data-epubWidget” being the “interactive popup trigger” and “class” the static fallback.

Perhaps it would not work everywhere but hey, at least you could do “graceful degradation” by styling it.

Pros and Cons

I’m being honest, this is not perfect. Nothing’s perfect in real life after all, because pure theory doesn’t stand the test of time…

Pros:

• acknowledging eBooks have specific issues that the web doesn’t necessarily have to deal with (since it isn’t paginated by default);
• the simpler, the better: you may hate this idea but everybody knows how to “class”, which is not necessarily true for anything else;
• if you don’t want to use class, the logical framework can be applied to anything else (data attribute?);
• you could still style those classes (i.e. for RS which would not provide this “CSS API”);
• consistency at the RS level;
• consistency at the authoring software level (developers could provide users with a set of predefined ebook styles);
• if the CSS is absolute crap, you could override it globally;
• Reading Systems + authoring software could provide users with, wait for it, eBook themes (extra cash opportunity for both devs and authors);
• you may hate that idea as an eBook author but overriding would be a lot easier.

Cons:

• yep, it’s objectively a micro format and I know you don’t want to hear about that;
• extra stuff in the RS (and that probably wouldn’t be specced);
• if there’s a bug in the RS, everyone is impacted;
• performance impact (???);
• that should probably be “prefixed” because collateral damages could happen;
• you’ll probably hate me since it feels like a proposal to create an eBook-specific “API” while EPUB 3.1 is trying to get rid of anything eBook-specific.

Thoughts?