Checklist for Readium CSS integration

[mickael-menu]

Here are a few points regarding the Readium CSS integration which should be double-checked or fixed in the mobile toolkits.

• ReadiumCSS-default.css needs to be injected if the book doesn't have any style.
• When using iframes, we need to use allowtransparency to make sure that background color settings work properly.
• Check rendering on big screens.

  • Since we still limit line-length in the spread model, you might want to limit the web view/iframe size so that you don’t end up with wide gaps on large screens (or add padding to :root, and take it into account when scrolling).

• Instead of fixed fonts (Helvetica Neue, Athelas, etc.), we should expose by default the font stacks from Readium CSS, using the provided CSS variables.
• Should we use Readium CSS highlight colors? There's an on-going discussion. Nope.
• We should improve support of internationalization.

  • the app should at least offer the publisher’s font and the default (var(--RS__baseFontFamily)) for the language – which should work automatically if the correct language is set for each document;

  • Some user settings need to be disabled depending on the publication language, both in the UX and in ReadiumCSS.
  • The primary language needs to be determined from the page progression as well.

    • There's a well known bug on InDesign (addition of an extra ar-SA dc:language) which causes problems in the reading progression of apps like iBooks (they rely on the last dc:language because they can't rely on the spine attribute in EPUB2)

  • The primary language needs to be injected in the DOM with xml:lang.
    • Determining the primary language doesn't depend only on the order of <dc:language>, the page-progression-direction must be taken into account.
  • Check the list of languages for CJK support.
  • We need to inject the EBPAJ patch for Japanese.
  • We must not inject the dir= attribute with CJK languages
  • Some parts of the UX must follow the publication's direction, including search and highlights.
• Some books won't change their font size unless publisher's styles are disabled.

[mickael-menu]

When choosing a specific font, as a rule of thumb we should fall back on one of the known font stacks, e.g.

--USER__fontFamily: "SF Mono" var(--RS__monospaceTf);

[JayPanoz]

Should we manipulate the typeScale property when changing the font size?

We discussed about this in private so for the benefit of everyone, here is a recap on the concept of type scale, its purpose and use cases.

Definition

Type scale, also known as modular scale, is a sequence of numbers that relate to one another in a meaningful way. As typographer Robert Bringhurst put it:

A modular scale, like a musical scale, is a prearranged set of harmonious proportions.

So in ReadiumCSS we have this typeScale ratio in the font-size normalise module, and then you’ll find a calc() function using it to compute a font-size e.g.

font-size: calc(1rem * var(--USER__typeScale))

An interactive web app such as this one will illustrate what happens when you change the type scale.

For more details, you can also check this 2011 article.

Purpose

It was initially implemented in ReadiumCSS as a way to get relatively foolproof typography in many circumstances – it’s also implemented in the default stylesheet for instance.

And we also had this issue of the font-size setting which doesn’t have anything standard in CSS (or a JS API) so we parsed lots of stylesheets to find a reasonable default ratio (1.2) working for most authors’ stylesheets.

It became clear it was a good idea to expose this variable to reading system developers so that they could change this ratio as they see fit.

Use cases

• if you want to compute the ratio used by the author (by checking headings and paragraphs and doing some Math) and adjust the type scale of the font-size normalisation accordingly;
• anything responsive typography:
  • you might want to use different type scales for different devices/screen sizes so that you don’t have these awkward large headings on a smartphone;
  • if the user sets a large font-size, you might want to decrease the type scale so that headings are not super large.
• it could probably also be exposed as a setting for custom themes given the dramatic effect it has on typography.

Admittedly all of these use cases are kinda going the extra mile, but it could also be a “design differentiator” if you’re willing to take great care of typography in your app – we’ve done our best to provide a sound and better-than-average basis in ReadiumCSS so handling this typeScale could probably be considered a bonus. It’s not necessary but may show a clear commitment to the Reading Experience if you wish to differentiate on that.

[Edit] I guess we could add this comment AS-IS in the Readium CSS docs if it can be helpful (after all we already have a glossary for i18n).

[JayPanoz]

Some parts of the UX must follow the publication's direction, including search and highlights.

Although the vast majority of the UX can be ltr, I’m noticing that vertical writing + the toc panel is an open question BTW.

In Requirements for Japanese Text Layout:

For example, the table of contents may contain small modifications. Furthermore, there are many examples of indexes with a different page format than the basic page format, and vertically set books often have indexes in horizontal writing mode and sometimes multiple columns.

They just mention indexes for ltr layout in vertical-rtl so I’m assuming Apple Books does the right thing by having the toc panel the same as the reading progression of the publication.

[JayPanoz]

On a related note, would you like this warning about Mongolian directly in the docs?

It only exists in this ReadMe at the moment.

[JayPanoz]

Should we use Readium CSS highlight colors? There's an on-going discussion.

So yeah there’s this issue in Readium CSS for that.

If we deem it’s in ReadiumCSS’ scope (although it hasn’t necessarily been clarified it would be trivial to handle it in a efficient and compatible way with the Highlights API we discussed months ago), then it would have to go through a major “code change.”

There’s also this issue in r2-navigator-js which should be relevant to this discussion.

[mickael-menu]

@JayPanoz

We discussed about this in private so for the benefit of everyone, here is a recap on the concept of type scale, its purpose and use cases.

Thanks for the explanation, the use cases are particularly useful 👍

So for mobile test apps, I think it's fine to ignore this property for now to keep it simple.

I actually think that we need a native wrapper/module around Readium CSS for mobile toolkits. Something similar to what we have with UserSettings but simpler to use, type-safe and more complete. This module could implement all the recommendations from Readium CSS documentation and handle:

• Injection of:
  • Readium CSS stylesheets (including default when there's not author styles)
  • dir=, lang=
  • USER/RS variables in <html>
• Generation of the JavaScript used to update the USER/RS variables
• A complete type-safe settings API which would expose all the Readium CSS variables (so including typeScale). The test app would only use a subset of them.

Except for the effective reading progression and the primary language, which should probably be in the shared models + EPUB parsers and not particularly tied to Readium CSS. (I'm not sure about dir= and lang=, is it specific to Readium CSS?)

This wouldn't be the upcoming "Rendering/User Settings" API, which should be format-agnostic. But this would be a lower-level API that the User Settings API would use when rendering EPUBs.

On a related note, would you like this warning about Mongolian directly in the docs?

I think it would make sense, I actually didn't read the README in dist/, assuming it was a condensed version of the documentation.

If we deem it’s in ReadiumCSS’ scope (although it hasn’t necessarily been clarified it would be trivial to handle it in a efficient and compatible way with the Highlights API we discussed months ago), then it would have to go through a major “code change.”

After thinking more about this, I believe that highlights should not be in the scope of Readium CSS. If we have some default highlight colors in Readium, they should maybe be documented in architecture, and declared in the test apps. There's just too many different ways to implement highlighting, and also we couldn't reuse the colors declared in Readium CSS for other formats such as PDF.

[JayPanoz]

Some quick answers for the stuff that doesn’t need much thought.

(I'm not sure about dir= and lang=, is it specific to Readium CSS?)

So dir is tied to CSS multicol for pagination/fragmentation (which is applied on :root a.k.a. html element). If it weren’t present, the columns progression would go the opposite way. We didn’t have enough samples in RTL to check whether authors add it themselves or not so we resolved to this rule.

Then lang is not particularly tied to ReadiumCSS in the sense the rendering engine will use it to hyphenate properly for instance, or for some very specific CSS styles (including browsers’ UA styles).

But yeah in the end ReadiumCSS is relying on this as a web browsers actually do (default font-stacks, word breaking rules, etc.).

I think it would make sense, I actually didn't read the README in dist/, assuming it was a condensed version of the documentation.

Just noticed this morning, sorry. I can see I should also mention the fact only Windows has a typeface for traditional Mongolian – Android you have to install a downloadable font if I’m not mistaken, iOS and web you’re pretty much out of luck. I tried contacting the type designer of a popular Mongolian font in 2018 so that Readium projects could use it – through a contact form in Chinese – but never got an answer, unfortunately.

I believe that highlights should not be in the scope of Readium CSS.

Yeah me neither given how limiting a ReadiumCSS module would be. And we shouldn’t forget other formats – I’m assuming web publications could have TTS with sync/overlaid highlights, notes, etc. as differentiating features from web browsers.

So we should probably open a vote in the ReadiumCSS issue tracker on dropping this highlights module.

[mickael-menu]

An issue related to Readium CSS, but to be fixed on the native side: Some books won't change their font size unless publisher's styles are disabled (note to self: 9782081418011.epub).

This occurs when a book uses absolute font units, which Readium CSS can only handle when the fsNormalize module is enabled through --USER__advancedSettings: readium-advanced-on.

Here are two potential solutions which require to provide a native wrapper for Readium CSS, to handle this seamlessly for reading apps:

• Android's WebView has setTextZoom().
• text-size-adjust could be used instead of Readium CSS, when available.
• We could check if a resource uses absolute font units and disable publisher's styles on a case-by-case basis. This would most likely require parsing the CSS and check for the presence of font-size: pt|px|keywords, as well as the shorthand font.