kobolabs / epub-spec Goto Github PK
View Code? Open in Web Editor NEWDetails on the elements of the ePub spec that Kobo supports, as well as other information on the Kobo reading platforms.
License: Other
Details on the elements of the ePub spec that Kobo supports, as well as other information on the Kobo reading platforms.
License: Other
My selector h2:first-child
does not work in Kobo. But this is CSS level 2 feature..
If I'm not mistaken, there’s nothing about iframe in the spec.
As far as I know, it is supported in iOS but with a few caveats e.g. the iframe is automatically opened in Safari if it’s an external ressource, a case for which it would definitely be cool to have navigator.epubReadingSystem
(see issue #26) because I consider this “terrible-UX-borderline-to-bug” from the user’s point of view.
Haven’t tested iframes with internal ressources yet but this might become the new new hype since kids learnt some months ago you can use online services to create “widgets” you can then implement as iframes in your ebook file.
Just so that you know, the Viewport height sub-section in the CSS section doesn’t make any sense.
Viewport Height (vh)
Kobo advises against using the CSS element
vh
in reflowable content as it is not supported on all display engines and may result in text getting cut off or overlapping with other content. More conventional elements such asheight
ormax-height
are recommended.
First and foremost, the main use case for vh
is (portrait) images, not text. And it’s useful for images.
Then, vh
is not a CSS element but a unit. So it’s like %
, em
, px
, etc.
In other words, you use vh
in combination with height
or max-height
, not as a substitution of those two CSS properties. What you mean is probably:
A more conventional unit such as
%
is recommended.
But that brings other issues as it means you must make sure (on your side) that you don’t break the cascade and the container wrapping the content with a (max-)height
+ %
unit combo can have an explicit/computed height
(or else the value computes to auto
or none
). Which is to say the author’s declarations are then useless.
For instance:
html, body {
height: 100%;
}
figure {
height: 80%;
}
img {
height: 100%;
}
Will fail if you have some wrapper and don’t set its (max-)height
:
<html>
<body>
<div class="kobo-wrapper">
<figure>
<img alt="" src="img.jpg" />
</figure>
</div>
</body>
</html>
Which is the reason why the viewport units exist, BTW, since the viewport-percentage lengths are relative to the size of the initial containing block.
As regards interop, it’s worth noting other vendors are actually advising authors to use vh
units e.g. portrait images. So you might want to introduce feature queries to authors at some point, since it can solve a lot of your limitations/issues related to having to deal with both the RMSDK and your own Reading System.
In the case of vh
, the underlying logic would look like this:
figure {
height: 80%;
}
img {
height: 100%;
}
@supports (height: 80vh) {
figure {
height: auto;
}
img {
height: 80vh;
}
}
Authors have to deal with this anyway, and features queries are the only option if you want to make some progress and kill a lot of maintenance on your side in the longer term (such as dealing with the cascade + %
units for height
). But there’s also small caps, and a lot of issues you might encounter in the future but are not in the spec yet.
In the JavaScript section, you recommend not to alter the layout of the book using scripts:
it is recommended not to use JavaScript in reflowable content in ways that may alter the layout of the book.
Actually, you don’t even need JS to alter the layout since you can create an accordion-like widget using <details>
(cf. http://html5doctor.com/the-details-and-summary-elements/)
FYI, <details>
work as expected in Kobo 4 iOS (and pagination is automatically refreshed).
It is not working in Kobo 4 Android: only <summary>
is displayed, <details>
is closed by default and you can't toggle it. Also, it looks like it triggers a bug: the last page of the xhtml file is duplicated.
Does it mean it is supported in the meta section of the opf file, or in itemref?
I tried both options to make rendition spread none, and it is still in spread mode in my Kobo App.
Is the active-class metadata supported in EPUB 3 FXL docs? Is it required? If you use it, can you use a different class name than "kobo-smil-highlight"? (http://www.idpf.org/epub/30/spec/epub30-mediaoverlays.html#sec-docs-assoc-style) I ask because Apple requires it, and, despite the fact that the spec explicitly says otherwise, they also seem to require that you use the class name "-epub-media-overlay-active".
The transform skew (css3) does not work on font, on e-ink kobo with kepub extension
p {
transform: skew(-20deg);
}
Hi,
I am an epub creator and want to sideload my epubs on a Galaxy tab (Android) for testing purposes. I have the Kobo App installed on it. Even if I follow the instructions on that sheet about sideloading, there is no import options appearing when I select options (the three dots on the top right), only "sync".
Same thing for Desktop App on Mac OS X. Can't make it work.
Thanks for any help.
Marie
Could you clarify this part so that we know if it is possible to use default/user fonts in publisher’s CSS (font-stacks)? And if it is, could you list the names we can use?
I’ve been trying to use eInk fonts such as Malabar or Amasis for weeks, using alternative names like MalabareText and "Malabar eText", but the stack falls back to Georgia (serif) or Avenir (sans-serif) on my Kobo Mini.
Also, on my Kobo Mini, sans-serif fonts don’t ship with italic styles and are replaced with bold, which creates extra customer care as people think we don’t know how to typeset….
There is no mention of whether kobo ereaders and apps recognize any kind of landmark, as listed in the Nav doc, inside <nav epub:type="landmarks">
, and whether they trigger a specific behavior if so. For example, some other ereader apps will open straight to the first epub:type="bodymatter"
landmark when opening the ebook for the first time.
Clearing up either way (“no kind of landmark has any effect whatsoever in kobo ereaders and apps”, or “kobo ereaders and apps only recognize landmarks of the kind ??? in order to ????”, etc.) is necessary IMHO, since the different available terms in the vocabulary for landmarks do have specific meanings which might therefore suggest triggering specific behaviors.
You might want to be more specific when referencing EPUB 3 markup like epub:type, as some people may not know that it is not valid to add those to EPUB 2 files.
kobo aura 4.20.14622 + kepub extension
html, body {
width: 100vw;
height: 100vh;
overflow: hidden;
background-color: black;
}
main {
position: absolute;
background-color: white;
color: black;
width: calc(100vw - 2rem);
height: calc(100vh - 2rem);
margin: 1rem;
}
if i use width: calc(100% - 2rem);
, it works!
I have an ebook (epub, probably 2) where changing the font from embedded to custom is impossible. Also all text is in bold (except italics).
Clara HD.
Sometimes <figcaption>
(inside <figure>
with image), is rendered on the next page, even if there is 50% place below the image. Unfortunately don't know why..
On my Clara HD reader (latest soft), links to notes don't work:
I have a reference:
<a epub:type="noteref" href="przypisy.xhtml#endnote-8-1" class="noteref">*1</a>
And a note in przypisy.xhtml:
<aside epub:type="endnote" id="endnote-8-1">*1. Francisco López de Gómara, Cortés: The Life of the Conqueror by His Secretary, przeł. i oprac. Lesley Byrd Simpson, Berkeley-Los Angeles 1964, s. 8.</aside>
Issue: Touching/clicking anchor link does nothing on my ereader.
Hi,
I have hyperlinks in my epub that reference another page (they don't have any epub:type attribute). The problem is that they fulfill Kobo's 4 criteria to display the linked content in a popup and I don't want that!
Amongst the reasons:
Is there a way to disable it?
Thanks.
Am testing in my Kobo Touch a book I built. The Touch just updated itself to the latest O/S. In the epub, I have sections to mimic a screenplay:
.speaker
{margin-left: 20%;
margin-right: 20%;
margin-bottom:0;
font-size:1em;
text-indent:0;
text-align:center;
font-family:"Courier New", Courier, monospace;}
When I tested it, if the default (unjustified) text is left as is, no problem; but if I turn justification on, the margins are still respected, but the text-align:center is ignored and reverts to left aligned. I have tried a workaround by adding text-align:center inline styling, but to no avail. Note that this problem does not occur with headings (h1, etc) but it does occur with all other styles that are all center aligned including my title, subtitle, and author styles; for example:
p.Subtitle
{margin-right:0em;
margin-bottom:2em;
margin-left:0em;
text-align:center;
text-indent:0%;
font-size:1.5em;
font-weight:bold;
line-height:120%;}
This did not happen in my previous O/S, so I am assuming this is a bug.
One location (https://github.com/kobolabs/epub-spec#image-formatting) in this document says, "but not Scalable Vector Graphics (SVG), which are not supported on all reading platforms."
Another location (https://github.com/kobolabs/epub-spec#scalable-vector-graphics-svg) says, "Text, images and animations in SVG are supported on all Kobo reading platforms (performance on eInk is limited but the animations will function)."
Please clarify.
In the "Fallback Statements/Switches" section, HTML comment tags are placed around the epub:switch markup, leaving only the default case uncommented.
Is that markup required for certain legacy Kobo reading systems? If so, do you know which reading systems require it? Thanks!
Obfuscated Fonts Are Not Currently Supported by the Kobo CMS
Non-sideloaded titles with obfuscated fonts will display the reading
platform’s default font instead of the intended font. As a result they
may fail content QA. However, work is underway at Kobo to support
obfuscated fonts and render these titles correctly.
I use InDesign CC to create an ePub file, although I do a lot of post-processing to set up the file for iBooks, Nook, Kindle, etc. InDesign automatically applies the IDPF obfuscation system to all embedded fonts. This font obfuscation method is handled just fine (at least when side-loading) to Nook, iBooks, etc.
When creating a Kindle file, KindleGen throws away obfuscated fonts, so I do have a method of de-obfuscating the fonts. (They are later obfuscated/encrypted somewhere in the Amazon CMS, apparently.) I can do the same "clarifying" process on the fonts, with the file that I submit to Kobo, if needed.
However, a number of the fonts that I am using are licensed from Adobe, and they have something of a requirement that any embedded fonts are properly obfuscated to prevent ripoff. If I submit an ePub to the Kobo CMS that has unobfuscated fonts, are these obfuscated by the time they hit the readers? The Kobo Touch seems to be able to handle such fonts in any case.
Thanks.
In your section on inline styling, you give some examples.
HTML:
<p class="normal text">Sample text before page break</p>
<p class="normal text2">Sample text after page break</p>
CSS:
@normal text { footer {page-break-after: always;} }
vs.
HTML:
<p class="normal text">Sample text before page break</p>
<code><div style="page-break-before:always;"></div>
<p class="normal text2">Sample text after page break</p>
What is this? --> @normal text { footer {...} }
Some kind of media query? Do you mean something like this:
HTML:
<p class="normal-text">Sample text before page break</p>
<p class="normal-text2">Sample text after page break</p>
CSS:
p.normal-text { page-break-after: always; }
I'm asking, because I've found that it doesn't seem to be creating page breaks on my ebook, after I began using the Kobo Webkit by changing the extension to .kepub.epub
hello, i tried your code exemple to catch touchevent on my kobo aura (N514) with 4.20.14622 and kepub extension
document.querySelector("main").addEventListener('click', handleClick, false);
document.querySelector("main").addEventListener('touchstart', handleTouch, false);
function handleClick(event) {
event.preventDefault();
}
function handleTouch(event) {
exampleElement.style.background="red";
event.preventDefault();
}
}
but the main menu interact over my script.
what's wrong?
oh and alert()
don't too (for debugging).
The document lacks overall support for non Latin scripts and the idiosyncrasies of right-to-left languages. Amongst others, it lacks mention of:
spine
element's page-progression-direction
attribute, for right-to-left pagination flow.writing-mode
CSS3 property (or equivalent), for vertical left-to-right or vertical right-to-left text layouts, and related CSS3 properties such as text-combine-upright
(or equivalent)dir
attribute, and related bdi
and bdo
elements, for hardcoding base text direction irrespective of CSS styling, as well as its interactions/collisions with the Unicode Bidirectional Algorithm.Readings related to some of the above:
bdi
elementFeel free to split this issue in multiple issues if appropriate.
Simple scenario with link <a href="#foo">...</a>
to <div id="foo">...</div>
somewhere else.
Clicking on the anchor always moves my ereader to the page BEFORE the page where div#foo
is visible.
And if id
is set on <section>
or <figure>
the landing page is even more "inaccurate".
My e-reader Clara HD (latest soft).
I have an embedded font for select sections of my book, as well as one for a foreign glyph. On Kindle, the user can change the main font without affecting sections styled with an embedded font. I thought my Kobo Touch did the same thing, but now it does not. Do not know if this is a change with the updated O/S, or if my memory fails me and this was always the case. Either way, this is NOT good. Is this the case on all Kobos? Your documentation suggests it is.
Unless I’m missing something, it looks like the Storage API (sessionStorage
, localStorage
) is not enabled in the Android app, while it is in the iOS app.
As far as I can remember, it has to be set (opt-in) for Android web views while it is automatically enabled (opt-out) for iOS web views, and the method which should be used is webSettings.setDatabaseEnabled(true)
(cf. the Android Reference).
Problem is, the Storage API is quite a MUST if you have quizzes or more general stuff for which you must store and retrieve values at a later time, and this inconsistency may create compatibility issues between the 2 apps.
So it would be great to have some consistency there, the alternative being IndexedDB, which can be very slow and tricky to deal with on less capable Android devices.
Or maybe it is already and I’m missing something? But even simple tests are failing for me right now.
The renderingissues address mentioned in this document bounces.
So, when text-align is not declared in the CSS and you pick “Publisher’s default” setting in the menu, the whole text is centered (by default).
For the record, if you set text-align: left
for h1 for instance, then the whole text is left-aligned when using this setting.
Applies to Kobo iOS and Kobo Android.
Kobo has rejected several books with the error:
OEBPS/Text/notes.xhtml(10,33): Undefined property: 'endnotes'.
I don't have any further details.
They are reflowable epub3 books with numerous endnotes and they validate with epubcheck v4.2.2 and Ace by Daisy1.1.2.
The endnotes are in their own file notes.xhtml, in a
<section epub:type="endnotes" role="doc-endnotes">
and each note is also defined:
<div id="footnote-1" epub:type="endnote" role="doc-endnote">
An example is isbn 978-2-490431-03-8 title "La Famille de l’antiquaire ou la belle-mère et la bru" but I can't attach it here for copyright reasons. I previously encountered this same problem nearly a year ago. If I recall correctly, to get around the problem the last time I changed all the "endnotes" to "footnotes" so the client could get the book available for sale, and I'll do that here too but this is a hacky workaround, not a solution.
This looks a lot like the previously identified problem of validating with an outdated version of epubcheck, eg :
w3c/epubcheck#714
Do the "toc.ncx" and "nav.html" files have to be named those exact names? The documentation is not clear.
In the OPF section of the document, it says that "special characters and spaces should not be used for file names within an ePub" and "special characters are not letters or numbers."
Does this also mean that files should only be named using ASCII characters? For example, if an EPUB contains a file named "例如.xhtml", what will happen?
What about dashes or underscores, apostrophes, percent signs, ampersands, or upper ASCII (like "sømething_wèird.jpg")?
Does this also apply to directories with an EPUB? For example, the file name "example.xhtml" is fine, but what if its path is "OEBPS/folder name with spaces/example.xhtml"?
Thanks!
In the documentation the following is mentioned:
Kobo reading platforms insert max-width and max-height CSS for images and video.
Can you clarify how you do this? Is this done differently per device, or can you provide the exact CSS you add? Is this able to be overridden if desired by the creator using !important
or some other manner?
The spec says:
"[The dc:identifier] should contain the eBook ISBN, also supplied in the external metadata. However, if this field does not contain the eBook ISBN, it must be in the ePub file name."
For cases where the ISBN is provided in the filename, can you tell me which filename formats are supported? For example:
Thanks!
You might want to add section numbers (1.0, 1.1, etc.) to make it easier to refer to sections.
Not an issue but more of a general wish for consideration.
In the document is very little about annotating ("bookmarking and note keeping" in) an epub in the document. A while ago I read this document - https://web.hypothes.is/blog/epub-annotation/. And I still wonder if it weren't just great if I could use Hypothesis to map my notes and highlights on the Kobo reader to the epub in Calibre and wherever else "a connector" exists. (It hasn't to be scientific as Hypothesis suggest; maybe on Goodread too - think o f Harry Potter annotated by the masses ;)).
It has to be open (not something bound to a Kobo account or Community), but it still would be an very interesting and distinguishing feature on the e-reader market.
What’s the best way to submit rendering bugs we believe are reader system issues?
Seriously, I'm doing my utmost to debug on your desktop and Android apps but proper tools are lacking.
I know this is sounding really harsh but hey, if you don't provide us guys with simple tools which work, don't dare complain we don't QA/debug for your apps.
If I'm not mistaken, there’s no mention of navigator.epubReadingSystem
in the spec. Now, it can be useful sometimes → http://epubzone.org/news/epub-3-and-interactivity#_the_epub_3_epubreadingsystem_object
So basically, we don’t know whether it’s implemented or not if we don’t test or check http://epubtest.org/testsuite/epub3/feature/epub-reading-system/, but maybe it’s been implemented since?
OK so this is kinda weird.
Is this help page up to date? Cos’ I can’t access those settings on a Honor 5x when using the Android app.
Pinch to enlarge font-size is working though, but no reading menu nor themes in sight, either when side loading files or downloading from the store.
When referring to the support grid for SVG, fonts and other matters, epubtest.org is referred to as the place to clear any doubts that should arise. However, epubtest.org is no longer online, so any questions that should arise will remain unresolved.
A client has come back to me because a book I made has been rejected by Kobo with the error message
"OEBPS/content.opf(26,64): Undeclared prefix: 'a11y'."
The book is a valid epub3 (epubcheck 4.2.2 + Ace by Daisy 1.1.2), the same one referenced in this other report: #55 (isbn 978-2-490431-03-8 title "La Famille de l’antiquaire ou la belle-mère et la bru").
How can this be resolved?
The doc says, "TTF and OTF font types are fully supported on Kobo. Other font types are not supported as per the ePub spec." However, EPUB 3 does not support TTF as a core media type, only OTF and WOFF (http://www.idpf.org/epub/30/spec/epub30-contentdocs.html#sec-css-fonts). If you use TTF in an EPUB 3 file then you would technically need to use a fallback mechanism to a core media type (http://www.idpf.org/epub/30/spec/epub30-publications.html#confreq-resources-font-fallback). Just an interesting thing to mention, as most publishers and creators are completely unaware about it.
Per your docs, footnotes and endnotes are supported, which is great!
There is the statement Users of the eInk and iOS platforms (starting with version 7.3) see a pop-up text box containing a footnote or endnote’s text.
, but I'm not sure what "version 7.3" means. Is this eInk firmware, or iOS app version? Can this be differentiated, please? For example, I have an old Kobo Touch, software version 3.11.0. Could I expect the notes to pop up there?
What is the behavior of Kobo eReaders/apps if I were to use the epub:type
attribute, and the reader was an older version that did not support this?
With iBooks, epub:type
endnotes are not supported--only footnotes. In other words, when you use hyperlinks with the epub:type
attribute in iBooks, it will display a popover for that hyperlink, only if the target is in the same HTML file. How does Kobo's behavior compare to this?
And overall, I want to make sure that I do, in fact, understand correctly that you "support the epub:type attribute", for example, in the way given detailed in a blog post by Liz Castro. Please let me know if I misunderstood.
Finally, having this level of documentation on what Kobo supports and does not support is incredible, and a serious step up over other eBook distributors. Way to go!
According to the section headed "JavaScript Support," Kobo for Android supports JS for fixed-layout content only, while iOS supports JS for both FXL and reflowable content.
Later, the "Support Grid" section indicates JS support on the eInk and desktop platforms. Do these platforms support JS for both FXL and reflowable content, or just FXL?
Thanks!
Derek
So, that’s a tough one.
Say you have a fixed-layout file which is made entirely of images because distributor X is imposing this constraint for all fixed-layout files—it’s sad, I know, but there’s nothing I can do.
According to the spec, it will be passed to the image-based FXL reader on iOS and Android.
Now, let’s say you add audio files and javascript (custom controls for instance) in this file. The markup for this is obviously bigger than the markup for the image.
Finally, sideload this file to the iOS and Android apps and… it will be passed to the image-based FXL reader too. No audio, no controls, just images.
As far as I can tell, that’s not a criteria currently listed so could you tell me whether it’s a bug or an expected behavior?
Hi,
The chapter "Javascript support" states that
Kobo’s Android and iOS platforms support JavaScript for Fixed Layout and reflowable ePubs [...] Kobo’s eInk and Desktop platforms have limited support for JavaScript, and do not support interactive JavaScript elements
and
Note that navigator.epubReadingSystem property is only supported on Kobo's Desktop and eInk platforms and is not presently supported on iOS, Android or Windows.
Why is the navigator.epubReadingSystem not supported for iOS, Android or Windows? It's confusing as later the chapter "support Grid" states that JS is supported for Android and iOS but not for Desktop, eInk, Windows.
Furthermore, according to the EPUB3 spec :
A Reading System that supports scripting must meet the following criteria:
[...] It must implement the JavaScript navigator extension object epubReadingSystem defined in Appendix B, JavaScript epubReadingSystem Object. It also must support the dom-manipulation and layout-change features defined in Features in container-constrained scripting contexts.
Hello,
Firstly, I am not so sure if this is the right place to share my issue.
Mathml characters such as left/right angle brackets and their variants are not rendered in my eink kobo (kepub extension). I tried changing the font and issue persists. What could be the cause?
The Kobo EPUB Specifications claims that users of the eInk and iOS platforms see a pop-up text box containing a footnote or endnote’s text, but I can only get footnotes to behave as a standard hyperlinks instead.
Below is the markup that I am using. Epubcheck Version 3.0.1 validates the ebook against EPUB version 3.0 with no errors or warnings detected:
<p>This is a <a href="footnotes.xhtml#fn1" id="fnref1" epub:type="noteref" class="footnoteRef">Footnote reference</a>
<ol>
<li id="fn1" epub:type="footnote">Foonotes should purportedly appear on a popup on Kobo for iOS. <a href="index.html#fnref1" hidden="hidden">↑</a></li>
</ol>
or:
<ol>
<li><aside id="fn1" epub:type="footnote">“Please!!! Fucking hell! What the fuck WHATTHEFUCK!!!”</aside> <a href="index.html#fnref1">↑</a></li>
</ol>
It makes no difference whether the footnote reference and its footnote reside in the same document or not.
Seen in Kobo for iOS 7.2.1 on an iPhone 4 running iOS 7.1.1.
I'm currently building a script for debug tools, which is binding the console to a virtual console in the DOM. In other words, it injects every log, error, etc. into the DOM, even system’s.
While testing this in Kobo Android, got access to app’s logs (two last lines in the screenshot).
“Why reporting this” you may ask… Depends on what you're logging, obviously, but could also turn into a security issue if some critical data is “console.logged”.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.