So that’s how an eBook framework was born
Disclaimer: This essay starts as a pretty personal piece, if you’re only interested in the framework, please feel free to jump to “Let’s document this crap.”
If you just want to download this pre-release crap, go to github.
Around eighteen months ago I created a file called “Blitz.css” on my computer. It was yet another side project launched out of sheer boredom in the rain of Genoa, Italy. Little did I know that turning this simple CSS into a robust eBook framework would require such a Herculean effort.
Blitz’ goal has always been dead simple: helping people author eBook styles. Indeed, the eBook ecosystem is a hostile environment and there is a lot of things happening to your styles: they might be badly digested — and crash some Reading Systems — , they may be ignored, they will be overridden, etc. This is the reason why a lot of web developers or designers giving a shot at eBooks, for instance, end up encountering unexpected issues they don’t necessarily know how to solve.
Having designed more than a hundred templates to master the eBook CSS craft, I thought I was “dat guy who could provide those people with answers in the form of a framework.” Hundreds of people had already downloaded the handful of EPUB themes I released publicly, it seemed logical to me at the time.
The road to hell is paved with good intentions.
The beginnings
Well, people I know consider me an expert. I must be an expert, right?
Developing Blitz was quite easy at first. It was just about putting all my knowledge into one single stylesheet for eBooks (EPUB & Kindle Mobi).
As a matter of fact, I was naïve enough to believe I knew everything I should know as an eBook producer. And I was painfully wrong judging by the hundreds of commits I’ve pushed to date.
Just two days after creating this empty CSS file, I had a framework. But I didn’t release it; it was too rough and, more importantly, untested.
Problem is I, the freelance, suddenly had to deal with an insane amount of work. And the framework went untested for months. Worst still, I had set up my mind to translate the CSS to LESS in order to provide the future users with flexibility.
I was confident that I could do that quickly because debugging would be a “blitz”. After all, I created that from years of experience. What could go wrong?
Development Hell
I feel like I’m the only one in this world.
The following comment stayed in Blitz.css for months.
/* blitz — CSS framework for reflowable eBooks */
/* Version 0.6.66 by Jiminy Panoz */
/* Codename: Development Hell */I thought it was just fun when I wrote it, it slowly but surely turned me into a fraidy cat.
To be fair, it was not just this comment which made me this little kitty… All other side projects I released publicly were met with relative silence. Sure, I could hear echoes but that was it. I tried absolutely everything to rely on others — like putting projets under the Creative Commons Zero licence — , I soon learned that I could only count on my own means.
Why that? I don’t really know. My guess is that the community is still in its infancy so very few people write and make things about eBooks, thus letting Google build some sort of authority that maybe a significant part of people do not want to call into question. At least some people are asking me for a validation so perhaps I have some authority. I don’t know.
Also, I’m opinionated so argumenting with me can be pretty harsh, which may have worked against me. But listen, I can’t learn and improve if you don’t tell me I’m making unbearable melodramatic pieces of crap. OK?
Consequently, Blitz turned out to be a real development hell: I had lost all motivation, the framework was lost in a limbo.
Homesickness… at home
Ciao Genoa, I’m taking my talents to Lyon.
I moved back to France, my native country, and that didn’t go as expected. I’d been an expatriate for 3 years and a lot of things had changed in France. I must admit that reintegrating into this evolving culture proved pretty difficult.
To illustrate how difficult it was, I censored myself a lot then — and I still do today. It feels like you are out of touch with the people you meet, you don’t know how they will react and, well, it hurts. So you build yourself a bubble (that’s work for me) but it hurts even more. Health issues were the icing on the cake…
And, oh yeah, it doesn’t help that the vast majority of people see you as “that guy who knows eBooks.” eBooks, eBooks, eBooks everywhere, every fucking time. Please, folks, I’m not my job, my blog and my twitter profile; there is a human being with other interests behind all of these.
Three years is not a lot but, sadly, it is enough for some of your friends to become strangers too. So you end up shouting from this bubble. Fortunately, I’ve learned that good people stand up when you’re doing so.
Enters Quentin, which worked on eBooks too (authoring and reading systems). We went for a drink and, surprisingly, his first question wasn’t about blitz — but that’s another story which I must confess didn’t end very well. And you know what? It was cool.
Of course we discussed eBooks a little bit and we agreed the lack of open tools was daunting. I had a framework, he had the foot to kickstart my ass again. It’s really amazing how one person willing to help can reignite your determination.
And that is how the blitz framework was back on track.
Let’s document this crap
Designing with assumptions leads nowhere. Period.
We had to document Reading Systems’ default CSS and overrides, we couldn’t “try something else and hope it works.” So we got our hands dirty and soon we created the “Will That Be Overridden” repo on github. Meanwhile, issue #672, started by acabal, arised in the “epub-revision” repo and finally, we, the two guys who started documenting default stylesheets, kind of became troublemakers.
Forget what you’ve heard about the working group, it’s been very welcoming and supportive. So much, as a matter of fact, that I proposed to provide them with an abstract and a documented version of the framework, so that they can use it as a practical example for the CSS issues (more on that later).
On the other hand, we discovered how big a mess the ecosystem currently is regarding stylesheets. And here’s the most extreme case of overrides we’ve found so far.
body {
margin: {margin}px !important;
}
…
* {
page: auto !important;
line-height:normal !important;
-webkit-box-sizing: border-box !important;
-webkit-text-size-adjust: {font-size}% !important;
box-sizing: border-box !important;
background: transparent;
background-color: transparent;
max-width: {pageWidth}px !important;
text-align: {text-align} !important;
word-break: break-word !important;
padding: 0;
margin: 0;
}
*, * *, *[class], *[class] *[class] {
background: transparent !important;
background-color: transparent !important;
border-color: {foreground-color} !important;
line-height: {line-height}% !important;
text-align: none !important
}
html, html * {
color: {foreground-color} !important;
}
a[href], a[href] * {
color: {anchor-color} !important;
text-decoration: underline !important;
}To put it simply, this breaks the conceptual model of inheritance. No more, no less. I had never ever seen the * universal selector used in combination with “!important” before. The goal of the whole CSS is just to annihilate the author’s CSS. By any means necessary.
So we’ve got ourselves a new set of issues to cope with. And this is the reason why we decided to limit the framework’s official support to a list of Reading Systems we can deal with.
Simplify and debug
Keep it simple, stupid.
Building a framework is a tough job, especially when you must take default CSS, overrides and user settings into account.
To sum up, it takes an awful lot of simple solutions to get around those complex issues.
And as a result, the Blitz eBook framework was designed around mixed feelings:
- whether we like it or not, we have to rely on RS’ default CSS and we don’t have the choice. If we define text color for instance, we are taking the risk it may not be overridden in night mode; this creates a terrible user experience. The same can be true for body’s height, margins and max-width (line-length).
- we wished we could create a “normalize” but it became a “reset” given the magnitude of the task.
- some style overrides may be pretty difficult to manage for RS’ developers e.g. border color in night mode, hr styling, etc. We’re trying to help them a little bit (extended use of values inherit and currentColor) but it limits what authors can do. Dramatically.
- though we try to manage vertical rhythm, we obviously know overrides can break it the second after the file is opened or as soon as the user sets a different line-height (margin-top and -bottom won’t be overriden accordingly).
- the impact of legacy RMSDK on Blitz’ design and, more broadly, eBook CSS authoring is gigantic: there are so many things you must do to be RMSDK-compatible that it’s no wonder people coming from the web may have difficulties dealing with it.
- media queries are another issue as there is currently nothing to deal with the column or container’s width some Reading Systems are setting. You must target devices hence make choices: if you target iBooks on an iPad for instance, which is using columns to fake a spread, you might be leaving other iOS apps, which don’t, besides. Moreover, such an approach is simply unmaintainable over the long term. Since we can’t rely on media queries, the default type scale has been chosen accordingly.
We tried to do our best. It’s not perfect, it’s compromised though opinionated in some places but it works. And this was not the obvious outcome once we started documenting Reading Systems’ default CSS.
Reinventing my practice in one week
We’ve got a reset, an engine computing vertical rhythm automatically, a lot of functionnal classes and media queries to target specific devices… Is it really what we need?
I doubted for a while. I was not really sure Blitz was the best we could do and that is why I took one week off to reinvent my practice. I went as far as creating another eBook framework adopting a minimalistic approach: resetting absolutely nothing, just correcting the oversights of default stylesheets and building on top of them, calling it a day. At least I learnt a few things I could reuse in Blitz. And those things did improve Blitz in the end.
I even tried designing with no type scale at all. Everything font-size: 1em and let’s see how I can deal with this limitation. Credit where credit is due, Frank Chimero did it first.
In parallel, I started using Blitz for other projects like Soma, an Ulysses 3’s ePub theme, or eBookDys, a stylesheet enforcing dyslexia’s best practices.
Blitz framework seemed to work great but, well, I am the guy who built all its (preprocessor) abstractions and I know how to leverage every variable and mixin. We had got rid of stuff that bloated it like, say, dangerous hacks, but still, I wasn’t 100% sure Blitz could meet its potential users’ expectations.
With a framework comes great responsibility and I must confess I was doing pretty much anything to delay its publication…
Fuck it, rock the casbah
That looks like a leap of faith, doesn’t it?
Being the guy people mention in their workshops/presentations is kind of amazing and burdening at the same time. And this is exactly what happened at eBookCraft 2016. Once. Twice. Thrice.
You’re on the other side of the Atlantic and all of a sudden, you’re being quoted, your repo is listed as a reference and your rants are becoming legendary — nah, just kidding, I hope they don’t, really.
But, well, the Blitz eBook framework had not been released yet because I was still trying to improve it a little bit. With eBookCraft, I discovered my side projects could really be useful to the community.
It’d been 18 months at this point, and Blitz was still in closed beta. Truth is CSS authoring had some momentum in the EPUB revision and it felt like providing the working group with a documented version of Blitz as a practical example could help.
So I asked Romain Deltour and Dave Cramer if that would indeed be the case. And they answered it would be a useful thing to have — seriously, if you have something to say, just speak up, it’s worth it. Consequently, I documented every part of Blitz within a day and wrote an abstract
Here are excerpts from the abstract I sent to the working group — minor edits in some places.
The Blitz eBook framework is an open source project which aim is to solve the various problems people may experience when styling EPUB (and Kindle) documents.
It currently consists of a LESS/SASS design system, a default CSS and an EPUB 3.0.1 template.
Design & Goals
Blitz was designed to deal with the significant obstacles a newcomer or even an experienced producer might encounter. Its major goals are:
- to be simple and robust enough;
- to offer a sensible default;
- to manage backwards compatibility (ePub 2.0.1 + mobi 7);
- to provide useful tools (LESS/SASS);
- to get around reading modes (night, sepia, etc.);
- to not disable user settings.
We have chosen a functional approach (FCSS) but LESS/SASS “plugins” are planned to provide meaningful class names depending on eBook’s type (poetry, plays, etc.).
Principles
Blitz is leveraging the concept of inheritance. Values inherit and currentColor are being used extensively to make the framework compatible with Reading Systems’ default stylesheets, reading modes (color) and user settings (font-size, font-family, line-height, etc.).
Defaults and a reset do the heavy lifting so it’s just about building on top of this base. Please note Blitz is taking care of defaults RS aren’t necessarily (HTML5 block elements, hyphens and pagebreaks for selected elements, etc.).
Finally, although we try to rely on RS’ typefaces, typography has been fine tuned.
- The default scale (power of 1.125) has been chosen to handle various situations well enough (screen/container size, user increasing font-size, typeface used, etc.)
- Vertical rhythm (line-height + margin and padding) is automatically computed in LESS/SASS to enforce consistency. By taking care of vertical rhythm, we’re also achieving horizontal harmony when the eBook is rendered on a (fake) spread: “everything text” lines up on the same baseline grid, which makes for a more comfortable reading experience.
- sup and sub styling is improved to prevent them from affecting line-height.
- The whole §8. Breaking Within Words is implemented in LESS/SASS.
To sum up, we’ve tried to find a balance and feel like Blitz defaults can help producers get around a lot of possible issues: we don’t need hacks, we don’t have to change values in specific situations using complex media queries.
Guess what? I hate documenting things and some other stuff proved to be the last straw that breaks the camel’s back so I pushed the initial commit of Blitz to Github on April 12, 2016.
I know it works. Perhaps clumsily, but it works. And right now, if we’ve made crap, I just want to know.
My parents have been constantly teaching me to stand for what I think is right. I know Reading System developers must manage crap, and I want to help eBooks achieve higher quality. Maybe this is meaningless — it’s a first world problem after all — but at least I can now say that I’ve tried doing something useful.
Consequently, it’s no wonder that, to some extent, pushing the initial commit was a relief. Today, while writing this piece, I know I did the right thing. So it’s up to you now to show me I really did, to prove me those 18 months were worth it. I hope Blitz can make an impact but it’s not my creation anymore: it is a community project I’m in charge of from now on, and it needs your help.
So, if you want to help, you’re most welcome. It’s currently a pre-release and there is still a lot of work to do—please note that if you don’t dig refactoring and maintaining, there’s a lab you can consider a playground.
And this, ladies and gentlemen, is how the Blitz eBook framework was born and how I grew as a human being—I’m still terrible at this but at least I’m trying to learn. Thanks to everyone who has taken part in this story; they know really well who they are :)
