KindleGen and XHTML/CSS2

[pdurrant]

It's possible to generate a Kindle format book by pointing the KindleGen application at an expanded ePub.

But working out how the XHTML/CSS2 in the ePub is going to be handled by KindleGen is a lot trickier.

I'm doing some experiments in an attempt to find a way to generate a good looking ePub and Kindle from the same source files. This will require some limits on the use of ePub features, but for plain text books, this shouldn't really cause a problem.

I'll be documenting what I find in here, along with uploads of my test ePubs and Kindle books.

I welcome any comments on the test ebooks, or suggested work-arounds.

[Slava]

I've tried to convert couple of ePub files without expanding them first. One was success, another one was missing "content" file and KindleGen failed to convert it.

[pdurrant]

The first thing I wanted to test was first line text indents of paragraphs.

In CSS this is controlled by the text-indent: attribute. Values can be specified as a length (pixels, points, cm, inches, ems) or a percentage (of the available width).

KindleGen preserves percentages and ems, rounded to the nearest whole number, and converts all other measurements to pixels, counting 96 pixels per inch.

Since only ems scale with the font size, it seems that it will almost always be best to specify the text indent in ems. Unfortunately, we can only have a whole number of ems, so we don't have a lot of choice in indent size. Also, since the Kindle 1 displays ems as bigger than on the Kindle 2 (I'm reliably informed), it seems that a text indent of 1em may always the best choice.

I also looked at hanging indents. Using a left margin of 1em and a text-indent of -1em doesn't work with Kindlegen. It generates a blockquote inside a paragraph with a negative textindent (width), and that just gets rendered as a blockquote.
But if we instead specify a left padding of 1em, Kindlegen ignores this, and we get the result we want both on the kindle and in the ePub.

FONT="Monospace"]text-indent:[/FONT]
Use a whole number of ems. For hanging indents, specify the same magnitude of ems for padding-left as for the negative text-indent:

Well, this works really well on the Kindle, and on the Kindle Previewer. Hanging Indents don't seem to work at all on Kindle for Mac. Sigh...

Next: margin-left: and how to indent whole paragraphs and still allow text-indent to work correctly. (Always assuming I can work it out!)

[tomsem]

Originally Posted by pdurrant

Well, this works really well on the Kindle, and on the Kindle Previewer. Hanging Indents don't seem to work at all on Kindle for Mac. Sigh...

Next: margin-left: and how to indent whole paragraphs and still allow text-indent to work correctly. (Always assuming I can work it out!)

I'd recommend Joshua Talent's "Kindle Formatting" book. It predates Kindlegen, but the formatting advice has not changed (mobi format hasn't changed). Might save you some frustration, and he's been responsive when I've asked questions of him directly.

As for Kindle for Mac issue, that seems like a bug. Make sure you report it to Amazon, I wouldn't try to work around it.

Originally Posted by pdurrant

Since only ems scale with the font size, it seems that it will almost always be best to specify the text indent in ems.

I've found that using em to indent paragraphs with different font sizes is no good. For example, I like to use blockquotes for long quotations and use a smaller font size so that it stands out. I also like to use smaller font sizes for footnotes. In this case the indents would not align between the two paragraphs, especially if whole numbers are all that is allowed for ems. You have to use pixels in that case.

Does KindleGen allow non whole numbers for font size em specifications? For example, font-size: 1.2em; .

[ATDrake]

Kindlegen's basically a modified mobigen, so you'll probably want a look at the old Mobipocket developer site's docs on the format. One thing that you can apparently use in the Mobipocket reader that the Kindle doesn't do at all is border styling for anything.

Also, Amazon's DTP site has some stuff on formatting in its Knowledge Base. It's not much, but might be of some help.

Here's their tiny page on CSS in particular and the Formatting Guide in general. And the Desktop Publishing Guidelines (3 meg PDF) which has a little bit on specifying font-sizes/text-indents/margins via CSS, along with the admission that CSS is basically not supported very much, or all that well.

Also, beware of the new Kindlegen 1.1 build 99, or whatever they're calling the latest. It's apparently supposed to have some fixes and feature enhancements, which as far as I can tell consist solely of removing the hidden -donotaddsource feature so that all the output is doomed to bloat.

And they still haven't visibly fixed the NCX thing where it looks like nested navpoints don't show up on the Kindle (although one can apparently get to them by navigating to any given navpoint at that level, and then flicking between them, but they're otherwise invisible and inaccessible until you stumble across one of them to begin with).

[pdurrant]

Thanks all. I have Joshua Talent's book and it has some good ideas, but isn't explicit enough for me, especially on what works when specifying styles in CSS and (obviously) using KindleGen.

I have indeed read all though the old and new documentation from Mobipocket and Amazon. But I don't want to have my books in Mobipocket-specific 'HTML'. I want to get my source files in proper XJTML that produces valid ePubs with roughly speaking the same formatting as an ePub that we get through using KindleGen on it - thus the use of a padding-left (which KindleGen ignores) with the negative text-indent.


As for fractional em values - no, KindleGen rounds fractional values to the nearest em.

And as for smaller font sizes - this is a personal choice. I think that having the indents scale with the displayed text size is more important than having the indent the same size for all paragraphs on a page. And I'm told (but haven't confirmed) that on Kindle the em is based of the base font size, not the particular font size of the paragraph.

[pdurrant]

My investigations of text indents shows that Amazon haven't been at all consistent in their implementation of their own standard.

Negative text-indent attributes don't work properly on Kindle for PC. blockquote indent on Kindle for PC and Kindle for Mac is half that on the Kindle 2.

All in all, I'm very disappointed in Amazon. With such a comparatively simple format you'd have thought they could at least have a consistent rendering of it.

Sigh... I think I shall work on getting things right on the Kindle 2, and hope they'll also be right on the Kindle 3. I'm not going to worry about Kindle 1 (where the blockquote has even more left indent than on the Kindle 2, or so I'm told).

[pdurrant]

OK, the Kindle for Mac and Kindle for PC renderers completely fail with negative widths, even though they should work according to the latest Kindle documentation.

So, ignoring that problem, in the hopes that Amazon will eventually fix it, I'm only left with the problem of getting the same results on an actual Kindle as in an ePub from the same source.

And here it is. First line indents, hanging indents, left indents, and all combinations.

The trick is NOT to use margin-left, which causes Kindlegen to insert blockquotes, as blockquotes on Kindle2 automatically have 2em left indent. And also, they are rather fragile on Kindle - you have to wrap each paragraph in block quotes, not a whole range.

So what to use instead? We use the text-indent. We can specify this in whole multiples of em. To have a paragraph indented by two em with a 1em text indent, we specify a text-indent of -2em, and then add 12 non-breaking spaces to the start of the paragraph. It might be even better to add two emspaces and four non-breaking spaces, which should make a better match to the 3em we need. em-spaces work well on Kindle2, but are not in the recommended character for Kindle ebooks, due to problems with word identification. (The only spaces we're allowed are space, non-breaking space and zer-width non-joining characater.)

And by using padding-left appropriately in our CSS (which KindleGen ignores) we can get the ePub generated from this soure looking identical to the Kindle ebook.

I attach a sample showing various left indents and first line indents.

[pdurrant]

Originally Posted by pdurrant

TSo what to use instead? We use the text-indent. We can specify this in whole multiples of em. To have a paragraph indented by two em with a 1em text indent, we specify a text-indent of -2em, and then add 12 non-breaking spaces to the start of the paragraph.

Ah, I’ve found a problem. It was mentioned elsewhere, but having double-checked I can confirm that when using the em unit in specifying the text-indent, the indent used is independent on Kindle from the font size of the paragraph.

The em-unit /does/ scale depending on the base font size chosen in the Kindle user interface. I now need to check whether that's also the case when it's specified in points or pixels - does the indent get bigger if a bigger base font is chosen? I suspect not, but I have to check.

This does introduce some problems for the paragraph left indent procedure so far suggested - it only really works for text at the base font size.

Sigh... This is really rather complex, and no proper specifications from Amazon.

[pdurrant]

Originally Posted by pdurrant

The em-unit /does/ scale depending on the base font size chosen in the Kindle user interface. I now need to check whether that's also the case when it's specified in points or pixels - does the indent get bigger if a bigger base font is chosen? I suspect not, but I have to check.

My suspicions were right. If the text-indent is specified in ems, it changes as the user selects different base font sizes on the Kindle, but if it's specified in points, it does not change when the user changes base font size.

So I think I'm right in wanting to specify the text-indent using ems rather than points or pixels.

The question now is how best to introduce a space at the start of the paragraph equivalent to a specified number of ems. I suspect it might have to be a bit of trial and error. For default size text, four non-breaking spaces per em seems about right.

Now to try to put some of these ideas into practice. I'm going to see how much I can improve some of the formatting in my version of Kidnapped, which features several quotes, notes and letters that need to be indented in a variety of ways.

[pdurrant]

Originally Posted by pdurrant

Now to try to put some of these ideas into practice. I'm going to see how much I can improve some of the formatting in my version of Kidnapped, which features several quotes, notes and letters that need to be indented in a variety of ways.

Well, I quickly found that I needed to know more. to do things properly.

So I thought I'd take a look at font sizes. What a mess!

Kindle's default font size is CSS's small font size, while ADE and other ePub renderers mostly take the default font size to be medium.

This means it's impossible to specify absolute font size in a span and get the same result on Kindle and ePub,

Worse, even specifying relative font sizes, by percentage or (in Kindle HTML) -3..+3 doesn't really generate relative sizes on Kindle - only relative to the base font size chosen by the user, not the current font size.

Ugh.... I'm still looking for some way of specifying font sizes that wrks the same for both Kindle and ePub that isn't just including lots of <big> and <small> tags directly in the XHTML.

[ATDrake]

I hope I'm not being discouraging by saying this, but it's starting to look like one would be better off creating separate CSS and OPF files for one's books, depending on what output format one intends to produce for them.

Documenting a lowest common denominator for Kindle and ePub XHTML/CSS support and trying to find some universal formatting points that people could rely upon is a great idea, but it's kind of kneecapped by the fact that in Kindlegen's case, the low appears to be *really* low.

That said, your experiments make for interesting and informative reading, so best of luck with it.

Edit: Just curious if you've tried it - do the "larger"/"smaller" keywords in CSS work at all, or just in the same broken way that the other stuff does? Because the W3C specs say it's supposed to +1/-1 the current font size as set by the user, though if Kindlegen's already ignoring relative font size tricks, it'll probably ignore that, too, assuming it's part of the subset of CSS it seems to understand.

[pdurrant]

Originally Posted by ATDrake

I hope I'm not being discouraging by saying this, but it's starting to look like one would be better off creating separate CSS and OPF files for one's books, depending on what output format one intends to produce for them.

It depends on how much formatting needs to be in the book, and how much you want it to match from Kindle to ePub. I have three books out there now compiled from the same source. I'm just trying to make it work better.

But you're right, the Kindle is a low base. Mind you, smallcaps isn't properly supported in ADE either.

But I am beginning to suspect that separate CSS files for Kindle and ePub might be necessary. I hope not, but the font size issue might be a sticking point.

[pdurrant]

Originally Posted by pdurrant

But I am beginning to suspect that separate CSS files for Kindle and ePub might be necessary. I hope not, but the font size issue might be a sticking point.

Here's my sample files for font sizes. I found out a lot of interesting info, but the final conclusion is that specifying font sizes can't be done through CS and still get a consistent result between Kindle and ePub. The only consistent font size option is to use <big> and <small> tag directly in the XHTML. Otherwise, separate CSS files are going to be needed for Kindle and ePub.

I'm going to have a bit more of a think about this. It may be that separate CSS files really is the best way forward.