Requests from authors

[JayPanoz]

We’re collecting feedback for Readium CSS and some requests may exceed the project’s scope. This issue is intended to list those requests.

I assume you’ll open specific issues for requests if needed so I may edit this first comment so that it’s easier to keep track. I’ll also include the source whenever possible so that you can require additional information.

• pop-up footnotes which are accessible and stylable (source)
• pagelist/page numbers support since it is critical for textbooks in education (source) → Streamer already retrieves pagelist/navdoc, it’s up to apps to display page numbers.
• Math/chemistry → if there is anything I can do in CSS, tell me (for some reason, iBooks has its own copy of a patched mathml.css and doesn’t rely on webkit’s)
• There has been an extended discussion about themes and how the publisher’s stylesheet could fit in there (worth mentioning imho although it’s a super complex issue)
• If margins set at the webview/iframe level, ensure that background can bleed (e.g. background-color: red on body). I’ve just discovered that some Reading Systems actually do it.
• Tables (an obvious one, this issue hasn’t really been solved yet and can’t be in pure CSS)
• Define margin in a chrome vs content way

[HadrienGardeur]

Thanks @JayPanoz for collecting those requests.

Have you documented how footnotes are implemented across EPUB3 readers? I agree that this is often requested by users, but we need to know more before we can figure out a solution in R2.

[JayPanoz]

I can already tell how they are displayed/managed but must document further details, for instance “are styles applied?” Some readers like iBooks may manage them as widgets so I won’t necessarily be able to have implementation details, it will be educated guesses.

As far as I can tell:

• Google Play Books display footnotes in a catfish (i.e. modal sliding from the bottom of the screen);
• Kobo and Kindle display the targeted link in a modal which is ± 80% of the screen’s size, with a link to go to the file#id;
• iBooks display the footnote in a pop-over.

Implementation details

iBooks

[edit = added some details, sorry.]

• They’re using an XHTML template in which they append the footnote when epub:type is found on a elements.
• It uses the ibooks namespace.
• My understanding is that it is treated as one of their iBooks widgets, which they’ve been using for their RMT format as well (EPUB 3 files generated by iBooks Author).
• Authors’ styling is ignored.
• If you don’t mark up as they tell, it will fail.
• Authors can choose whether the footnote should be displayed or not: <div epub:type="footnote"> will be displayed in the logical flow, <aside epub:type="footnote"> will be hidden.
• It’s been a pain to authors they’re using the noteref as the pop-over’s title (which is often a number).
• There are some positioning bugs e.g. the popover displayed on the left page while the noteref is on the right page.
• I’ve never been able to access pop-overs with Voice Over enabled but can’t guarantee they’re inaccessible since I’m not using Voice Over on a daily basis and there may be some trick I’m unaware of.

Kobo

• They do it for every link on iOS, not just footnotes.
• This behavior will change in an upcoming update.
• I can’t guarantee styling is ignored entirely but I can remember images’ layout/sizing is not taken into account.

Kindle

• Various issues I’ll have to investigate (text not correctly aligned for instance, depending on where the footnote is)
• Implem may not be consistent across all their apps and devices (different teams)
• for KF8 I must refer to their Kindle Cloud Reader, which is something like 9000+ lines of minimized JS.
• for KFX I must refer to their phantom.js script in Kindle Previewer 3, which is 4000+ lines of minimized JS for altering EPUB files’ markup + styles, and the Kindle Cloud Reader for rendering. Am now pretty familiar with those files but it could take days to investigate that.

[danielweck]

Regarding "popup footnotes" support in Readium: this functionality is currently implemented in a "feature branch" (i.e. not the mainstream Readium releases), see the Pull Request readium/readium-js-viewer#505

Demo (more links in the PR):
http://readium-footnotes.surge.sh/?epub=https%3A%2F%2Fcdn.rawgit.com%2FIDPF%2Fepub3-samples%2Fmaster%2F30%2Fgeorgia-cfi&goto=%7B%22idref%22%3A%22doc1%22%2C%22elementCfi%22%3A%22%2F4%2F2%5Bd10e42%5D%2F18%5Bd10e150%5D%2F6%5Bd10e163%5D%2C%2F3%3A732%2C%2F3%3A733%22%7D

Basically, the note content is extracted from the EPUB content document (HTML DOM), and presented "externally" via a modal dialog implemented with the same user interface controls as the rest of the application (that is to say: Chrome extension and cloud reader app, as native apps would have to implement this to suit their own UI framework). This way, the note content is accessible to screen readers without resorting to injecting "live region" overlays inside the actual content. PS: the note content's CSS is set to display:none when the "popup footnote" feature is activated, and when it isn't then the note hyperlinks simply point to the note content (regular link-based navigation).

[HadrienGardeur]

Purely from a code perspective, I see only two things that we'll need to support:

• open a content document at a specific id
• extract the HTML for a footnote's content (using id + epub:type)

Visually, I don't think it's up to us to decide how this will be handled.

[JayPanoz]

Given that out of the 4 apps I’ve discussed, there are 3 different visual implementations, I agree. Same for page numbers by the way.

[llemeurfr]

Well, we have to decide for Readium Desktop, the only end-user app we'll create in the short term.

[JayPanoz]

@llemeurfr I assume a lot of the requests I’ll collect will indeed be usable for Readium Desktop. Do you want me to maintain a dedicated Google Doc until there’s a RD repo?

[llemeurfr]

There's a Readium Desktop repo already (in the EDRLab Github for now), you could indeed publish interesting info on this repo, in specific UX issues. I'll give you access, people interested in RD UX decisions will be able to check them.

[JayPanoz]

Whoops, completely flew under my radar (didn't check the EDRLab github for some reason, sorry).

Already have a request for page numbers so yeah, it’ll be the best place for details.

[JayPanoz]

Just to let you know I updated first message with some requests I got during yesterday’s eprdctn hour (math, themes, margins & backgrounds, tables).

[JayPanoz]

Tables (an obvious one, this issue hasn’t really been solved yet and can’t be in pure CSS).

This is probably more of an UX issue but what I can tell, from an authoring point of view is that it’s really really painful to manage at the authors’ level in paginated environments.

Tables may be cramped or overflow-x, additionally span several pages… And Columns are not particularly good at fragmenting them.

What I tried for the OECD prototype which was presented at ePub Summit:

• overflow-x + overflow-y + sticky header so that the table stands on its own single page, but it feels unnatural to scroll + you get false positive gestures: scroll-x → page turn
• overflow-y hidden + scale so that at least the width fits. Tap on table → modal opens with the whole table’s content
• paginating columns if they don’t fit
• picking the columns you want displayed
• tables → interactive chart depending on media queries

What iBooks does

Table is displayed as usual but double-click opens it in a web view, without authors’ styles.

How the web deals with this

This CSS-tricks article discusses possible solutions for tables, which are also an issue on the web. We’re on the same boat.

What could be in the scope of R2

Like footnotes, extract the HTML for a table’s content so that implementers at least have the option to do as iBooks does.

[JayPanoz]

If margins set at the webview/iframe level, ensure that background can bleed (e.g. background-color: red on body). I’ve just discovered that some Reading Systems actually do it.

FWIW, I can provide authors with 2 specific CSS variables for this (if background is set then text color should probably as well).

We’ll have to deal with this for reading modes anyway i.e. make colors bleed so that the entire screen is the same color in night or sepia modes. And those 2 authors variables could be retrieved in JS at runtime (they’re a computed style).

[JayPanoz]

Math/chemistry → if there is anything I can do in CSS, tell me (for some reason, iBooks has its own copy of a patched mathml.css and doesn’t rely on webkit’s)

So I was mistaken about that, they’re actually using a plist and/or embedding an xml file in iBooks Author’s EPUB3 files.

It’s quite hard to tell what they’re doing with it since I don’t know MathML very well. So if anybody could clarify that…