Pop-up footnotes in sideloaded kepubs gone AWOL in fw 4.0.7523

[jackie_w]

I'm creating this post as a repository for information following several reports of footnote links in sideloaded kepubs no longer appearing as pop-ups on the AuraOne with firmware 4.0.7523.

For all de-DRM'd epub2 format books tested so far (about 30 of them), I've managed to get kepub footnotes to pop-up by doing the following:

1. Physically remove any non-working kepub from the Kobo before proceeding. I think this is safest because step 2 will reorganise the internal structure of the epub.
   
   
2. Open the source standard epub in the calibre Editor and use the Tools - Arrange into folders option to reorganise the epub internal file structure as per the attached image.
   
   
3. Check the HTML code controlling the footnotes. Each footnote is made up of a "matched pair", the code in the chapter text and the code in the footnotes/endnotes file.
   
   The chapter file HTML code should look similar to:
   

   <p class="indent">Text in chapter with a footnote link.<a id="retfn01" href="footnotes.xhtml#fn01">[1]</a></p>

   and the footnote/endnote file HTML code similar to
   

   <p class="footnote"><a id="fn01" href="chapter.xhtml#retfn01">[1]</a>Explanatory footnote text</p>

   I have no reason to believe the class names or filenames are important. The footnote id names may not be important either.
   
   
4. If either or both of the pieces of HTML code are styled using a <sup> or <span class="..."> tag to give the '[1]' text a superscript appearance, make sure the <a> anchor tag is the innermost tag and the <sup>/<span> the outer tag, not vice versa. E.g.
   

   <sup><a id="retfn01" href="footnotes.xhtml#fn01">[1]</a></sup>

5. Use KoboTouchExtended calibre driver to send-to-device the epub-as-kepub in the normal way.

Notes:

• Anyone who is not comfortable with steps 3 and 4 could try excluding these steps. Footnotes not coded this way may never have popped up in previous firmwares either. Perhaps your books are already correctly coded if they had working pop-ups on a non-AuraOne Kobo using fw3.19.
  
• In case anyone is wondering, I have no idea why step 2 has become necessary. It maybe that many different internal file layouts will also work, but I do know my previous preferred layout no longer works. See davidfor's comment in post #3 for extra info.
  
• I have not done enough testing on epub3-sent-as-kepub books which use the newer epub3 method for coding footnotes to reach any conclusions about the best way to make epub3 kepub footnotes pop-up. Personally, I don't have any epub3s with footnotes and I don't want to spend any more time troubleshooting on a firmware which is so close to being superceded. Of course, any contributions from others are most welcome.

Obviously I have no way of knowing whether this method will still work with the new firmware promised for next week

[icallaci]

How did you ever figure this out? I will give this a try when I get some time, but I hate to think of redoing all my epubs, especially the directory structure. The change in the directory structure seems to be important, as all of my footnotes already have the <a></a> tags as the innermost tags, and they are definitely not showing as popups. My stylesheets are located in OEBPS/Styles (instead of OEBPS/ as you show in your attachment), so if that's the main problem, it might be an easy fix for Kobo to implement. I hope, I hope, I hope. Thank you for posting this.

[davidfor]

Good catch. I looked at the book I was testing with, and everything is in the root directory.

But, it looks like it might be simpler. From my testing, the only thing needed is that the text and OPF are not in the root directory. And it doesn't seem to matter what the subdirectory is called.

Also, Kobo do have some notes on the footnotes at https://github.com/kobolabs/epub-spe...kobo-platforms. Reading those explains a few things, including why some ToC pages in books show the popup rather than act as a link.

I have attached the epub I have been experimenting with. The three chapters have the different foot/end notes I could think of. The back-links from the end notes all go the first chapter, but the "Previous location" in the bottom bar is probably the better way to navigate backwards.

[jackie_w]

Originally Posted by davidfor

But, it looks like it might be simpler. From my testing, the only thing needed is that the text and OPF are not in the root directory. And it doesn't seem to matter what the subdirectory is called.

Unfortunately I'm guessing many Kobo users who are obsessive enough (holds hand up ) to want to standardise their epubs to a preferred fixed internal structure are going to have put the OPF file in the root directory. Those who have been less nit-picky may have better luck because having a top-level directory of OEBPS/ seems fairly common in retail epubs (which is why I used this particular value).

Originally Posted by davidfor

Also, Kobo do have some notes on the footnotes at https://github.com/kobolabs/epub-spe...kobo-platforms. Reading those explains a few things, including why some ToC pages in books show the popup rather than act as a link.

Thanks for this link.

Originally Posted by davidfor

I have attached the epub I have been experimenting with. The three chapters have the different foot/end notes I could think of. The back-links from the end notes all go the first chapter, but the "Previous location" in the bottom bar is probably the better way to navigate backwards.

Yes, I guess if you're only ever going to read the epub/kepub on a Kobo eink device the back-links aren't really necessary because the 'Previous location' button is easier to hit. But if you want your footnotes to also pop-up in the calibre Viewer I think the back-links are necessary. It's also advisable to keep them if you may want to read the same epub in a variety of Android apps. Many (most???) Android apps don't have pop-up footnotes but some of them don't have a 'Previous location' option either.

Re: the <a><sup> sequence, I could have sworn that when I was doing my testing one of my kepubs didn't pop-up and switching the order around fixed it. But as your test epub shows the order doesn't seem to matter, so I'll edit the first post accordingly.

[davidfor]

Originally Posted by jackie_w

Unfortunately I'm guessing many Kobo users who are obsessive enough (holds hand up ) to want to standardise their epubs to a preferred fixed internal structure are going to have put the OPF file in the root directory. Those who have been less nit-picky may have better luck because having a top-level directory of OEBPS/ seems fairly common in retail epubs (which is why I used this particular value).

The "OEBPS" directory is so common, I was wondering if it was part of the standard. It doesn't seem to be, but every recommendation I found for the structure had it, so it the way everyone codes it.

Yes, I guess if you're only ever going to read the epub/kepub on a Kobo eink device the back-links aren't really necessary because the 'Previous location' button is easier to hit. But if you want your footnotes to also pop-up in the calibre Viewer I think the back-links are necessary. It's also advisable to keep them if you may want to read the same epub in a variety of Android apps. Many (most???) Android apps don't have pop-up footnotes but some of them don't have a 'Previous location' option either.

The lack of the back link was me being lazy and not doing it.

[DNSB]

Originally Posted by davidfor

The "OEBPS" directory is so common, I was wondering if it was part of the standard. It doesn't seem to be, but every recommendation I found for the structure had it, so it the way everyone codes it.

As far as I recall, the specification says the mimetype file must be in the root directory of the epub file structure and the container.xml file must in a META-INF directory in the root. The rest of the directory structure is found from the content.opf file found at the path in the container.xml file. So no requirement for the OEBPS directory though most publishing software does use it. The epub3 OCF standard does say "It is recommended that the contents of the EPUB Publication be stored within its own dedicated directory under the container's root." while the epub2 OCF standard said much the same in a wordier fashion.

[JSWolf]

Originally Posted by DNSB

As far as I recall, the specification says the mimetype file must be in the root directory of the epub file structure and the container.xml file must in a META-INF directory in the root. The rest of the directory structure is found from the content.opf file found at the path in the container.xml file. So no requirement for the OEBPS directory though most publishing software does use it.

Yes, you are correct.