Reader support of EPUB3, :target, popups

[ghmerrill]

I've just finished the body of my book in Sigil in Epub3. It passes epubcheck with no errors and only a couple of trivial warnings. It looks great in several readers I've tried.

I'm now experimenting with a few features I'd like to add, and these include (1) use of :target for highlighting citations in the References section, (2) Tooltips, and (3) popup notes.

I haven't tried the popup notes yet, but I have the :target stuff and the tooltips working in my Sigil version (and displaying as expected in Sigil's Preview window). However, when I move the book into either Calibre or Adobe Digital Editions, the tooltips work, but the :target code fails (all it attempts to do is to highlight by setting the background color). It does jump to the link target, but the background isn't changed.

What's going on here? Do these readers just not support :target?

I'm doing these simple "pre-tests" before I invest time in coding up a lot of this stuff for my intended Kindle edition. But now I'm concerned about support. I know that Kindle at least supports popup notes (I have a Kindle book in which those work fine -- so I know it can be done).

But what's the problem I'm running into with :target in Adobe Digital Editions (4.5) and Calibre?

[jhowell]

Originally Posted by ghmerrill

I know that Kindle at least supports popup notes (I have a Kindle book in which those work fine -- so I know it can be done).

I am curious what you mean by that.

Kindles can produce popup footnotes as a special case. They also allow popup panels for fixed layout comics and children's books. I don't know of any other popup capability on Kindle.

Kindles only support a small subset of EPUB3 functionality. Refer to the Kindle Publishing Guidelines. for details.

[Doitsu]

Originally Posted by ghmerrill

I'm now experimenting with a few features I'd like to add, and these include (1) use of :target for highlighting citations in the References section, (2) Tooltips, and (3) popup notes.

IMHO, only a very limited number of pseudo elements are supported. A couple of years ago I tested it with an .epub for Kindle conversion.
Note that many elements that I found to work aren't officially sanctioned by Amazon. If you want to be on the safe side, use only the pseudo elements listed inn Appendix C of the Kindle Publishing Guidelines.

[ghmerrill]

Originally Posted by jhowell

I am curious what you mean by that.

I mean that I have a book in my Kindle library that I bought from Amazon that has what appears to be a standard implementation of popup footnotes. Perhaps in some way it's not "really" a Kindle book? It's listed on Amazon as an eTextbook and appears as any other book does in my Kindle library. It lists the usually large array of Kindle devices as being supported.

If it's not a Kindle book, perhaps you can tell me what it is:

https://www.amazon.com/Beyond-Hoax-S...s=books&sr=1-1

[ghmerrill]

Originally Posted by Doitsu

IMHO, only a very limited number of pseudo elements are supported. A couple of years ago I tested it with an .epub for Kindle conversion.
Note that many elements that I found to work aren't officially sanctioned by Amazon. If you want to be on the safe side, use only the pseudo elements listed inn Appendix C of the Kindle Publishing Guidelines.

Yeah, thanks. I was looking at that list yesterday and thinking pretty much the same. But I always wonder how up-to-date and complete the Amazon documentation is -- especially in the context of seeing a book that appears to make use of features not listed.

But I also agree that being on the safe side is likely the best idea. So I think I'll proceed now with a "safe side" approach and when all of that is to my satisfaction, maybe experiment briefly with some other things. Part of this is just my being stubborn about trying to duplicate some features I'm seeing in someone else's published book.

[j.p.s]

Originally Posted by ghmerrill

I know that Kindle at least supports popup notes.

Notes in ebooks do not need to be in some special popup notation to be displayed as popup notes in kindles.

An EPUB with code like

Blah, blah, blah
<a id="noteref_1"/><a class="link" href="ar01s02.html#note_1">*</a></p>
<p>Blah, blah, blah
...
</p>
<p><a id="note_1"/><a class="link" href="ar01s02.html#noteref_1">*</a> Some taxonomists consider the Sea Otter
to be so different from the Land or River Otter that it is considered
to be a Sub-Family.</p>

and converted to kindle format by kindlegen will display the note as a popup on the kindle.

[jhowell]

Originally Posted by ghmerrill

I mean that I have a book in my Kindle library that I bought from Amazon that has what appears to be a standard implementation of popup footnotes.

I was not sure whether you were referring specifically to footnotes. That answers my question.

Originally Posted by ghmerrill

Perhaps in some way it's not "really" a Kindle book? It's listed on Amazon as an eTextbook and appears as any other book does in my Kindle library. It lists the usually large array of Kindle devices as being supported.

If it's not a Kindle book, perhaps you can tell me what it is:

https://www.amazon.com/Beyond-Hoax-S...s=books&sr=1-1

That is a normal Kindle book with reflowable layout. As j.p.s pointed out the Kindle app looks for a specific pattern of content (mainly matching forward and back links) an turns that into a popup footnote without any explicit pop-up related HTML coding. That is what is happening in that book.

[ghmerrill]

Originally Posted by jhowell

As j.p.s pointed out the Kindle app looks for a specific pattern of content (mainly matching forward and back links) an turns that into a popup footnote without any explicit pop-up related HTML coding. That is what is happening in that book.

Hmmm ... now I feel like a real dummy.

Well, thanks to both of you for this. I started this book about 10 years ago and have been working on it sporadically since then. Originally I was testing my Sigil version by converting to a Kindle format with Calibre. But since then I've just been working in Sigil and not converting to Kindle to test for several years now. So what you're saying is enlightening and of course now my whole understanding of the Kindle publication process has changed as well (since the Kindle publication process has changed). I've just downloaded the Kindle Previewer for the first time, and this seems to really simplify things. Testing should be easier. Duh.

One remaining question: Given that this popup footnote/endnote behavior is app-specific, is it documented anywhere? I haven't managed to come across it anywhere and so have gone off in the direction of implementing the behavior in Epub3 -- which is clearly a waste of time if the target is Kindle. Does Amazon document features like this somewhere? The KDP "Create Links to Footnotes" page doesn't mention anything about this, and the HTML code example there does not exhibit the necessary pattern.

[jhowell]

Originally Posted by ghmerrill

Given that this popup footnote/endnote behavior is app-specific, is it documented anywhere?

See section 10.3.12 (Footnote Guidelines) in the Amazon Kindle Publishing Guidelines.

Regardless of whether the aside element is used, Amazon requires formatting footnotes with bidirectional hyperlinks (the text is linked to the footnote and the footnote is linked back to the text). This makes it easier for customers to return to the text after viewing the footnote. On some Kindle devices, such as Kindle Paperwhite, footnotes with bi-directional hyperlinks are displayed in a pop-up.

[ghmerrill]

Originally Posted by jhowell

See section 10.3.12 (Footnote Guidelines) in the Amazon Kindle Publishing Guidelines.

Yeah, I saw this and read and re-read it multiple times. Perhaps (from years of dealing with formal language specs) I tend to read things a bit too closely from time to time (), but I interpreted this as a constraint on footnotes -- however they are implemented. And moreover, as an informative comment on the use of the <aside> element.

So I saw the requirement for bidirectional links in footnotes and said to myself "Okay. Roger that." And then "But then how do I implement the popup?" To what, exactly, do I apply this constraint?

The next sentence in that paragraph is of no help in answering that question since it says only that some Kindle devices will display footnotes having bidirectional hyperlinks as popups. But it's still nowhere said what a footnote is. Nor is any characteristic example given.

Is any construct in which there's a bidirectional hyperlink interpreted by the device as a "footnote" and rendered as a popup? That seems a bit goofy. Then something is a footnote (or regarded by "some Kindle devices" as a footnote) if and only if it contains a bidirectional hyperlink? Then I could never have anything with a bidirectional hyperlink which on such a device would not be rendered as a popup? Not exactly ANSI- or ISO-level description of a language/implementation feature.

Hence my confusion. Apparently I missed the "obvious". But now at least I have a good experimental environment and good pointers to what should work.

[jhowell]

Originally Posted by ghmerrill

Is any construct in which there's a bidirectional hyperlink interpreted by the device as a "footnote" and rendered as a popup? That seems a bit goofy. Then something is a footnote (or regarded by "some Kindle devices" as a footnote) if and only if it contains a bidirectional hyperlink? Then I could never have anything with a bidirectional hyperlink which on such a device would not be rendered as a popup? Not exactly ANSI- or ISO-level description of a language/implementation feature.

All good questions.

Getting things to work in the Kindle ecosystem involves some trial and error since the precise details are not documented anywhere. Amazon's publishing guidelines are nothing like a formal specification.

[ghmerrill]

So, in addition to that, it appears that when they/you say "on the kindle" this means ON THE FREAKING KINDLE -- and NOT, for example in the Kindle Previewer (which is supposed to be emulating "the Kindle"). Eh?

I just took that code you provided, stuck it in my document (changing only the local file names), loaded it into the Previewer, and ...

All the links and backlinks work fine (of course), but no popup appears. I guess it's a bridge too far to expect them to implement that behavior in the portable Previewer. Too bad.

So how DO I test this prior to uploading the book to Amazon for publication? I'm thinking (since you suggest that Kindlegen is what puts the pop in the popups) that if I just convert to a Kindle format via Calibre then this will lack the magic that Amazon imposes to get the popup behavior? How is this (if it is) testable prior to the upload/publication step? I'd REALLY like to experiment with the popup notes thing. But how to do this?

[j.p.s]

Calibre takes various liberties in the conversion process which may or may not suit you and may or may not keep amazon happy. Many of those can be changed with options and settings.

You might want to consider borrowing a kindle reader or buying one used or new. But each firmware version and each hardware model behave differently.

To see what calibre does in each direction, you can convert an EPUB to KF8 by both calibre and kindlegen, then convert both KF8 files to EPUB by calibre and kindleunpack (giving 4 secondary EPUBs. I think you will find that kindlegen -> azw3 -> kindleunpack comes closer to the original EPUB than any of the other 3.

[jhowell]

Originally Posted by ghmerrill

So, in addition to that, it appears that when they/you say "on the kindle" this means ON THE FREAKING KINDLE -- and NOT, for example in the Kindle Previewer (which is supposed to be emulating "the Kindle"). Eh?

It depends. The Kindle Previewer emulates the latest renderers for Amazon's KFX, KF8, and MOBI formats. It does not exactly replicate the functionality of any one device. Each renderer has different features and the implementations vary across Kindle apps and devices and assorted releases of them. That is one reason why professional e-book formatters have job security.

Originally Posted by ghmerrill

All the links and backlinks work fine (of course), but no popup appears. I guess it's a bridge too far to expect them to implement that behavior in the portable Previewer. Too bad.

The Previewer definitely does implement popup footnotes, but only for KFX format AFAIK. You can tell if your book is being converted to KFX by the presence of a green check mark labeled "Enhanced Typesetting" in the left pane of the Previewer.

Originally Posted by ghmerrill

So how DO I test this prior to uploading the book to Amazon for publication? I'm thinking (since you suggest that Kindlegen is what puts the pop in the popups) that if I just convert to a Kindle format via Calibre then this will lack the magic that Amazon imposes to get the popup behavior?

That is not how it works. Your HTML is not changed by kindlegen. The popup magic happens in the software that renders the book on Kindle apps and devices.

Originally Posted by ghmerrill

How is this (if it is) testable prior to the upload/publication step? I'd REALLY like to experiment with the popup notes thing. But how to do this?

Professional formatters have an assortment of Kindle apps and devices that they use for testing. They know from experience which features are problematic and should be avoided. Even then there are occasionally surprises once a book is actually published.

[ghmerrill]

Originally Posted by jhowell

The Previewer definitely does implement popup footnotes, but only for KFX format AFAIK. You can tell if your book is being converted to KFX by the presence of a green check mark labeled "Enhanced Typesetting" in the left pane of the Previewer.

Ah, it works!! And for each of the three device types. Not quite sure what happened. Now I can sleep well tonight.

That is not how it works. Your HTML is not changed by kindlegen. The popup magic happens in the software that renders the book on Kindle apps and devices.

Okay, that's a big part of the question I was asking (Who does what to whom, and when?). Also, I do have a couple of Kindles on hand. One is a rather old Fire that probably needs an OS upgrade and hasn't been used in a year or so. The other is one of the new bigger Fires. So I may try stuff on them, but I'm really not doing any crazy stuff with the book formatting. So I think just using the Previewer should be fine.

You guys have been great. I just got a response to my question from Amazon Kindle support that was vaguely general and dodged answering the questions. Then I rephrased the question more simply and directly and got the same answer. But I'm confident now that the Previewer will show me everything I want. So you've been very helpful. Thanks again.