Amazon Kindle Publishing Guidelines version 2013.1 Questions

[yaelkmiller]

Amazon has recently released an update to their "Amazon Kindle Publishing Guidelines" -- version 2013.1 (can be downloaded here) They have not, however, released new samples that reflect their new guidelines. (Old samples still here.)

In the new guidelines they changed how they want the embedded cover done in the OPF file (3.2). In the middle of giving two methods, they say the below:

This syntax is part of IDPF 3.0 standard and described at http://idpf.org/epub/30/spec/epub30-...roperty-values.

So I'm guessing this means that package info and dc-metadata are changed in the OPF from the previous (see below):

<package unique-identifier="uid" xmlns:opf="http://www.idpf.org/2007/opf" xmlns:asd="http://www.idpf.org/asdfaf">
	<metadata>
		<dc-metadata  xmlns:dc="http://purl.org/metadata/dublin_core" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/">

Is my guess correct?

Does 3.2.2 and 3.2.3 mean that the below is eliminated from the OPF?

<x-metadata>
			<EmbeddedCover>images/cover.jpg</EmbeddedCover>
			</x-metadata>

Does anyone have a sample of an OPF file according to Amazon's new guidelines?

I also have questions about the updated TOC.

What is a "logical TOC"?

In 3.3.1.2, it says the below:

NCX is part of the IDPF 2.0 specification and is described at http://www.niso.org/workrooms/daisy/...-2005.html#NCX

I'm guessing that doctype info, etc. has changed. Does anyone have a sample of an toc.ncx file according to Amazon's new guidelines?

I don't understand 3.4 "landmarks nav Elements Guidelines" at all. What are they for? Do you have to use them?

[DiapDealer]

Looks like a lot of transitioning towards ePub 3 while leaving the existing ePub 2 features in place for maximum backward compatibility.

You don't have to change the way you do covers, the old way will work fine (method 2). Method 1 is based on an ePub3 OPF file.

What is a "logical TOC"?

That's the NCX file in ePub2. Nothing has changed there as far as I can see. And an EPUB Navigation Document in ePub 3. The Navigation Document has the advantage of being a Logical ToC and an HTML ToC all in one.

I don't understand 3.4 "landmarks nav Elements Guidelines" at all. What are they for? Do you have to use them?

Landmark nav elements (ePub 3) are similar to the guide items in an ePub 2 NCX file.

It looks to me like Kindlegen v2.8 is accepting ePub3 as input (or at least XHTML with an ePub 3 OPF), but you're obviously not required to do so.

[yaelkmiller]

Would you recommend sticking with the ePub 2 features or switching to ePub3? (I don't currently output an epub since I only publish on the Kindle.)

the old way will work fine (method 2)

Actually, the old way -- being what's in the KF8 sample files -- isn't the same as Method 2. But it's closer to Method 2 than Method 1.

The Navigation Document has the advantage of being a Logical ToC and an HTML ToC all in one.

Does that mean I no longer have to create a toc.html file and can just create a toc.ncx file?

What do the declarations of the Navigation Document look like? The stuff before the below:

<nav epub:type="toc">
<ol>
<li><a href=”Sway_body.html#preface_1">AUTHOR'S NOTE</a></li>

Do you have any samples of the files with ePub3 features?

[DiapDealer]

I'll be honest... from my preliminary (and very cursory) experimentation, the only real difference here is that kindlegen (and KindlePreviewer) v2.8 is accepting ePub3 as input. But it doesn't really appear to be creating KF8 files that are significantly different than what the previous versions of Kindlegen created. I've not really tested any of the multi-media stuff (so take what follows with a grain of salt), but there doesn't seem to be any real inherent advantage to starting with an ePub3 document over ePub2 if you're not ready to make that particular leap with your text-based ebooks.

The only thing that may be an advantage to some is that with ePub3, you don't have to mess with creating an NCX if you don't want to. Kindlegen will automatically create an NCX from the Navigation Document.

Here's a small sample of an ePub(3) document that KindlePreviewer doesn't bat an eye at. It's nothing fancy, but it shows an example of the Nav document and an ePub3 OPF file if you're interested. Just don't open the epub in Sigil though, or it won't likely stay an ePub3 ebook.

EDIT: The method 2 for cover images matches exactly what's been in previous editions of the Guidelines, so far as I can tell. The name values may have changed, but it's the same thing: a meta tag with the reserved "cover" name and then a manifested item using the meta tag's "content" property for that item's "id." Same-same.

[yaelkmiller]

the only real difference here is that kindlegen (and KindlePreviewer) v2.8 is accepting ePub3 as input. [...] but there doesn't seem to be any real inherent advantage to starting with an ePub3 document over ePub2 if you're not ready to make that particular leap with your text-based ebooks.

Thanks for clarifying. Your explanation is probably right. (Amazon, as usual, isn't explaining itself.)

The only thing that may be an advantage to some is that with ePub3, you don't have to mess with creating an NCX if you don't want to. Kindlegen will automatically create an NCX from the Navigation Document.

Interesting, I'll have to test this out.

It's nothing fancy, but it shows an example of the Nav document and an ePub3 OPF file if you're interested.

Thanks for sharing. What software can I use to open it with to see the Nav document and OPF file?

[DiapDealer]

Originally Posted by yaelkmiller

Thanks for sharing. What software can I use to open it with to see the Nav document and OPF file?

I don't really know of any ePub3 editors, so I'd say just change the extension to .zip, unzip it and use any text/code editor to view those files.

[JSWolf]

There is an advantage of not going with ePub 3 and sticking to ePub 2. That is that if you ever decided to publish your eBooks elsewhere besides Amazon, you would be all set with the ePub 2 instead of having to modify your ePub 3 to be ePub 2.

[yaelkmiller]

Originally Posted by DiapDealer

I'd say just change the extension to .zip, unzip it and use any text/code editor to view those files.

That worked. Thanks again.

[yaelkmiller]

Originally Posted by JSWolf

if you ever decided to publish your eBooks elsewhere besides Amazon, you would be all set with the ePub 2 instead of having to modify your ePub 3 to be ePub 2.

So other platforms don't use ePub 3?

[dgatwood]

Originally Posted by yaelkmiller

So other platforms don't use ePub 3?

Ostensibly yes, in much the same way that lots of web browsers support CSS3 and HTML5....

In other words, you can do it, but the problem with living on the bleeding edge is that you tend to bleed a lot.

[AlPe]

Hi,

I would like to share a piece of information that might help those who are producing EPUB 3 eBooks and might want to take "advantage" of kindlegen 2.8 to create MOBI/KF8 files from them.

Short
If you want to convert an EPUB 3 file using kindlegen, in the nav landmarks of your navigation document you MUST specify ONLY one element with epub:type "toc", "cover" and "bodymatter". If you specify other elements (e.g., an item with epub:type "frontmatter"), kindlegen 2.8 FAILS to create the cover/TOC/beginning shortcuts in the output MOBI/KF8 file. If you want to keep those extra bits, you are forced to revert to kindlegen 2.7.

Long
I have a perfectly legal EPUB 3 file with the navigation document both as XHTML (toc.xhtml) and NCX (toc.ncx, for backward compatibility).

The former contains the following landmarks:

        <nav class="indice" epub:type="landmarks">
            <h1 class="indice">Scelte rapide</h1>
            <ol class="indice">
                <li class="indice"><a class="indice" epub:type="cover" href="copertina.xhtml">Copertina</a></li>
                <li class="indice"><a class="indice" epub:type="frontmatter colophon" href="colophon.xhtml">Colophon</a></li>
                <li class="indice"><a class="indice" epub:type="toc" href="indice.xhtml">Indice</a></li>
                <li class="indice"><a class="indice" epub:type="frontmatter foreword" href="presentazione.xhtml">Presentazione</a></li>
                <li class="indice"><a class="indice" epub:type="frontmatter" href="p001.xhtml">Inizio del romanzo</a></li>
            </ol>
        </nav>

Now, I want the "opening point" of the eBook to be the last element, p001.xhtml.

Tried to convert the EPUB 3 file with the above code with kindlegen 2.8, and it issues the following warning:

Warning(prcgen):W14023: Failed to add the guide item to the book :  frontmatter

and, more importantly, it does not create the cover/TOC/beginning shortcuts (without outputting the corresponding warning), even if the OPF file has:

<guide>
    <reference type="cover" title="Copertina" href="Text/copertina.xhtml" />
    <reference type="toc" title="Indice" href="Text/indice.xhtml" />
    <reference type="text" title="Inizio" href="Text/presentazione.xhtml" />
</guide>

To "fix" the problem, one has to revert to kindlegen 2.7 (as I did) or "remove" the unrecognized elements from the nav landmarks:

        <nav class="indice" epub:type="landmarks">
            <h1 class="indice">Scelte rapide</h1>
            <ol class="indice">
                <li class="indice"><a class="indice" epub:type="cover" href="copertina.xhtml">Copertina</a></li>
                <li class="indice"><a class="indice" epub:type="toc" href="indice.xhtml">Indice</a></li>
                <li class="indice"><a class="indice" epub:type="frontmatter" href="p001.xhtml">Inizio del romanzo</a></li>
            </ol>
        </nav>

We are good, right? Uhm, no, because the Kindle Publishing Guidelines do not mention the fact that the ONLY recognized epub:type's are "toc", "cover" and "bodymatter". Hence, I am also forced to change (inconsistently with the semantics) the epub:type of the last item to "bodymatter".

        <nav class="indice" epub:type="landmarks">
            <h1 class="indice">Scelte rapide</h1>
            <ol class="indice">
                <li class="indice"><a class="indice" epub:type="cover" href="copertina.xhtml">Copertina</a></li>
                <li class="indice"><a class="indice" epub:type="toc" href="indice.xhtml">Indice</a></li>
                <li class="indice"><a class="indice" epub:type="bodymatter" href="p001.xhtml">Inizio del romanzo</a></li>
            </ol>
        </nav>

Now, of course, kindlegen succeeds in creating the MOBI/KF8 with cover/TOC/beginning shortcuts.


Summary
From the discussion above, it seems to me that:
1) if nav landmarks are present, the <guide> is ignored;
2) there is a bug in kindlegen 2.8, because if it cannot parse a nav landmark element, it fails to create the cover/TOC/begininning shortcuts;
3) the Kindle Publishing Guidelines do not state explicitly that the only recognized epub:type's are "cover", "toc", and "bodymatter";
4) in any case, Amazon forces you to open your book at "bodymatter", even if you want to open your book at (say) "preface" or "introduction" or whatever --- In other words, IMHO, they restrict the option for "opening point" to "beginning of text", which is not very desirable.

[DiapDealer]

I actually thought #3 was fairly clear according to the guidelines, myself. Both sections 3.4.1 and 3.5.1 state that anything other than Cover, Beginning, and TOC is not recommended... whether using nav landmarks or guide items.

[AlPe]

Alright, let's read 3.4.1 together:

The Kindle platform supports landmarks nav elements for defining the cover, table of contents (TOC), and start reading location (”Go to Beginning”). Do not set the start reading location to a blank page.

Was it so difficult to write instead:

The Kindle platform supports landmarks nav elements for defining the cover (epub:type="cover"), table of contents (TOC) (epub:type="toc"), and start reading location (”Go to Beginning”) (epub:type="bodymatter"). Do not set the start reading location to a blank page.

?
Please observe that "start reading location (”Go to Beginning”)" does not mean anything w.r.t. EPUB 3 specs.

Amazon does not recommend adding additional landmarks nav elements to the OPF file, because they will be grayed out in the menu options and may cause customer confusion.

Alright, but I am not expecting kindlegen to break down if I specify other elements in the landmarks, especially without warning about the failure of creating the shortcuts (#2)...

EDIT: BTW, I have just sent an email to Amazon KPTools, reporting this issue. Just to say that I am not complaining for the sake of complaining, but I just would like to work better, without second-guessing things that should be written black-on-white in the official documentation.

[JSWolf]

Originally Posted by yaelkmiller

So other platforms don't use ePub 3?

Most platforms use ePub 2.

[DiapDealer]

Originally Posted by AlPe

Alright, but I am not expecting kindlegen to break down if I specify other elements in the landmarks, especially without warning about the failure of creating the shortcuts

Fair enough. But at the same time, there's always been special considerations/concessions to be made for ePubs being used to build kindlebooks. So it's not surprising at all to me that there will be some things you can do in ePub3 that won't be supported by their conversion process (that are rarely documented). Surely when you run into issues, it's not hard to figure out that the first places to look are wherever you might be outside the recommendations. Like it or not, there's always going to be a difference between ePub, and "ePub designed to play nice with Kindlegen." It won't be any different with ePub3 than it was with ePub2.

Still, I suspect there'll be an update that fixes the situation where ALL landmarks are ignored when the doc contains unsupported types.