Defining a minimal default stylesheet in the epub spec

[acabal]

Tangentially related to #671.

AFAIK there is no default stylesheet that epub-compatible reading systems are required to implement, like for example https://www.w3.org/TR/CSS2/sample.html

This leads authors down a path of IE6-era guesswork hacking when composing ebook stylesheets. Since each reading system has its unique stylesheet and unique set of CSS properties that can and cannot be overridden by the ebook, authors must resort to complex, fragile hacks and over-complicated CSS to make their single epub file look good on the most possible reading systems.

Even then, some reading systems will invariably be left out, and the final epub may not stand the test of time as default styles invariably change with the introduction of new reading systems with their own unique defaults. This is a huge waste of developer time and a constant frustration in the ebook community: see, for example, Liz Castro's detailed archives on the vagaries of epub styling going back years.

Furthermore, many authors simply do not have physical access to the vast amount of ereading devices out there, making testing against today's jungle of defaults impossible, let alone tomorrow's jungle.

In short, epub developers today are where web developers were in the IE6 days. It took us years to solve it for the web--why not apply those lessons to epub today?

Solution: Defining a simple, minimum stylesheet that compatible reading systems are required to implement would go a long way to making the life of ebook authors easier. If authors had clear and unambiguous knowledge about what elements have what default CSS, they could very easily override exactly what is needed without hacks, ensuring their final epubs look as intended across all epub-compatible devices, today and tomorrow.

Developers of epub reading systems would have a simple point of reference to work off of, and be secure in the knowledge that ebooks produced with the epub standard in mind would look as intended on their devices.

[JayPanoz]

Since I discussed that with @rdeltour a few nights ago and for what it's worth, I kind of agree and I do think it is a broader issue.

Lately, lack of harmonization and documentation of overrides & settings pushed me to the "nuclear option" a.k.a. digging RS' default stylesheets out. I'm not doing this out of love or insanity; I'm doing it because there is no other choice.

To sum things up, the current state of default stylesheets is really, really, bad.

1. some RS just ignore authors' stylesheets entirely while their default stylesheet is incomplete, which can lead to huge failures, even if your documents have no stylesheet and are structured using basic HTML5.
2. I've witnessed a lot of epic CSS hacks in the last 5 years to… say… get around some iBooks' overrides – it seems to be my peers' favorite sport. Problem is very often those hacks were not tested anywhere else and led to epic failures in other RS. That's an authoring problem for sure: “with CSS hacks come great responsibility”, which is why I'm – and others are – weighing the pros and cons of hacks but others, like say InDesign users who can't do something because the feature is not yet implemented are often willing to do what it takes to make it happen, e.g. abusing epub:type to make a frame scrollable – I'm comfortable throwing them under the bus since InDesign CSS' output breaks so many things on so many levels.
3. Developers of authoring software having no reference, they unintentionally end up outputting CSS that breaks things in different RS.
4. Since a lot of RS developers have chosen not to support alternative stylesheets, e.g. night mode, and are using complex systems to manage authors' stylesheets in those situations, it usually becomes a "Charlie Foxtrot" really fast.
5. It seems there are everlasting trends which I would rather define as gimmicks on RS' side. For instance, a few of them are really eager to push their branding through links' color, which may result in links that don't meet WCAG 2.0 requirements (4.5:1 contrast). I don't know about you guys but I don't find it normal that we must use CSS hacks to get basic a11y right.
6. Regarding users' settings, it's became such a mess that you actually have to use CSS values some RS don't support in order to not disable basic settings, e.g. line-height: inherit. And I'm not kidding.
7. From experience, I know that any RS' dev will tell you they don't override because they can but because they must, authors' stylesheets being low-quality overall. Problem is it's turned into an arms race and in my “humble-as-in-small-opinion”, this issue should be addressed sooner than later if we want it to stop. In users' interest.

Regarding this last point, I can indeed confirm a lot of eBooks I'm buying (as a user) disable different users' settings in different apps. This is nothing new, it makes everyone's life miserable but somehow it went unaddressed. As a result, I feel like we're stuck in a highly-dysfunctional system, which is extremely depressing since any change or bug on one RS' side may potentially trigger a catastrophe.

FYI, 18 months ago, I started working on a simple CSS framework to help others tackle the issues I've encountered during the last 5 years. I thought this project would take a few weeks, it is yet to be published and I'm constantly revising it as the deeper I'm digging in my research, the weirder stuff turns out. Between distributors altering styles and RS overriding them, including some obscure conversions to epub-based formats (KePub, Google's stream, etc.), it is currently impossible to not screw things up.

I'm not saying we should add mandatory stuff into specs, this would likely fail anyway since a lot of people, especially the ones developing Android apps, are already ignoring mandatory part of the specs. I'm just saying this whole CSS stuff is indeed a problem for some right now and it would be a relief to see people discuss and help one another instead of playing cat and mouse.

I don't have any solution but well, maybe a CSS framework could help. A "Can I Use" dedicated to epub could definitely help too. But hey, that requires a collective effort for sure.

[acabal]

I also want to point out that this issue may be a non-negligible factor in driving authors into Kindle's awful ecosystem. Kindle is already the 800-lb gorilla of RS. When a small indie author tries to make their book look nice, why should they go through the hassle, headache, and expense of figuring out the crazy CSS exceptions on every single epub-based RS out there, when they can just say "screw it, I'll make it look good on a Kindle since that's where 80% of my sales will be anyway, and not bother with the other platforms". Each time that happens Kindle's closed and developer-hostile ecosystem gains an author and epub loses an author--a net loss for advocates of open source and open literature.

I'm not sure a framework would solve the issue; if RS are already ignoring standards, then that suggests they won't make any more effort to stay compatible with a framework. Frameworks work great for the web because they can be updated and tweaked live, and each time a person visits a site they can be presented with current fixes for evolving standards. But epubs are deployed and then not changed--rather, it's the RS that changes over time with firmware updates. Therefore the shifting sands of RS stylesheets may, at a later date, move under the static framework's feet, rendering it useless.

The only sane solution that comes to mind is to define a minimal default stylesheet, and require RS to implement it if they want the "compatible with epub" stamp. Since this stylesheet would be part of the core spec, it would not change over time, and epubs published at a fixed date targeting a fixed version of the spec can be guaranteed to look the same on compatible readers 10 or 100 years from now.

Getting RS to implement such a solution is certainly a political problem. The only way we can move forward on that political front is to be loud about how much styling epubs sucks, like developers did with IE6. Back in those days, once developers started complaining really loudly the crazy out-of-spec implementations of the HTML/CSS standard converged and we got the nice, mostly-homogenous development landscape we have to day. But that took years, and so we can't wait any more to start with epub.

[JayPanoz]

Well. Rest assured that I strongly agree it is an “ecosystem issue” and that harmonization is probably necessary. RS default's stylesheets are an issue; sometimes you're even wondering if some put an intern in charge on his first day and the poor fellow had to deal with it during his break.

Now, it's been 5–6 years and a lot of folks created workarounds – even CSS hacks for basic needs like images with portrait aspect ratio – and reported issues to RS devs. For instance, I've opened dozens and dozens of tickets on Apple's bug reporter, sent so many emails to apps' devs I can't even keep track, discussed the issues with some willing to talk about it – and that is pretty scarce –, tried to shake Google, which dev team seems to make itself unavailable, out of its lethargy by publicly digging up all the dirt with the Play's community manager, etc. So yeah, with others, we may have reduced our level of ambition and decided to go the "baby steps" approach.

Do not think of this framework to which I've referred as a framework but rather as the missing bedrock. In other words, its main goal is to deal with fundamental stuff (like resetting HTML5 stuff so that aside, section, etc. display as block, something you won't find in the vast majority of RS default's stylesheets…) and with users' settings (i.e. the CSS doesn't disable any of those, whenever possible). Then you add your styles to this bedrock and that's it.

Since we feel like the vast majority of RS devs don't care, and since the issue has gone unaddressed for so long, that's all that's left. To me that's just pragmatism. Obviously it is not a silver bullet but if it can help others, that's cool. And if that stirs some RS devs because they need action on our part to become aware of the issue, it will be even better. Don't forget the web had to create CSS resets, JS polyfills, etc. The web has built an undervalued culture of improvement and it's certainly something we lack in eBooks today.

There's another point I'd like to address: how this issue is worded.

I recognize my conceptualization may be pretty personal but to me, it's not about “producers – readers – RS devs”.

That is how we deal with it and it certainly doesn't reflect my daily work. If I had to define it, I would say that "my job consists of finding a compromise between the text and the reader, and advocating for the user 'vis-à-vis' the publisher".

Text is a logical framework, phrasing calls for rhythm. The moment an RS dev applies an override at the block level, he's taking a risk to break the logical framework of some books, hence deteriorating comprehension. This is especially true for essays or, more generally, non-fiction.

A simple stylesheet can't necessarily be used for all books. Text needs nuance because all authors don't write the same.

Besides, in some languages like French, we have fundamental nuances we must deal with. For instance, a paragraph is not <p>. We're making a distinction between "paragraphe" and "alinéa" (indent) so a paragraph may be a sequence of indented <p> – for better or worse, we haven't any semantic tag for that so the distinction is purely visual.

Needless to say that if you override paragraphs (getting rid of indent and adding vertical padding/margin for example), then you're taking this nuance away, a distinction which may be critical in making sense of the text, especially if the author's phrasing is complex.

And that's pretty impossible to take into account, for both overrides and users' settings. The best case scenario is RS devs providing with themes and the user picking the one that suits the logical framework of the text.

So yeah, I'm a little bit uncomfortable with the wording "producers – readers – RS devs". Book design is certainly a lot more nuanced than this implies. But as KFX tends to demonstrate, we're focusing on H&J, drop-caps and what we consider bookish stuff instead of asking “text designers” what their job is.

To sum things up, this whole CSS issue may be a lot more complex than we guess it is at first glance. And that is the reason why I do believe we should not put all our eggs in one basket.

Would a default stylesheet at the spec level help? Yes, obviously.

Would technical harmonization in overrides + users' settings help? Yes, definitely.

Would a CSS framework help? Yes, I know it can help since the free templates I'm distributing are used by hundreds of people who feel lost, including students which are being lectured because they don't even get rid of my comments – that's also the reason why I'm committing to the framework in the first place, moral obligation and stuff.

It's not something we can solve out easily. But we should at least be clever and learn from the web, which had to deal with this before. I don't feel like it is about "keeping the producers happy" has @rdeltour reported it was said in WG (hashtag eprdctn on twitter), it's about building a culture and it demands multiple efforts, anywhere.

A strong culture could help prevent overrides/RS CSS justifying and/or hyphenating headings for instance, something I'm doubtful we would think about in a default stylesheet. And the same goes for a lot of stuff, like say hr per HTML5 spec (thematic break = asterism in books).

P.S.: Please excuse this monologue, especially as our vision is pretty much the same.

[dauwhe]

HTML5 has a "suggested default rendering". EPUB 3.1 could say that reading systems should or must support the suggested default rendering, but I'm not confident that many reading systems would actually do that. We'll try to gather some information from reading system vendors.

[acabal]

@dauwhe if we do go that route, it must be defined as "must". "Should", will, of course, be ignored by some or all RS, which defeats the entire point of having a common default across all RS. We'd be back to where we started, or worse, since we may have squandered an opportunity.

What might help in getting RS to adopt that implementation rather than ignore it is some kind of official "works with Epub" endorsement. Giving RS permission to advertise their products with some kind of approved validation from the Epub group would be a marketing bullet point for them. Much like the HTML5 "shield" logo took off: people took pride in displaying the HTML5 shield to indicate they complied with the latest and greatest standards.

[dauwhe]

Possible spec language:

In addition to supporting CSS properties as defined above, an EPUB Reading System's user agent stylesheet MUST support the suggested default rendering as defined by the HTML5 specification.

[rdeltour]

Possible spec language

In case anyone wonders, and since I had to look this up, "support the suggested default rendering" has a special meaning here, defined as a conformance class in HTML5

[dauwhe]

Even looking only at html and body, it's interesting.

HTML 5 spec (w3c version):

html, body { display: block; }

Then there's a fun paragraph and table, that AFAIK means that in the absence of other stuff the body should have an 8px margin

Webkit UA stylesheet (not ebook-specific)

html  { display block }
body { display: block;  margin 8px }

Adobe Digital Editions:

html {
    height: 100%;
    margin: 0;
}

body {
    height: 100%;
    width: 100%;
    margin: 0;
    padding: 10px;
    position: absolute;
    overflow: hidden;
    box-sizing:border-box;
    -moz-box-sizing:border-box; /* Firefox */
    -webkit-box-sizing:border-box; /* Safari */
}

Barnes and Noble:

html, body {
    margin:0;
    padding:0;
    height:100%;
    width: 100%;
    overflow:hidden;
}

body {
    background-color: #5a5b5a;
    color:#333333;
    font-family: arial, helvetica, sans-serif;
    font-size:12px;
    -webkit-user-select:none; /* disable text selection */
    position:absolute;
    left:0;
    right:0; 
    top:0;
    bottom:0;
    text-rendering: optimizeLegibility;
}

Google Play Books:

body {
    margin: 0;
    padding: 0;
    font-size: 13px;
    font-family: arial, sans-serif
}

Readium:

html {
    height: 100%;
    margin: 0;
    overflow: hidden;
}

body {
    height: 100%;
    width: 100%;
    margin: 0;
    position: absolute;
    overflow: hidden;
    box-sizing:border-box;
    -moz-box-sizing:border-box; /* Firefox */
    -webkit-box-sizing:border-box; /* Safari */
}

I wonder if it's possible to get some agreement from reading systems on how to handle the margin on body.

[acabal]

Yeah it's no secret that styling an ebook is an exercise in insanity :)

I'd be very surprised if a standards body could convince all RS developers to agree on and change their default stylesheets in one fell swoop. Very unlikely to happen, though that would of course be the best possible outcome.

A possibly more pragmatic path might be to pick a sane default, like the HTML5 spec you linked to, and bless it as the epub "required minimum". Ebook producers could then target that minimum, and over time RS developers might feel pressured by the amount of producers targeting the minimum to build conformance into their products.

Then again, they might not. Even in 2016 each major browser still has its own minor default stylesheet quirks and CSS resets are necessary. But since epub 3.1 appears to be taking a stance on ideological purity on a lot of other issues, why not this one too?

[acabal]

BTW @dauwhe can I ask where you found those default styles listed? I'm curious to study them more closely.

[dauwhe]

Found this incredibly useful repo (thanks @JayPanoz!!) which has ebook style overrides: https://github.com/FriendsOfEpub/WillThatBeOverriden

Webkit html.css is from the webkit source code http://trac.webkit.org/browser/trunk/Source/WebCore/css/html.css

[bduga]

I am not sure where you got those lists of styles, but they are almost
certainly not really correct. For instance, Google Play Books has 3
clients, that display content in large resizable windows, very small
phones, and large fixed size tablets. A single base style for all those
form factors is difficult. For instance, going nearly to the edge of the
page makes sense on a phone, but less sense on a 30" monitor. Yes, ebook
content can adjust for that case using @media queries to some extent
(depends on actual implementation of things like 2-up), but the reality is
most ebooks do not do that. In fact, it is rare enough that a bug in our
@media handling went unnoticed for quite some time. I think we should also
consider why reading systems have such different margin rules. We apply
different margins based on the device size, platform, and content type. To
date, the margins specified by epub content has been all over the place -
sometimes assuming reasonable margins, sometimes assuming no margins,
sometimes placing content off the visible page with negative margins. The
reality is we have a long history of content making different assumptions
about the default margins and we have adapted our display code to handle
most cases reasonably well. And no, it is not all done with CSS, we do have
Javascript that helps make some decisions/corrections. If we were to
enforce, say, 8px margins, our existing corpus would be badly broken. We
could enforce it for content that claims to be epub 3.1, but the ability
for reading systems to stop playing with default styles will require much
better styling in the source ebook content. When a customer comes to us and
says "gee, this content looks terrible/is missing stuff" it's hard for us
to say "well, that's what the author wanted. But here, have a pretty
sticker."

On Thu, Mar 17, 2016 at 8:51 AM Dave Cramer notifications@github.com
wrote:

Found this incredibly useful repo which has ebook style overrides:
https://github.com/FriendsOfEpub/WillThatBeOverriden

Webkit html.css is from the webkit source code
http://trac.webkit.org/browser/trunk/Source/WebCore/css/html.css

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#672 (comment)

[dauwhe]

@bduga, I simplified from the three files that were ostensibly about GPB: https://github.com/FriendsOfEpub/WillThatBeOverriden/tree/master/ReadingSystems/Google%20Play%20Books

This feedback is really useful. Thanks!

Maybe this is another example of the truly fundamental difference between the web at large and the EPUB ecosystem. On the web (in general), you run your content on your servers. In EPUBland, you run someone else's content on your servers (broadly speaking). Hence the issues with scripting. Here, reading systems need to mitigate horrible authoring, as well as get content to display well in a complex environment where there is much more html/css than in the EPUB.

So should EPUB address this on the authoring side? Say you can't put margin: 50% on ? It seems a free-for-all doesn't really work well for anyone.

[rdeltour]

We could enforce it for content that claims to be epub 3.1, but the ability for reading systems to stop playing with default styles will require much better styling in the source ebook content.

Can this is be mitigated with a new property rendition:default-css in 3.1, that would toggle RS style overrides?

[mgylling]

Can this is be mitigated with a new property rendition:default-css in 3.1, that would toggle RS style overrides?

A tangentially related topic here: https://groups.google.com/forum/#!topic/epub-working-group/ybmulvP4eqQ

[dauwhe]

Can this is be mitigated with a new property rendition:default-css in 3.1, that would toggle RS style overrides?

Just noting that Apple has various magic incantations you can place in META-INF/com.apple.ibooks.display-options.xml that "turn off" various reading system overrides.

[bduga]

@dauwhe I do think we there is a difference, though there is still the browser on the web. It is easier to test with multiple browsers than it is multiple reading systems, due to stores, DRM, etc. There are just inherent roadblocks in the ecosystem. And I hesitate to blame content. It is more an intricate, evolved web of reading systems accounting for weird content, and content doing weird things to account for reading systems. But it means we have a stack of books that are a problem.

@rdeltour Interesting idea. So not toggled on 3.1, but essentially blessed. "This content assumes default styles".

[iherman]

On 17 Mar 2016, at 20:44, Dave Cramer notifications@github.com wrote:

Can this is be mitigated with a new property rendition:default-css in 3.1, that would toggle RS style overrides?

Just noting that Apple has various magic incantations you can place in META-INF/com.apple.ibooks.display-options.xml that "turn off" various reading system overrides.

This is completely a side issue but: really? Where is that documented? (I had to modify the CSS of some of my generated epub files which is really really ugly due to Apple's manipulation of the margin. If there was a better way of doing that, I would be happy…)

[dauwhe]

Might it be useful to collect a list of common problems in this area? Just for a start:

1. margins on body
2. default styling of new HTML5 elements (section, aside, etc)

[danielweck]

Hello, I will try to allocate some time to document what DOM and CSS manipulations Readium performs when rendering fixed-layout and reflowable documents (in both the paginated and scroll view modes), and depending on right-to-left, vertical-writing-mode, etc. I will report back here.
Issue tracked: readium/readium-shared-js#276

[bduga]

@dauwhe Some more for the list, mainly user adjustable:

Font size
Font family
Line height
Background color
Text color
Text alignment

[rdeltour]

@dauwhe I drafted a proposal for a new rendition:css-overrides property. Let me know what you think (you and @mattgarrish have editor rights, anyone can view and comment).

[dauwhe]

Thanks @rdeltour ! This looks good. Perhaps we should clarify that this shouldn't affect user preferences (users should be able to override user agent or author styles). And there's some overlap with the default UA stylesheet issue, unless the author does a very thorough reset.

[bduga]

I am a bit concerned with this. While it does still allow user settings,
not everything we do to the content is related to a user setting. For
instance, we adjust the default font size based on device size and density.
If we don't, then we can get a very poor initial reading experience. Would
that change now be disallowed?

On Fri, Mar 25, 2016 at 6:30 AM Dave Cramer notifications@github.com
wrote:

Thanks @rdeltour https://github.com/rdeltour ! This looks good. Perhaps
we should clarify that this shouldn't affect user preferences (users should
be able to override user agent or author styles). And there's some overlap
with the default UA stylesheet issue, unless the author does a very
thorough reset.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#672 (comment)

[acabal]

@rdeltour interesting proposal. A default stylesheet would still be necessary though: for example, if an ebook producer set rendition:css-override to none, without a default stylesheet in the spec they're still left with the fundamental question of "what CSS styles do I have to set to make this ebook look the same on every RS?" Unless when none is set then there are absolutely no RS-set CSS styles at all, and the ebook producer has to define previously-implied defaults like p{ display: block; }. But in that case producers would be stuck with including a big CSS-reset-esque stylesheet anyway and we're back where we started.

I'm also not sure if rendition:css-override isn't just skirting the issue. As an ebook producer my goal is to make my single ebook file look the same on every RS. In pursuit of that goal, why would I ever set rendition:css-override to anything but none? And again, then we're kind of back where we started.

Overall I still think the best way to approach this issue is to fully embrace epub's heritage and future as a web-based technology--thinking of an epub as just a website frozen in time. In the web's ancient heritage, browsers were very much like today's ereaders--different browsers had different defaults styles and supported different CSS properties in different ways. Over the years they realized what a pain in the ass that is for producers, and they all converged to nearly-identical default styles that are--and here's the key--largely based off of default recommendations defined in the HTML spec.

[rdeltour]

@rdeltour interesting proposal. A default stylesheet would still be necessary though: for example, if an ebook producer set rendition:css-override to none, without a default stylesheet in the spec they're still left with the fundamental question of "what CSS styles do I have to set to make this ebook look the same on every RS?" Unless when none is set then there are absolutely no RS-set CSS styles at all, and the ebook producer has to define previously-implied defaults like p{ display: block; }.

Right, the proposal of the rendition:css-overrides property isn't mutually exclusive to @dauwhe's suggestion to follow a default rendering (as defined in HTML).

But in that case producers would be stuck with including a big CSS-reset-esque stylesheet anyway and we're back where we started.

Not really. RS-defined CSS overrides are apparently sometimes quite extreme today, notably when using !important properties that cannot be overridden by the author. By using the none mode, you'd have 1. fewer default CSS styling to handle and 2. guarantee that there are no forced override.
Using a simple normalize.css is an acceptable practice, even on today's Web targeting modern browsers.

I'm also not sure if rendition:css-override isn't just skirting the issue. As an ebook producer my goal is to make my single ebook file look the same on every RS. In pursuit of that goal, why would I ever set rendition:css-override to anything but none?

Basically for the very good reasons stated by @bduga: a big amount of EPUB content would cause readability issues without the current RS style fixes.

Overall I still think the best way to approach this issue is to fully embrace epub's heritage and future as a web-based technology--thinking of an epub as just a website frozen in time. In the web's ancient heritage, browsers were very much like today's ereaders--different browsers had different defaults styles and supported different CSS properties in different ways. Over the years they realized what a pain in the ass that is for producers, and they all converged to nearly-identical default styles that are--and here's the key--largely based off of default recommendations defined in the HTML spec.

I generally agree, but what we're targeting here is EPUB 3.1, not EPUB 4 or whatever it may be called :)

[JayPanoz]

I must admit I'm a little bit concerned too. While I, as en eBook producer, am opinionated, reason tells me there's a potential for “abuse” i.e. popular authoring software outputting <meta property="rendition:css-overrides">none</meta> as default. That would probably force RS to ignore the meta entirely.

After all, that’s what InDesign is already doing for com.apple.ibooks.display-options.xml (ePub 2.0.1) and <meta property="ibooks:specified-fonts">true</meta> (EPUB 3). Now, that can go really wrong depending on the quality of the InDD source-file, trust me. And should the embedded fonts not be thoroughly tested by the author and not rendered properly by the RS, which actually happens a lot, we've got a recipe for a poor initial user experience.

I do have compassion for RS devs because they sometimes have to deal with nightmarish files and this is why they override in the first place—at least that's what they tell me… when they are willing to communicate. And you’ve also got those cases for which something must absolutely be overridden or else there will be rendering issues, e.g. iBooks targeting and overriding some very specific Calibre’s styles (resetting to position: static + a “centering hack to support Calibre-generated vertical centered documents”).

On the other hand, there are some cases for which such a meta could prove useful, especially when it comes to a11y. Dyslexic readers may have specific needs (preferred typeface, background-color, etc. which are not offered in the RS), elderly people who might push the font-size to 36pt (see picture below), etc.

In that extreme case, I guess everything should be font-size: 1em, even h1?

By extension, that also reignites alternate stylesheets and their pretty non-existant support….

And of course we’ve got those RS’ defaults stylesheets abusing the universal selector, which also “!important all the styles” because yolo. That can lead to unexpected failures. In this case, why not ignoring the author’s CSS entirely?

All in all, it's not overrides that bother me much but the lack of documentation, which is the reason why I decided to take any necessary action to document on my side—I'm wasting weeks doing it, which is a huge hit when you're a freelance by the way. My purpose isn't even overriding the overrides as I gave up pixel-perfect a long time ago, but understanding RS to achieve the best UX possible—and help a little bit, like with this a11y-focused project. I therefore warmly welcome the note at the end of the proposal.

That being said, should a default stylesheet be spec’ed, and that's just my humble opinion, it should be 1. minimal and 2. trying to take realities into account. A 40-pixel margin-left and -right, as is the case for blockquote and figure in HTML5 suggested Rendering, is gigantic on a smartphone. Maybe a % value could do, given RS have decided to “paginate” by default? And 2em is also problematic on a smartphone for instance: should the user increase font-size, this value creates a lot of issues (text-wrap, line height, margins, etc.)

Problem is, whether we like it or not, eBook design/dev is currently not like web design/dev as there is an additional layer we must deal with: the renderer/paginator. And we're back to what @bduga posted a few hours ago. Those guys are dealing with a paginator (ocean.js in the case of Google if I'm not mistaken) + a huge amount of potential cases so they need some flexibility. Maybe suggesting not styles but elements which must be minimally styled could be an option? I don't know, I'm just trying to understand what their needs are, how some specs could impact them and if we can reach a compromise.

[caraya]

@rdeltour I don't think that pointing to the HTML5 specification and saying do what they say is going to be enough. If I read that correctly that's an optional requirement for User Agents where it should be mandatory for Reading Systems.

We also need to take display size and accessibility into consideration. Does the default style sheet renders the same in a phone or a tablet as it does in a desktop system? (No, I don't think it does or ever will) Do we introduce media queries by default to accommodate the differences?

Personally I'd like something like normalize.css for ebooks as a default stylesheet. We can use this stylesheet not only create a default but also a baseline that normalizes the most glaring discrepancies between readers so designers can build on top of this.

[JayPanoz]

Now that I think about it, I'm a little bit uncomfortable with the fact we don't hear from authoring software developers. And that also explains my compassion for RS devs I guess.

Authoring software devs’ interests are not necessarily the same as RS’ and readers’. The end-user of an authoring app is sort of a book designer, and that impacts the output’s defaults in many ways.

Take InDesign for instance. By default, it outputs for both ePub 2 and EPUB 3:

• embedded fonts, whichever their licence or format are, which can create rendering and licensing issues and that's why there are so many embedded system’s Georgia, Times New Roman, Helvetica, etc. out there;
• color for almost every CSS element but characters and char-overrides;
• line-height: 1.2 if you don’t pick another one or, even worse, use a baseline grid;
• images in pixel dimensions, computed using the spread as a reference, the wrapper using display: inline-block, which not only creates issues in some RS (cut image displayed on two pages) but also isn't supposed to be in the ePub 2 spec.

If you don’t want ID to output fonts, pixel dimensions, styles for specific elements, etc. you actually must uncheck options. But, on the other hand, if they don’t check some options by default, a wild bunch of end-users may complain so I admit it’s a complex issue. Consequently, outputting this meta by default seems like the logical choice.

Very often, the approach WYSIWYG devs have chosen is drawing documents to ePub/HTML. They won’t try to prevent bad design choices with sensible defaults, they’ll just do their utmost to meet users’ expectations. I know, I’ve witnessed custom-made software use tables, divs and spans to layout EPUB 3 eBooks so that RS can’t override any style of those files. The publisher wasn’t even informed, it discovered it when asking me to audit the files… which had a lot of rendering issues.

That should clarify “abuse” in my previous comment. That might also explain why I consider this a global issue we can’t necessarily fix with specs, once and for all. While I understand “authors” want some freedom, I’m also aware RS have to deal with Charlie Foxtrot and too bad if “authors” who care are casualties. In the end, to me, it feels like this issue is revolving around responsibilities, for what it's worth. And say if an author doesn’t want to take responsibility for the styling, he should probably be assured a good fallback is provided in the RS. On the contrary, if he does s**t, the RS can claim the responsibility for improving (ignoring the stylesheet, applying overrides, etc.). It’s not about a switch, it’s about context I guess.

P.S.: I’m using InDesign as an example only because it is one popular piece of authoring software. There is an awful lot of other apps/solutions automatically outputting com.apple.ibooks.display-options.xml and <meta property="ibooks:specified-fonts">true</meta> for instance, even A.S. exporting a minimal stylesheet which is more of a boilerplate than anything else. In that case, you’re just imposing Times New Roman to iBooks’ users, and oh boy this typeface is really thin and can be uncomfortable on Retina.

Also, has anyone asked Apple how much used they were and how many times (or percentage) they were disabled by users? Cos’ if it’s a technical debt for them in practice, perhaps we should think twice about it—my understanding is that they've been regularly limiting its scope, e.g. ignoring links’ color since iOS9 in order to provide a gray background or more simply because users couldn’t tell a link from text since some authoring apps and eBook producers were using inherit without any differentiating style.

[rdeltour]

This is getting in many directions, which can be hard to follow. This is my (possibly too naïve) understanding of the issue, please correct me if I'm wrong or if I missed some aspects:

1. most RS implement proprietary style overrides to improve the readability of content (including poorly-styled content).
2. book developers and authoring tool vendors have difficulty to cope with those RS-provided style overrides due to the lack of harmonization
3. some book developers would like to have more control on they styles –like they would have on the Web– without worrying that RSs will brutally override them.

The proposal for a rendition:css-overrides property only intends to tackle the last point. A value of none basically means "bring your own styles, we won't mess with it". A couple comments on this proposal:

• it can only work if RS play ball and do support this property (maybe the proposal should be changed to make supporting the none value a MUST?), even if at first some poorly-authored content renders badly. It is essential that we get feedback from RS vendors before making it into the spec.
• it also requires that media queries can be relied upon, see Media Queries #685. This may be the elephant in the room.
• if Authors or authoring tools produce bad styles with the none mode, so be it. It's their responsibility and bad content/readability will ensue, like lousy web sites are developed every single day. The hope here is that good content and best practices will also be developed and can be used as reference, getting us closer to today's Web development practices.
• developing a normalize.css for the none mode would be a bazillion times easier than developing one that would handle the current RS style overrides.

Now, the 2 earlier points in the the issue statement are about harmonization of the RS style overrides. This is totally independent from the none mode proposed above. I honestly don't know how to best approach this, but this is definitely important.
Requiring a single common default stylesheet seems too naïve, as RS have to cope with legacy content. Developing a single nomalize.css sounds difficult too, given the very complex style overrides that the RS are applying (sometimes from Javascript).
I would also agree that simply mandating the HTML suggested default rendering may not be the right solution, as @JayPanoz and @caraya noted.
Suggesting that RS provide public documentation is one thing (although it cannot be "mandated" in spec language). What else can be done?

[acabal]

@rdeltour That's sort of it, but to more precisely rephrase the issues this ticket was created for:

Today, RS's all have different default stylesheets and RS overrides.

Since RS developers rarely if ever disclose the default stylesheets implemented by the RS, or the CSS properties their systems don't support or override, it's near-impossible for ebook developers to create a single ebook file that they can be sure looks good/consistent across all major RS.

In other words, ebook development today is like web development in the early IE6 era.

This ticket suggests a path towards alleviating, but perhaps not permanently solving, that issue: defining a minimum default stylesheet in the epub spec, akin to the default suggested stylesheet defined in the various HTML specs.

I don't think there will ever be a way to force RS developers to all harmonize on a single stylesheet or set of CSS overrides. This is because, in part, RS's differentiate themselves on how they style ebooks and present that style to the reader. For example, iBooks wants the ebooks it presents to appear different and unique from the ebooks Google Play Books presents: font, line height ,etc.

What a minimum default stylesheet in the spec would accomplish would be a starting point for ebook developers to point to and say:

"Look, the ebook I produced complies with the epub minimum stylesheet. If an RS removes all styling except for the epub minimum, my ebook is guaranteed to look good. Now it's up to the RS to make sure its own unique styles it applies on top of the epub minimum stylesheet don't screw things up too badly. I wash my hands of the matter."

Today we can't even say that much, because there is no minimum defined. The minimum is whatever a specific RS has implemented at that specific version of the RS software, and it could change at any time with a software update. Since RS developers are not communicative, it becomes impossible for ebook developers to produce ebook files are both frozen in time (as all ebooks are) and that are guaranteed to be rendered as intended on today's and tomorrow's RS's. Today, the CSS sands shift underfoot, and you can't build a foundation on that.

If backwards compatibility is a concern for the minimum default stylesheet option, then it's a simple matter to say, "If this ebook says it's compliant with epub 3.1, then render it using the epub minimum default stylesheet as the base, and apply our super secret overrides on top of that. If it's < epub 3.1, then use our super secret default stylesheet that we've been using for a long time now."

I'm still not sure rendition:css-overrides would accomplish what we're trying to solve here. As I mentioned, ebook producers will always opt for it on, because from their perspective it would be the only way to ensure their ebook looks the same. If the greater web had an option for "don't use the browser's default styles", wouldn't almost every web developer always turn it on too? And if an option is always on, then why have the option at all?

[BluefireMicah]

This is a fabulous thread about a topic that has long been neglected in our industry. I can't claim to have answers, but I would like to share my perspective as an RS dev in the hopes of furthering the conversation. As an RS dev, my focus is on users. And with that focus over the last decade, I can say two things with absolute certainty: 1) Users want consistency across books. 2.) Users want complete control over their reading experience. Meaning, if I ("user") want an all caps font, narrow margins, left justified, Tan background and dark brown text at a relatively largish text size - that is what I want, period the end. And I don't want to have to set that each time I open a book. I want to set it once. Once I do, it should work the same on every single book. It it does not work on one of my books, then that book is Broken and I'm likely to complain, and maybe ask for my money back. In many cases, I as an RS dev can deliver on that expectation. But not always. Why not always? Because while I can over-ride "known" CSS selectors, I don't have a good way to over-ride unknown selectors. This is why when we offer "night mode" we simply use graphics API's to invert all colors. Using CSS over-rides simply is not consistently successful enough to do it with CSS. It is a horrible, horrible hack. But the best choice we have given the UX of the alternatives. I think having a setting along the lines of "use publisher settings" is a good thing to offer for a variety of reasons. I don't think users would use it that often, but some books will benefit greatly from it, and perhaps in those cases the content of the ebook should recommend such a setting, if present, would enhance the experience. I agree that more standardization, or at least transparency in "default" RS CSS would be a helpful (albeit more complex than it sounds given that RS's tend to try to optimize to the device) though given how common it is for users to over-ride RS defaults, I'm not sure how much mileage is gained. What to me, as an RS Dev, would be most useful is more standardization in markup, so when a user instructs me to present the text to them in all caps, in open dyslexic font, left justified, tiny margin, dark brown on tan, I can actually do that for them consistently.

[danielweck]

As promised, here is Readium's input to this discussion:

https://github.com/readium/readium-shared-js/wiki/ContentModifications

This is work-in-progress, feel free to file issues if you would like to suggest changes, etc.

[pettarin]

I pretty much [1] agree with Micah Bower's above comment ( #672 (comment) ), especially on the complexity and ineffectiveness of CSS overrides to achieve a "consistent UX", but I would push the reasoning even a step further.

I would argue that a first step towards better "eBook experiences" would be that reading systems should be required to implement the "throw publisher CSS away" function. (I would even add "... and enabled by default", but I know it will never happen.) [2]

Once authors/publishers/tool developers start realizing that outputting poor HTML markup is problematic, and fix their course, we could start tackling finer issues like an "agreed default CSS" more fruitfully. Until then, my feeling is that this might be an inspiring discussion, but I doubt it will also be useful in practice.

"There is no permanent place in the world for ugly hacks"

Footnotes

[1] actually, people using my app say the "ignore original CSS" is among their favorite features. However it covers a very specific type of EPUB3 files, and I have a tiny user base (<10k users), and with peculiar characteristics. So, this observation might not be applicable more broadly. More than one year ago I talked about it on my personal blog ("No user-provided CSS is a stupid CSS").

[2] en passant, a discussion about enforcing RS compliance to the EPUB specification would be in order, but since in abstract terms it applies to both the "ignore CSS" and the "default CSS" proposals, I think it is suited for another time/issue.

[Crash--]

I pretty like the idea of rendition:css-overrides (if implementation is a must) but we need to see this issue as a whole. This metadata should just declare the intention of the ebook producer and then let the user makes his choice.

For instance, we can imagine something like :

• ebook producer can add rendition:prevent-override : (yes/no) to their ebook. If yes, then ebook producer can add a metadata like rendition:should-be-displayed-like-that : (URI to an image / screenshot / ...) (see why below)
• if RS has a settings like always override (yes/no) (as @BluefireMicah said) so this setting is on top of hierarchy and override the ebook style. But RS MUST give the choice to the user if rendition:prevent-override is set to yes.

So when a user start reading the ebook, RS can add something like "You have a custom style defined, but the ebook producer recommends you to read the book without it. What do you want to do ?" with the image provided by rendition:should-be-displayed-like-thatto help the user to make his choice. In order to not display this "popup" (or whatever the form factor is) every time, RS can implement something like "Remember my choice for this ebook producer / editor / ...".

If something like that is implemented, us (by us I mean the ebook dev community) can develop JS/CSS frameworks to normalize style, to enhance readability and so on, between RS. At the end, we can produce tools to facilitate the life of ebook producer but also to enhance ebook quality (ie better markup).

It's not incompatible with the fact that RS vendor want the best for their users. They can still work on improving readability, a11y on their RS if they want to! At the end they will benefit from these JS/CSS frameworks because they will have cleaner markup so it'll be easier to manipulate.

I really don't want to see what we're currently seing in web dev : "This ebook is not compatible with your RS. Please install X to read it."

_I think we should stop talking for the users. There is so many use case, so many domains, so many different users... We have to agreed on the fact that a user wants the best experience possible. And for that, we need to agree on the fact that this best experience possible depends on the context/domains (edupub, multiple renditions, ...) of the book but also depends on the user. Sometimes RS will do a better job, sometime ebook producer will produce a very well designed ebook... _

[dauwhe]

Did we ever get a working group resolution on rendition: css-overrides (aka "leave me alone")? I thought we decided that this was not going to work for the reading systems, but haven't found any decision in the minutes.

[rdeltour]

I thought we decided that this was not going to work for the reading systems, but haven't found any decision in the minutes

FWIW I had the same understanding, but can't point you to any minutes...

[dauwhe]

Proposed resolution: do not add rendition: css-overrides. Do not provide a formal UA stylesheet, as we have already added a statement that reading systems should support the suggested default rendering of HTML5.

Small steps... there will be much to revisit in a future version of EPUB.

[dauwhe]

Proposed resolution in above comment accepted by WG on July 13.