Offset value for pagination

decoherencer commented 6 months ago

I don't mind mostly double pages appearing if Epubs don't have those properties to enforce pagination always, but I feel there should be an offset value to offset the first page; most of the time, it's this issue of unmatched pages getting into double page-view instead of displaying with the next one. An offset setting would help a lot. I may be confused with another software, but I used to use this long ago.

related #1147

johnfactotum commented 6 months ago

I may be confused with another software, but I used to use this long ago.

You're probably thinking of the "Odd Pages Left" setting in Evince.

jancborchardt commented 5 months ago

Currently the page layout for double pages always seems to be like this: 1	2
3	4
5	6

Which is not what any standard book does and thus it also destroys the layout of a spread/centerfold. Instead this would be correct:

Empty	1
2	3
4	5

Seems like this could be the default, without any offset setting needed, no?

johnfactotum commented 5 months ago

As far as I can tell, yes, for PDF and CBZ, odd page recto should be the default. But the setting is still needed because a large number of documents require odd pages to be verso.

Not entirely sure about fixed-layout EPUB/Kindle books, though. I don't see a particular requirement in the spec and my interpretation has been that it should default to verso, and this is indeed what at least some books assume.

jancborchardt commented 5 months ago

Not entirely sure about fixed-layout EPUB/Kindle books, though. I don't see a particular requirement in the spec and my interpretation has been that it should default to verso, and this is indeed what at least some books assume.

At least for the EPUBs which I have, all of them would look better with odd page recto as default. They have a cover page, which would be on the right side (or centered, or left) but definitely alone on the first 2-up view. Then when you open the book you see page 2 left and page 3 right.

But yeah as you said, likely a lot of documents still require a setting anyway. However I would be curious to know if it’s really the majority of documents which do not assume a cover page?

johnfactotum commented 5 months ago

With EPUB, it doesn't really have anything to do with cover pages. You're supposed to specify the page-spread-* properties. You can do that with the first page, or any page. Some books set it for every spine item to ensure that every spread would be correctly displayed.

The problem only arises when the EPUB fails to include this info. According to the spec, if you don't specify, it basically means that the spread placement is unimportant:

To indicate that two consecutive pages represent a true spread, EPUB creators SHOULD use the rendition:page-spread-left and rendition:page-spread-right properties on the spine items for the two adjacent EPUB content documents, and omit the properties on spine items where one-up or two-up presentation is equally acceptable.

I could be missing something, but it doesn't seem to say anything about the default placement of the first page. It only says,

When a reading system renders a synthetic spread, the default behavior is to populate the spread by rendering the next EPUB content document in the next available unpopulated viewport, where the next available viewport is determined by the given page progression direction or by local declarations within EPUB content documents.

But we should just do whatever other reading systems are doing. I might be missing something, but from testing with the file from https://github.com/koreader/koreader/issues/6215, which doesn't seem to have any page-spread-* properties and has a blank page before the cover page, it would appear that both Thorium and Apple Books display the spreads correctly. If so then we should continue defaulting to verso page first for EPUBs.

A counter example is "The Real Mother Goose" from https://bbebooksthailand.com/samples.html. This books doesn't use the standard EPUB properties. Instead it relies on the proprietary open-to-spread property in META-INF/com.apple.ibooks.display-options.xml, which is~n't supported by Foliate. If I have to guess, this is probably the reason why the EPUBs you have are displayed wrong.~ now fixed with https://github.com/johnfactotum/foliate-js/commit/51c02bf594d32d3e4b77d98e2db75721f14ab74c.

It must be emphasized, though, that the above doesn't necessarily apply to KF8 (AZW3) files. Currently it will read the RESC record, which might contain the correct page-spread-* properties. But I'm not sure what the expected behavior would be if this is not available. From the KF8 version of "The Real Mother Goose" above, unlike the EPUB version, there's no cover page.

But from Amazon's guidelines, if you don't specify page-spread-* in the EPUB, it will default to page-spread-center, which means it won't render any spreads at all!

Anyway, the only way to be sure would be to prepare a bunch of test cases and open them with Apple Books, Thorium Reader, Kindle Previewer, etc.

jancborchardt commented 2 months ago

Hi again @johnfactotum, I checked a bit more regarding this. :) To be clear, my background is design and UX, so I’m looking at this very much from the user perspective and what would be expected, less from what can technically be defined in the formats.

The metadata of the specific epub I tested has these properties, but no page-spread-* anywhere I could see:

<meta property="rendition:layout">pre-paginated</meta>
<meta property="rendition:orientation">auto</meta>
<meta property="rendition:spread">auto</meta>

This is what happens with other apps with this specific ebook:

Thorium: Shows the title page on the right and shows the spreads correctly (but for some reason it’s very slow)
Apple Books: Same thing, title page alone on right / odd page recto

Also UX-wise it makes sense to show the first page alone, and just assuming it is a title page:

What very likely is a title page is nicely presented
It feels more like opening an actual book
epubs which might have layout peculiarities left/right can be correctly viewed
Some books which don’t define it are well handled

According to the spec, if you don't specify, it basically means that the spread placement is unimportant

@johnfactotum I wouldn’t interpret it exactly like that, as it says:

one-up or two-up presentation is equally acceptable

So rather it sounds like "it doesn’t matter whether you show a single page or both at the same time". But it doesn’t really clarify showing pages two-up with odd page verso?

johnfactotum commented 2 months ago

Apple has a its own option called open-to-spread for this. See my edit above:

it relies on the proprietary open-to-spread property in META-INF/com.apple.ibooks.display-options.xml, which is~n't supported by Foliate. If I have to guess, this is probably the reason why the EPUBs you have are displayed wrong.~ now fixed with johnfactotum/foliate-js@51c02bf.

The fix is unreleased, but one can test it at https://johnfactotum.github.io/foliate-js/reader.html.

jancborchardt commented 2 months ago

@johnfactotum yeah, I saw your edit before my comment and did test with the online version – but at least with the epub I tested with, it’s showing the title page verso, unlike Apple Books or Thorium when viewing the same epub.

johnfactotum commented 2 months ago

Hmmm. Yes, you're right. If you don't specify any page-spread-* properties, Thorium does put the first page recto. So I guess that's what Foliate should do.

However now we have the opposite problem. Namely, why does the file from https://github.com/koreader/koreader/issues/6215 render correctly in Thorium?

So after some testing, I think the problem is that, for some godforsaken reason, apparently you're supposed to ignore linear="no" for fixed layout books. The only written evidence I could find is one line from https://help.apple.com/itc/booksassetguide/en.lproj/static.html:

Note: Nonlinear content is for flowing books, and is not supported for fixed-layout books.

I suppose this is the reason why KindeUnpack will almost always insert an extra cover page? That was something that always puzzled me... And it's still a mystery to me, how one is supposed to determine when to insert that cover page.

Additionally, looking at https://github.com/kobolabs/epub-spec, it seems that for the Kobo iOS app at least, it's in fact impossible to set the first page to the left.

The Kobo iOS app will always [emphasis added] display the first page centered and as its own spread.

Apparently Thorium also has that kind of automatic "first page centered" rendering. But not always. Only in some cases, and I'm at a loss as to how it's doing that. But this is less important, I guess, as it does not affect the contents of the book.

TL;DR: For EPUB, it needs to make first page recto by default, and ignore linear="no". Or at least it should ignore it for the purpose of determining which side the page should appear on.

For Kindle, the same applies. On top of that, one needs to investigate when to insert extra cover page.

jancborchardt commented 2 months ago

@johnfactotum awesome, tested in the online version and it works great now! Let me know when the flatpak is updated, I can test that too.

johnfactotum / foliate

Offset value for pagination #1318