"Polish Book" causing ToC to disappear in ePub?

[stasiana]

I am getting strange behavior when using polished epubs with a Kobo Sage. You access this feature by pressing "P" in Calibre. I've tried many different combinations of options in this menu but the latest is "update metadata", "update cover", "remove book jacket", "upgrade book internals" checked.

I get an original ePub. View it on the Kobo reader. The ToC shows properly.

I polish the ePub and send the polished version to Kobo reader. The ToC is now gone. But the Calibre reader still shows the ToC properly. So it seems like the polish process is corrupting the ToC in the way that fails on the Kobo.

If I then convert the polished ePub to a kepub and send that to the Kobo reader, the ToC shows up properly again.

Polish books does something with the ToC that makes it fail on the Kobo, it seems. Is this a bug? Anyone else seen this?

[kovidgoyal]

dont use upgrade book internals, the kobo is probably having issues with epub 3

[stasiana]

Originally Posted by kovidgoyal

dont use upgrade book internals, the kobo is probably having issues with epub 3

Just figured this out too. Thanks for confirming.

What is actually the difference between epub, epub3 and kepub?

[stasiana]

After further investigation, it doesn't seem so simple.

The Kobo reader doesn't have any problems with epub3 files I download from https://www.gutenberg.org/ or https://standardebooks.org/. It only has a ToC problem with epub3 generated by "Polish" in Calibre.

So it would seem that epub3 files generated elsewhere are somehow more compatible than epub3 files generated by Calibre.

[Karellen]

Originally Posted by stasiana

The Kobo reader doesn't have any problems with epub3 files I download from https://www.gutenberg.org/ or https://standardebooks.org/. It only has a ToC problem with epub3 generated by "Polish" in Calibre.

Would you mind checking the book in the Editor and confirm if either the nav.xhtml or toc.ncx files are present or if both are present in the books that work and don't work.

I've also noticed the missing TOC issue on the Libra2 when using epub3.

[Quoth]

Originally Posted by stasiana

What is actually the difference between epub, epub3 and kepub?

This is a simplified explaination

It's epub2 as epub1 was called OEPS or OEBPS (Open eBook Publication Structure) and dates to about 1998.

The epub3 has many different options and the epub2 ToC is optional for "fully" epub3 based apps, but needed for many ereaders and apps. The native epub has a different system contents file. Also epub3 has many optional features, some of which are multimedia or interactive and thus not needed for "real" ebooks that are simply text and images. Additionally epub3 has a fixed layout option to do paper book replication, but differently to PDF (which is deliberately EXACTLY what a print on paper would be and used to generate paper print).

Likely if you "Polish" and "upgrade" internal you get an epub3 with no fallback epub2 ToC. This can be automatically added in Calibre Editor.

The epub3 from Gutenberg have no "fancy" epub3 features and have also the fallback epub2 ToC file. Both sorts of epub are renamed zip files. If you rename to zip you can extract all the files! Handy to get the images without Calibre.

In theory, if you knew what you were doing you could use a text editor and repack to zip and rename to epub. It's better to use Sigil or Calibre.

The kepub is Kobo's proprietary extension to epub2. It has extra <span> stuff </span> in the HTML files. The epub on a Kobo uses Adobe renderer, Adobe Digital Editions (abbreviated ADE). The kepub files use Kobo's own renderer which allows zooming images and popup footnotes but does the text layout differently. Some people prefer kepub and some prefer epub2.

An epub2 and epub3 can look almost identical, and pretty much will be if the ebook was automatically created from a properly styled docx file and is not fixed layout epub3.

The epub3 has better support for semantic based HTML that isn't recognised by epub2, but the onscreen appearance may be identical. Epub3 is better for textbooks with support for equations and javascript.

[DNSB]

Originally Posted by Quoth

The kepub is Kobo's proprietary extension to epub2. It has extra <span> stuff </span> in the HTML files. The epub on a Kobo uses Adobe renderer, Adobe Digital Editions (abbreviated ADE). The kepub files use Kobo's own renderer which allows zooming images and popup footnotes but does the text layout differently. Some people prefer kepub and some prefer epub2.

Minor nit is that kepub is usable with either ePub2 or ePub3 but it's main use was to trigger using the ePub3 renderer (Kobo's ereaders have an RMSDK renderer which supports Adobe's ADEPT DRM and a Webkit based renderer which supports quite a bit more ePub3 features).

[Quoth]

Originally Posted by DNSB

Minor nit is that kepub is usable with either ePub2 or ePub3 but it's main use was to trigger using the ePub3 renderer (Kobo's ereaders have an RMSDK renderer which supports Adobe's ADEPT DRM and a Webkit based renderer which supports quite a bit more ePub3 features).

I did write it was a simplified explanation and though I used kepub at first on my original H20, I don't know specific details of compatibility. At a simplistic level you can rename file to use the kepub renderer?

[JSWolf]

Originally Posted by Quoth

I did write it was a simplified explanation and though I used kepub at first on my original H20, I don't know specific details of compatibility. At a simplistic level you can rename file to use the kepub renderer?

You can do the rename. But not everything works such as highlighting.

[DNSB]

The rename was more for use by authors so they could check for any formatting differences between the two renderers on various platforms.

From the KoboLabs epub-spec page:

Sideloading for Testing Purposes

Kobo encourages the testing of content on all its reading platforms by sideloading. Content should display identically whether sideloaded or downloaded to a device from the Kobo store. Instances where this is not the case can be reported to renderingissues@kobo.com and the EPUB in question will be logged for investigation.

Here’s how to sideload content on Kobo's reading platforms:

eInk

Connect the device to your computer via USB.
Find the drive on your computer in Finder or Windows Explorer.
Drag your EPUB onto the device. To trigger the Kobo WebKit, change the file extension to .kepub.epub. To trigger the Kobo WebKit for a Fixed Layout title, change the extension to .fxl.kepub.epub. (If the extension is left unchanged it will render using the Adobe Digital Editions WebKit. This is the default display engine for sideloaded content to enable bookmarking, searching and highlighting.)
Disconnect your device. The file will automatically appear in your library.

Sideloaded EPUBs with the ".fxl.kepub.epub" or ".kepub.epub" will disable bookmarking and note keeping. Thumbnails for covers may not display. Otherwise the reading experience and content display will be identical to how the file would display when loaded through the store. Leaving the extension as ".epub" will enable bookmarking and note keeping and will trigger the ADE display engine.

[Quoth]

I extensively use annotation by touch keyboard. Just a short note made intelligible by a big highlight, so obviously renaming an epub would be bad for me. The kepubs created on the fly by the Extended Kobo driver (or pre converted and loaded by USB or Wifi from Kobo do allow bookmarks and annotations).

Calibre (either conversion in advance to kepub) or extended driver on the fly conversion to kepub makes the inferior renaming feature obsolete.

[DNSB]

Originally Posted by Quoth

I extensively use annotation by touch keyboard. Just a short note made intelligible by a big highlight, so obviously renaming an epub would be bad for me. The kepubs created on the fly by the Extended Kobo driver (or pre converted and loaded by USB or Wifi from Kobo do allow bookmarks and annotations).

Calibre (either conversion in advance to kepub) or extended driver on the fly conversion to kepub makes the inferior renaming feature obsolete.

While you and I may be happy using calibre, kepubify, etc., there are a lot of people out there who are not running those programs and have no interest in running them, often a class of user for whom renaming a file is scary enough and don't mention the CLI.

[Quoth]

Originally Posted by DNSB

… often a class of user for whom renaming a file is scary enough and don't mention the CLI.

A console is a Nintendo, PS5 or xbox.
What's a Windows Console?

Some of us antiques started before WIMPs existed

I was at an antique fair for 1st time in years. I'm now older than most of what's on sale.
"No, sir, that's not a 1970s telephone you're selling, it's 1960s!"

Granddaughter looks at thing with marble handle, no dial and two cords. "What's that?"
Much younger grandson, "It might be a telephone?"