Possible spec language for reading system CSS handling

[dauwhe]

During the Bordeaux F2F, we decided on some "baby steps" to begin to address the relationship between author stylesheets, reading system defaults, and "overrides." [See #672]. We understand this will not solve the many complex problems in this area, but will continue to work on these issues. In the meantime, here is some possible spec language for EPUB 3.1:

1. In addition to supporting CSS properties as defined above, an EPUB Reading System's user agent stylesheet SHOULD support the suggested default rendering as defined by the HTML5 specification.
2. EPUB Reading Systems SHOULD apply author stylesheets as written to EPUB Content Documents. If a reading system allows, users should be able to override author stylesheets as desired. EPUB Reading Systems should only override author stylesheets if strictly necessary.
3. If an EPUB Reading System must override an author stylesheet, it SHOULD do so using CSS.
4. EPUB Reading Systems SHOULD publicly document their user agent stylesheets and how they interact with author stylesheets.

Feedback on the language would be most welcome. I expect we need more details for 3.

[iherman]

What about something stronger

During the Bordeaux F2F, we decided on some "baby steps" to begin to address the relationship between author stylesheets, reading system defaults, and "overrides." [See #672 https://github.com//issues/672]. We understand this will not solve the many complex problems in this area, but will continue to work on these issues. In the meantime, here is some possible spec language for EPUB 3.1:

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

EPUB Reading Systems SHOULD apply author stylesheets as written to EPUB Content Documents. If a reading system allows, users should be able to override author stylesheets as desired. EPUB Reading Systems should only override author stylesheets if strictly necessary.

If an EPUB Reading System must override an author stylesheet, it SHOULD do so using CSS.

An EPUB RS SHOULD NOT override an authors stylesheet; in case it does, it SHOUL do so using CSS via, conceptually, a separate CSS file

(I trie to avoid using element level style elements…)

EPUB Reading Systems SHOULD publicly document their user agent stylesheets and how they interact with author stylesheets.

Feedback on the language would be most welcome. I expect we need more details for 3.

[acabal]

What jumps out to me is SHOULD in #1. If one of the goals is to provide a reliable CSS foundation for ebook developers to build their own styles over, something that "might" be there isn't a reliable foundation and so ultimately just isn't useful for ebook developers.

Plus, since AFAIK no popular RS currently implements the HTML5 defaults, why should they expend the effort to implement a "should"? (Though of course we must acknowledge that even a "must" can and very well might be ignored.)

[acabal]

Also want to add that the rest looks good and would be a big step forward for us poor ebook developers :)

[JayPanoz]

OK so, that’s not necessarily feedback on pure language but I'll try not to spill over too much.

1. [opinionated] “must” instead of “should”? To me, problem is RS don't necessarily cover anything in their default CSS and tend to focus on fiction books. I'm trying to be pragmatic and I know this “must” won't solve all the issues we’ve got in a blink of an eye. But the sooner we (try to) make sure RS get that there is more than p, h1 and *, the better—especially because of pwp, epub-web, etc. in the long term.
2. what is strictly necessary? Margins, height and width for page, html or body? Text’s color if it doesn’t meet WCAG’s level AA contrast ratio? Hacks to make eBooks output from one popular software play well in the RS because some of their styles are problematic? The max-height of img so that you don't get a blank page after? Those are overrides which already exist. Are they strictly necessary?
3. requires feedback from RS but as far as I know, they already try to do that and sometimes, they can’t (night mode hacks for instance).
4. no comment.

[iherman]

On 15 Apr 2016, at 04:31, Jiminy Panoz notifications@github.com wrote:

OK so, that’s not necessarily feedback on pure language but I'll try to spill over.

[opinionated] “must” instead of “should”? To me, problem is RS don't necessarily cover anything in their default CSS and tend to focus on fiction books. I'm trying to be pragmatic and I know this “must” won't solve all the issues we’ve got in a blink of an eye. But the sooner we (try to) make sure RS get that there is more than p, h1 and *, the better—especially because of pwp, epub-web, etc. in the long term.
what is strictly necessary? Margins, height and width for page, html or body? Text’s color if it doesn’t meet WCAG’s level AA contrast ratio? Hacks to make eBooks output from one popular software play well in the RS because some of their styles are problematic? The max-height of img so that you don't get a blank page after? Those are overrides which already exist. Are they strictly necessary?
requires feedback from RS but as far as I know, they already try to do that and sometimes, they can’t (night mode hacks for instance).
There are examples for RS-s that modify the margin of the body element but, as it seems, do that programmatically, ie, this cannot be controlled or overwritten by any CSS tricks. It is this type of setup that we discussed at the F2F.
no comment.

[bdugas]

At Kobo we'd like to align ourselves with efforts to improve CSS support. What would help us get started is a sample ePub that makes use of all the CSS content creators would like to see supported (or not overwritten). One of the difficulties with improving CSS support is that there are so many possible attributes. Having content creation experts come up with a list of what they want to see supported everywhere and then making a sample that uses them would allow us to run testing across all our platforms then create a support grid.
We could then assess the gaps, estimate the work involved and schedule the work for our client teams.
In the past when we find instances of CSS being overwritten we log bugs and provide the examples but a more comprehensive approach would yield much greater results than looking at overrides one by one as they are reported or discovered.

[JayPanoz]

@bdugas Thanks a lot for your input. Please feel free to DM me on twitter if needed.

Firstly, what I can personally do is to provide a sample based on the Blitz framework we've been developing. But I guess it won't be very meaningful since we've been basically trying to get around anything which might be an issue. At least we're covering a lot of stuff (tags, CSS, etc.) so that's already something.

Then, I'll try to review all the files I've made so far and create a sample with common and edge cases which have proven to be problematic. I'll need some time though since that is quite a lot of files.

Finally, since it is quite impossible for one single individual to provide some comprehensive sample, I guess it would be useful if someone started some repo to compile problematic snippets of markup and CSS then build an epub file out of them? Obviously, this would be a great effort and in order to motivate people to get involved, I'm not sure one single individual is up to the task….

[bdugas]

@JayPanoz I'd be curious to see the file you can export now even if it's not the ultimate CSS test ePub we're seeking. We'd certainly be interested in working as a group to identify the CSS elements to be tested.
It might be more manageable if we began with just the CSS elements one would expect to be supported on all viable eBook platforms then add on edge cases later on.

[JayPanoz]

OK so just to illustrate how the CSS issue could turn into a huge problem really fast, I've tested rem values, which is something quite ordinary nowadays, and it's completely broken in eBooks because of default CSS + overrides.

For instance, Google Play Books doesn't know how to manage them, the user can't increase or decrease font-size (as if you've got pixels in IE 6) and, even worse, the cloud reader reflows margins instead of font-size, which means the smaller the font-size, the larger the margins.

Others like ADE 4.5 have, by default,

html {
  font-size: 100%;
}

which means you must declare:

html {
  font-size: 62.5% !important; /* 10px (in theory) */
}
element {
  font-size: 1.6rem; /* 16px (in theory) */
}

Or else…

while it should be

Of course, if they “!important” their own declaration, then you’re toast.

So I get why RS want this to be "should" and why they are doing this in the first place (because sometimes authors set body copy to 10px) but on the other hand, if that breaks CSS units (units!), we're heading for serious issues.

Indeed, using rem is not an edge case and given its design—em computed from root—, it just takes one override (html font-size) to mess it up. And that’s something RS may consider “strictly necessary” if they don’t take into account the fact that rem is used since, well, why would you override some styles depending on conditions (“if rem don't override html else font-size = 100%”) when parsing the author’s CSS?

[bduga]

But this doesn't sound like a problem with rem units, it sounds like a problem with font size changes. We use at least three different approaches to zoom fonts, based on the platform, and they all have their weird quirks. And that is specifically a case where doing something (changing font size) with just CSS is essentially impossible. There are some mobile hacks to do it (text-size-adjust), but that isn't available everywhere, so we are forced into these games of programmatically changing the font size. It also means (in some case) making sure there is at least one font size on the body, though I don't think we ever do that with !important and do it before any publisher CSS, so it should only take effect if no font size was specified by the publisher. I expect this specific case is just a bug, perhaps in only some of the readers (it's jot clear which ones you tested, other than the webreader). Personally, I would much rather not play these games just to enable font size changes, but I am also not sure what the alternative is.

[dauwhe]

Closing as we how have spec language that's had quite a bit of review.