Readium CSS snapshots

[JayPanoz]

This issue is meant for tracking progress.

The roadmap can be found in the Wiki.

August 21, 2017

We’ll publish the Readium CSS prototype on the master branch this week, with basic documentation so that implementers can take a look, review, test and report issues if needed.

A lot of testing has happened this last week, with few minor issues to report, and quite good results in any browser tested (Chrome, Safari, Firefox, Edge).

Proto features

• Support for Latin (LTR, horizontal-writing)
• Basic paged + scroll rendering
• Basic page margins
• Default stylesheets (base, unstyled EPUBs, highlights)
• Basic user settings:
  • night and sepia modes;
  • font family;
  • font size.

Font size being the more complex issue to manage, check issue #8 as it is UX-related.

Ahead of schedule

The good news is that we’re way ahead of schedule for the following:

• Advanced user settings:
  • line-height;
  • hyphenation;
  • text align;
  • paragraphs’ margin;
  • text indent.
• Customizable themes
• A11y-related user settings:
  • letter and word spacing.

Extras

We can reliably offer extra user settings for images in night mode:

• darken;
• invert.

Known issues

• We might need to (partly) implement the outline algo (for font-size) in the normalize stylesheet. Problem is EPUB3 files make heavy use of section and the type scale issues are generally related to aside. If authors use div we can’t do anything.
• max-width in scroll and one-column view (user setting) doesn’t apply because of the media query in pagination at the moment. This will be fix in alpha (advanced paged + scroll rendering).
• User’s line-height may not apply in a few publications.
• Sometimes headings’ margin-left are aligned on text-indent, should we override that if the user sets text-indent: 0?
• Some or all pictures may not be rendered in sepia mode because of mix-blend-mode. It happens in Blink/Webkit in particular, the former being the worst. This has consequently been disabled in the proto.
• Should we set a base line-height? Some authors don’t and the default is something like 1.2?

[JayPanoz]

November 22, 2017

We can’t release the alpha version at the moment because we don’t manage vertical writing yet. This will be implemented ASAP, especially as we’ll get some help and feedback from the Japanese APL. Please be assured this is our top priority.

An important note: we moved our Android target to 5.0.

Alpha Version progress

What we’ve got so far:

• Advanced paged + scroll rendering
• Advanced page margins
• Advanced user settings:
  • page margins;
  • columns;
  • line-height;
  • hyphenation;
  • text align;
  • paragraphs’ margin;
  • text indent.
• A11y-related user settings:
  • typefaces for dyslexia;
  • letter and word spacing.

Docs

• The core documentation for defaults (pagination, margins, default fonts, etc.) is done.
• The baseline for a11y-related user settings has been set.
• We have created a doc for EPUB compatibility so that implementers know what they might want to support for optimal compatibility with the de facto ecosystem.
• Insights from EPUB authors and users have been added to the doc.

Moreover:

• We have started researching and documenting vertical writing.
• We’ll define the minimal set of settings (and their values) implementers may want to provide to be WCAG 2.1-compliant.
• We’ll update variables and the API since we can now safely recommend ways to manage user settings.
• Themes are on their way and will be quickly documented.

[danielweck]

Congratulations, and thank you:) Just to be clear: support for RTL page-progression-direction in horizontal writing mode (e.g. Arabic, Hebrew) has not been formally tested yet, right? I managed to get it working in the Electron (Chromium) / NodeJS / TypeScript app but I had to override the "text align" parameter (left, center, justify, right) to ensure the correct application of @dir=rtl HTML attribute (or CSS direction property) for right-aligned text. Of course the JavaScript -side handling of CSS column offsets (and more importantly: the scroll offset -based overflow or coordinate-based viewport wrapper that pans pages across the horizontal axis) uses mirror calculations for the RTL case ; as expected ; and that's something we might want to document in ReadiumCSS in order to showcase different methods to fully enable the pagination of reflowable documents. I will produce some documentation for the Electron navigator as soon as it is stable (I have not yet tested edge cases including nested CSS boxes with mixes of static/relative/absolute positioning, which typically affect scroll offset calculations).

[JayPanoz]

support for RTL page-progression-direction in horizontal writing mode (e.g. Arabic, Hebrew) has not been formally tested yet, right?

I can confirm it has not been tested yet, since testing and feedback has been tightly coupled to the iOS test app for most of proto/alpha, and it didn't have RTL support at that point. The webpub-viewer I’ve been using was then diverging too much from this practical implementation so it was a little bit difficult to manage it this way.

For the text-align parameter, you might want to try start if you want something cleaner (I added that to the docs yesterday, but I can’t recommend it formally because of Trident/EdgeHTML, which doesn't support it).

To sum things up, the start value will be left in LTR and right in RTL. And, consequently, end will be right in LTR and left in RTL.

It is part of the logical properties and values which will make it a lot easier to manage RTL and writing-modes in the middle term – webkit/blink/gecko already use those props and values in their default stylesheets for example, but they’re non-standard.

the scroll offset -based overflow or coordinate-based viewport wrapper that pans pages across the horizontal axis) uses mirror calculations for the RTL case ; as expected ; and that's something we might want to document in ReadiumCSS in order to showcase different methods to fully enable the pagination of reflowable documents.

Well noted. There’s indeed still a lot to document on that front (relationships between Readium CSS and the more global Reading System in which it will be used) but that was planned.

[JayPanoz]

So yeah sorry, I had to create an “alpha” branch to deal with the release of this version, given the architectural changes, and all the doc-breaking changes – so it absolutely requires docs to be updated before the release.

[JayPanoz]

And to clarify, there is no breaking change at the CSS level, the stylesheets you’ve been using will be almost the same as the stylesheets the alpha will ship (with a few minor improvements in the form of safeguards).

[JayPanoz]

So the alpha version is almost ready.

In addition to the roadmap list items, it ships with:

• a package.json so that you can install PostCSS dev dependencies, build dist stylesheets, etc.;
• a ReadiumCSS-config.css file so that you can customize media queries, flags e.g. advanced settings, night mode, etc. (Dan, that should allow you to declare a min-width small enough that it applies to the desktop app without removing the media query entirely);
• a few minor improvements which shouldn’t make a huge difference compared to the CSS you’ve been using so far;
• updated docs (md, epub and exploded folder from epub);
• Issues and PR templates;
• a subpar build process (to say the least) which works but isn’t very elegant.

Warning: the iOS-implem has been deprecated (and removed) as we didn’t need it anymore – dist stylesheets are now doing the job the iOS-implem has been doing so far.

Alpha will be version 0.0.8.

Also, as regards i18n, you’ll find ReadiumCSS-before.css, ReadiumCSS-default.css, and ReadiumCSS-after.css in subfolders.

Question to implementers: does that help you? Or should we suffix those files with -rtl, -cjk-horizontal, and -cjk-vertical?

Personally, I don’t necessarily like having files by the same names but it might ease injection a little bit – the folder’s path being the only difference?

Any question, feel free to ask.

[danielweck]

Thanks, I will start looking inside https://github.com/readium/readium-css/tree/alpha/css/dist to figure-out how to update the R2 Electron navigator.

[danielweck]

Right now I'm using the ReadiumCSS files as-is (no removal of Media Queries, etc.). The rendered reflowable documents look okay, I will figure-out how to switch vertical, RTL, etc. later (especially as this will probably require changes in the Electron/JS pagination code).

[JayPanoz]

So yeah I can confirm the most reasonable path seems to be:

1. handling Indic and other non-Latin-and-non-CJK scripts (they’re built-in but can serve for lang logic in OPF);
2. handling CJK horizontal, mainly Chinese and Korean (page-progression-direction check in OPF + loading specific stylesheets);
3. handling RTL scripts (navigator → RTL progression);
4. handling CJK vertical (require lots of changes but it’s the same logic as R1).

And of course please feel free if something is unclear or poorly-worded in docs. :)

[JayPanoz]

Alpha has just been merged into develop.

It will be merged into master in the upcoming weeks.

[JayPanoz]

Alpha has been merged into master.

We’ll merge develop updates much regularly from now on.

[JayPanoz]

It’s highly likely we won’t need this issue any longer since we’ll make smaller merges from now on (and not the huge ones we did for the proto and alpha version) so I’ll close it in a few days if nobody disagrees.