Progression/direction between resources

[HadrienGardeur]

The current infoset does not contain any information about the reading progression (progression between resources) for a given publication.

In EPUB, this was handled using an attribute on the spine (the EPUB equivalent for the default reading order), and it's handled through direction in the metadata section of the RWPM.

This is a very important information for User Agents since it's absolutely necessary for providing key affordances.

For instance, in the case of Readium-2, we use three webviews side by side on iOS and Android:

_____________________________________
|           |           |           |
| Webview 1 | Webview 2 | Webview 3 |
|           |           |           |

If the reading progression is set to ltr, then:

• 1 contains the previous resource (or none if we're displaying the first one in the reading order)
• 2 contains the current resource
• 3 contains the next resource (or none if we're displaying the last one in the reading order)

If the reading progression is set to rtl, then:

• 1 contains the next resource (or none if we're displaying the last one in the reading order)
• 2 contains the current resource
• 3 contains the previous resource (or none if we're displaying the first one in the reading order)

In addition to setting up these Webviews, this reading progression is also used for:

• mapping tap zones that will allow us to get to the next page (if a resource is paginated) along with the next resource
• specific touch gestures, such as swipe/drag
• keyboard events, such as mapping arrow keys to move forward/backward in the publication

[HadrienGardeur]

@laudrain this is the issue that I mentioned during our call today. Could you post additional use cases and example as well?

[dauwhe]

How would this infoset metadata relate to the page progression direction of the primary HTML resources of the publication? What if the infoset value contradicts the value in some or all of the primary resources?

[HadrienGardeur]

Page progression is about the reading direction of a single resource.

This is about the progression between resources.

When each resource of a publication is scrolled vertically, the reading direction can't contradict this value.

Paged media is different though.

Setting ltr on the publication when all resources use rtl would not really "contradict" anything, but you might end up with a weird user experience where you get to the previous resource instead of the next one if the UA allows to swipe/tap inside paginated resources as well as between resources.

That said, this inconsistency goes beyond that. For example, what happens if the first chapter uses ltr and the second chapter uses rtl as its page progression ?

[iherman]

@HadrienGardeur just for my understanding: why isn't the default reading order enough? After all, that array would give me what the "next" resources is by default...

[HadrienGardeur]

@iherman the default reading order is enough to know what the next and previous resource in the reading order. But it does not contain any information about the direction of this progression.

Multiple affordances need this info as well:

• taps (need to define tap zones)
• swipes
• keyboard events

[dauwhe]

Can you outline some common scenarios where both reading order and page progression as defined in HTML/CSS is not enough information? Most existing reading systems use the same gesture/swipe/tap/keyboard event to move through both pages and to switch from spine item to spine item. And we also define a publication as a single unit. Do you envision the right arrow key, for example, moving RTL through pages but LTR through chapters?

[HadrienGardeur]

It's not enough in EVERY scenario. That's not a super rare special case, this is ALWAYS needed by the reading system.

[HadrienGardeur]

I'll ping other people involved in RS development as well to chime in @danielweck @fchasen

[HadrienGardeur]

Most reading systems implement swipe/tap/keyboard by either:

• injecting JS in each resource
• or by hijacking specific events at an OS level

Neither solution is ideal, but that's all we have.

What you're suggesting @dauwhe (using only what's present in HTML/CSS) is problematic on many levels:

• first of all, page progression might not be present at all
• sniffing individual resources is bad, having this information potentially hidden in CSS is even worse, it will be extremely complex to pre-process this information
• if we need to render the current document first before we can understand what the direction is, the UX will be extremely bad (long delay before we can inject the JS that handles interactions, inability to prerender resources in the meantime)
• this can also affect how we inject CSS as well (necessary in the case of EPUB 4, @JayPanoz can provide examples how this affects Readium CSS for example)
• finally, this could lead to an inconsistent experience as well if the first resource is rtl and the second ltr for example, we need to have a consistent progression throughout the publication

[JayPanoz]

So yes, if existing Reading Systems are any clue, this is quite a compat/interop nightmare at the moment, as there are awful issues and edge cases to deal with, and it hurts support for some languages:

• direction and writing-mode propagate, which means the value set for body will override the one set for html:
  • unlike any other CSS property, they are the two only CSS properties which propagate i.e. the parent element will acquire the value in this case, there is nothing you can do about it;
  • the dir attribute has little compatibility, with browsers not agreeing if if should propagate or not.
• the performance of vertical-* can be abysmal for some contents, with apps/browsers taking 10+ seconds to first layout & paint:
  • settings that take like 100ms to apply in latin languages can take 5 seconds in vertical-rl for instance, with a super visible re-layout (as if an image was resized);
  • on some occasions, I saw publications fail to render in some Reading Systems because something went wrong at runtime.
• when the page-progression-direction is missing, then some Reading Apps fall back on the language of the publication, not CSS/HTML:
  • either they limit the language to one item to make sure they can reasonably apply a direction;
  • and/or they put the burden on authors, who must declare the script (Hans or Hant for zh);
  • they may even have specific metadata so that authors can opt-out of the automatic direction they apply to scroll.
• there are script-specific typography rules, you can’t necessarily re-use the same user settings or styles, CSS logical Properties and Values are not yet available everywhere, and, consequently, you need to load different resources based on the language, script, direction, writing-mode, etc., and adjust the UI consequently;
• there are the mixed-directions and mixed-writing-modes edge cases of course, which very few Reading Apps solved (it took extending the multicol spec for Apple to solve it for instance, by having something to reverse the progression of columns, but that’s up to paged media/CSS overflow, etc.):
  • this is not an uncommon edge case as parts of a Japanese publication bound on the right (vertical-rl) can be written horizontally e.g. indexes;
  • bilingual publications?
• we had to resolve to a chain of educated guesses for i18n since all those issues make handling much more complex – and it felt like a burden to design this and recommend it as it can have a nasty impact on interoperability but we don’t have any guidance so there wasn’t any other solution than checking how others do it, and implement accordingly.

[TzviyaSiegman]

Perhaps this should be classified as an affordance? We know that in the world of EPUB it is nice to have, but do we need the same thing online?

[HadrienGardeur]

This is not an affordance. This is an infoset item that is used by a number of affordances (following the reading order and user settings). IMO this not "nice to have" but a must have.

[laudrain]

Sorry to be conservative, but from a publisher perspective, the use cases are limited to progression between all resources as ltr or rtl. I don't know any book with mixed page progression directions...
I understand that it is a must have in the infoset as it must be known by the reading system/navigator as soon as possible.

[danielweck]

1. yes, not having access to "direction" information for the publication spine (aka "page progression direction" in EPUB) directly as top-level metadata, means that as a reading system implementor: I have to fetch + load + parse documents in order to infer this information. Not good. Plus, individual documents can have a different direction (see below).
2. yes, there is the edge-case "publication has different overall 'progression direction' than individual documents". I'm not sure how wide-spread this currently is, or how common it may be in the future (e.g. mixed arabic french books) ... but purely from a technical perspective, the problem exists (of course there are UX issues too, that publication authors should work out).

[GarthConboy]

Agree on Daniel's #1.

Would tend to not expend cycles on #2, which should very much be an edge case.

[JayPanoz]

@danielweck

I'm not sure how wide-spread this currently is, or how common it may be in the future.

Strictly, we already have to deal with this for Japanese publications, in which writing-modes are already mixed (so mixed directions as well since vertical-rl is RTL and horizontal-tb is LTR).

Here is a capture from the sample provided with the EBPAJ template, where right page is vertical-rl and left page is horizontal-tb.

In paged views, the horizontal-tb document should go RTL as well, but we’ve got nothing to reverse the direction and it will automatically progress LTR.

In scrolled view, one strategy to deal with this is… paginating the horizontal-tb document so that it can scroll in the same direction as vertical-writing – I’m not kidding.

[iherman]

@JayPanoz, thanks. However, I am not sure I fully understand.

Are these two sections within the same HTML file, or are these two separate HTML files within the book? Because we would be concerned by the latter case only; the former is a matter of having the CSS and HTML specifications right. What we are concerned about is the overall direction among the resources of the book (and I agree that we do have to do something about this).

Or is it so that there are books whereby, say, the first three resources are to be understood as left to right and, then the second block of resources are to be understood as right to left?

[JayPanoz]

@iherman those are two separate HTML files.

• the global page-progression-direction is rtl
• file1.html is using vertical-rl
• file2.html is using horizontal-tb

This is something we can’t currently manage in paged views – cough columns cough – as we can’t reverse the progression for file2.html.

[iherman]

Ouch:-)

But I am not really sure what are the publication level metadata that could work. Is there an extra information that would radically change the implementation difficulties?

[murata2makoto]

Some Japanese printed book has both the right-to-left page progression direction and the left-to-right page progression progression. One half of such a book is a sequence of horizontally-written pages (from left-to-right page direction) and another sequence of vertically-written pages (from right left-to-right page direction).

But such books are very rare. When EPUB 3 was being developed, the EGLS subgroup discussed such books. We concluded that (1) providing a sensible user interface is not easy and that (2) we can always
separate such a book into two books. As a result, EPUB3 allows a single page progression direction per EPUB publication.

Books having a single page progression may have both horizontal writing and vertical writing. One of the two is primary, while the other is only for boxed articles or special pages. The example @JayPanoz mentioned contains a special page (at the very end), which has horizontal writing.

[iherman]

Thank you @murata2makoto. What I conclude (from the thread) to myself that there is indeed a need for an overall resource progression direction as part of the information set, but that only one of those is really necessary.

[dauwhe]

Can we at least state that this metadata must have no effect on the rendering of the individual primary resources? I want to avoid situations where we try to infer things (like dir) about content documents from publication metadata.

[TzviyaSiegman]

+1 to @dauwhe. Once we are listing real-world scenarios, what about intra-linear translations?

This website https://www.sefaria.org/Genesis.1?lang=bi is a good example of RTL and LTR interlaced throughout.

[JayPanoz]

intra-linear translations.

That shouldn’t necessarily be an issue. I won’t say I’m 100% sure it won’t be as if there is one thing I learnt during our i18n process, it’s that edge cases can be found all over the place and are still being discussed in the i18n repo. But I’m confident it’s unlikely or so edge-casey that it can be solved later.

What has proved to be an issue, is when the direction of a document/HTML page (i.e. html, root element, so it’s the whole document) differs from the publication’s direction. And you end up with LTR in RTL.

In the scroll case, it’s mostly fine i.e. you scroll vertically in both the Arabic Script and Latin so the direction of text doesn’t make any practical difference. One thing to note though, when mixing writing modes, is that you may end up with the following:

-----------  ----------------------
|         |  |                    |
|         |  |                    |
|         |  |         ←          |
|    ↓    |  |                    |
|         |  |                    |
|         |  ----------------------
|         |  
|         |  
|         |
|         |  
-----------  

← ← ← direction of the publication

1. The global progression direction is RTL
2. The first document is vertical-rl (direction is RTL)
3. The second document is horizontal-tb so its direction is LTR,

The scroll axis switches from horizontal to vertical.

So, say in iBooks, horizontal-tb documents will actually be paginated to keep the scroll axis consistent.

That’s obviously an implementation choice but I guess it’s probably noteworthy, UX-wise.

In the paged case, as long as you can’t reverse the direction of a document using CSS for instance, it is a tough issue to deal with.

[edit] Added Gif and made explanation clearer (sorry if it wasn’t)

[JayPanoz]

But, well, technical details aside, yes, the conclusion is:

there is indeed a need for an overall resource progression direction as part of the information set, but that only one of those is really necessary.

What’s most noteworthy, is that we got practical implementations of those cases (Apple extending the CSS multicol spec to handle this both in paged and scroll, and I can remember other apps are addressing it as well).

Then well, you also have authors trying to go from one writing-mode to the other with a switch. BTW, the author of this article can probably give a lot of details in this regard.

[JayPanoz]

Can we at least state that this metadata must have no effect on the rendering of the individual primary resources? I want to avoid situations where we try to infer things (like dir) about content documents from publication metadata.

Sorry, missed that. Definitely agree as this proved to be an issue in the real world.

And, from the implementation p.o.v., I much prefer not trying to deal with it at all than triggering issues as a result of trying to solve others (in the long term, “filling the gaps” is untenable as it will create expectations others must implement as well).

[iherman]

(comment from @dauwhe on the corresponding PR #142)

there are only two values for page progression direction. Within HTML resources, CSS does allow for overflow in both x and y axes. If a publication resource scrolls "down," it might be a better reading experience for the next resource to appear below. Do we need a "top to bottom" direction?

@JayPanoz ? @HadrienGardeur ?

[llemeurfr]

@dauwhe that would make no sense IMO to duplicate the notions. But this issue of vertical reading should be addressed.

For the sake of clarity, we could consider that the reading order does not have a "left" or "right" document, but a "first" and "last" document instead. Note that the notions of "next" and "previous" fit better with first/last than left/right.

Therefore "first to last" (ftl) and "last to first" (ltf) (in the ordered list representing the reading order ... or should we say reading sequence?) ) would make much more sense.

[mattgarrish]

we could consider that the reading order does not have a "left" or "right" document, but a "first" and "last" document instead

I'm not sure I follow. Are you suggesting that we drop ltr and rtl in favour of ftl and ltf, add them as values, something else?

If it's a replacement, how does this work for paginated content? Documents are read from the first document to the last independent of page progression. Page progression just reflects that there are different concepts of which direction to read in. I can go ltr or rtl when going ftl, in other words. (I'm not sure when anyone reads ltf.)

Even in a scrolled environment, you'd want to know whether to move top-to-bottom or bottom-to-top as you move from the first document to the last, so I'd more favour adding ttb and btt.

ftl and ltf just don't intuitively map to any direction.

Maybe we can accomplish the goal of using one property, but I agree with @dauwhe that we'd need more granularity, not less. It feels like overloading, though, as we'd need allow more than one declaration so that the author can define preferred paginated and scrolled directions.

[llemeurfr]

Are you suggesting that we drop ltr and rtl in favour of ftl and ltf?

Yes this was my suggestion: after all a manga is opened on its "last" page, then the natural reading progression is from the "last" to the "first" page of the book. But after re-reading the HTML page progression spec, that uses "left" and "right" terms (without being bothered by vertical scrolling), I finally retract this suggestion; it's better to use the same terms, as the two properties are complementary (but to equal).

[JayPanoz]

there are only two values for page progression direction. Within HTML resources, CSS does allow for overflow in both x and y axes. If a publication resource scrolls "down," it might be a better reading experience for the next resource to appear below. Do we need a "top to bottom" direction?

Reminds me of the scrolled-doc and scrolled-continuous renditions.

I don’t have any strong feeling about that. As a developer, we haven’t implement it yet so I can’t tell what the potential issues are. As a user, I’m used to both since they are a lot of magazine apps using a scrolled-doc rendition for instance, and ebook readers using a scrolled-continuous rendition.

I would probably have an issue with something like top to bottom as a value though, as it is already used in i18n docs to describe scripts direction si it would be a little bit confusing.

[iherman]

I am not sure whether the "top to bottom" issue is relevant here. The RTL/LTR choice dictates things like where menus, TOC-s, etc, are to put on the screen to make it natural to the reader (ie, if the overall progression is RTL then a UI may choose to put the pop-up window with the TOC on the right side of the screen), and this is independent on whether I paginate or scroll.

I would propose to accept the PR as is, and the rest of the discussion should be under a different issue, when we get there, namely under the control of pagination vs. scrolling.

(@rakutenjeff actually reminded me that this PR is, essentially, what EPUB already does.)

[iherman]

@HadrienGardeur we included the relevant infoset item; can this issue be closed now?

[HadrienGardeur]

Yes, I think so.