Possible spec language for reading system CSS handling #693

Closed
dauwhe opened this Issue Apr 7, 2016 · 11 comments

Comments

Projects
None yet
7 participants
@dauwhe
Contributor

dauwhe commented Apr 7, 2016

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

This comment has been minimized.

Show comment
Hide comment
@iherman

iherman Apr 8, 2016

Member

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/IDPF/epub-revision/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.

Member

iherman commented Apr 8, 2016

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/IDPF/epub-revision/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

This comment has been minimized.

Show comment
Hide comment
@acabal

acabal Apr 13, 2016

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 commented Apr 13, 2016

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

This comment has been minimized.

Show comment
Hide comment
@acabal

acabal Apr 13, 2016

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

acabal commented Apr 13, 2016

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

@mattgarrish mattgarrish modified the milestone: EPUB 3.1 Apr 14, 2016

@JayPanoz

This comment has been minimized.

Show comment
Hide comment
@JayPanoz

JayPanoz Apr 15, 2016

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.

JayPanoz commented Apr 15, 2016

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

This comment has been minimized.

Show comment
Hide comment
@iherman

iherman Apr 15, 2016

Member

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.

Member

iherman commented Apr 15, 2016

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

This comment has been minimized.

Show comment
Hide comment
@bdugas

bdugas Apr 21, 2016

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.

bdugas commented Apr 21, 2016

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

This comment has been minimized.

Show comment
Hide comment
@JayPanoz

JayPanoz Apr 22, 2016

@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 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

This comment has been minimized.

Show comment
Hide comment
@bdugas

bdugas Apr 28, 2016

@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.

bdugas commented Apr 28, 2016

@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.

@mattgarrish mattgarrish added the Cat-CSS label May 3, 2016

@JayPanoz

This comment has been minimized.

Show comment
Hide comment
@JayPanoz

JayPanoz May 14, 2016

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.

capture d ecran 2016-05-13 a 20 00 23

capture d ecran 2016-05-13 a 20 00 40

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…

capture d ecran 2016-05-13 a 19 47 03

while it should be

capture d ecran 2016-05-13 a 20 28 04

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?

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.

capture d ecran 2016-05-13 a 20 00 23

capture d ecran 2016-05-13 a 20 00 40

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…

capture d ecran 2016-05-13 a 19 47 03

while it should be

capture d ecran 2016-05-13 a 20 28 04

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

This comment has been minimized.

Show comment
Hide comment
@bduga

bduga May 16, 2016

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.

bduga commented May 16, 2016

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

This comment has been minimized.

Show comment
Hide comment
@dauwhe

dauwhe Jun 11, 2016

Contributor

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

Contributor

dauwhe commented Jun 11, 2016

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

@dauwhe dauwhe closed this Jun 11, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment