Displaying Code on the Kindle

So, I'm in a quandary.

Having used one now for a few months, I'm slowly warming to Amazon's Kindle 2. Sure, it still feels a bit cheap compared to the Sony 505, but it's fast, and the ability to download over their wireless network is a bit plus. (Stay tuned for an announcement from us about that...)

But my biggest issue with the Kindle is the markup it supports. Think 1995 browser, minus the <blink> tag. It is very, very limited.

I pride myself on the look of our books, so when I added support for eBooks on the Kindle, I worked hard to get something that looks half-way decent. We're still tuning it, but by and large I think our books look good. But we still have an issue. It is really hard to display code listings on the device. Let me explain why, and show you some examples. Then, at the end, I'll ask for your help.

First, the problem. When the Kindle was first launched, it lacked a fixed-width font. They recently added one. But the choice of sizes is limited, and the code tends to end up too big, even at <font size="-2"> This leads directly to the main problem. The Kindle display is narrow. You can get roughly 45 fixed-width characters across it at the smallest font size. That means code lines will either be truncated, or they'll wrap.

But, we went ahead and did our best. And we didn't much like the result. In particular, I didn't like the way long lines in the code wrapped onto the next line. So I went back to the drawing board and took a new approach.

In the books as currently published, code listings on the Kindle are actually images. That means I get to choose the font, and I get to choose the size. And I can do some cleverer things than I could do with straight HTML formatting. For example, if a listing is wide, I know before hand that it won't fit the horizontal size of the screen, so I scale the font down until it does. And, because the font I'm using is narrow, I can fit more code per line anyway. But there are some major downsides of this approach.

• The code doesn't scale up and down when you change the font size on the device.

• The font we're currently using in the images doesn't have bold and italic versions, so we're not syntax highlighting it. This is clearly fixable, but it would be something of a pita to do.

• The .mobi files we generate are about three times bigger than they'd otherwise be because of the embedded images.

• If an image is too big to fit on a page vertically, we currently chop it off.

So, there's no clear winner. Just to show you what I'm talking about, here are some comparison images taken from Daniel's Cocoa book. The ones on the left are pages from the books as we currently distribute them. The ones on the right use text, rather than images, do display code. (You can click on an image to see it at full size.)

Code As Image	Code as Text

So, given the pros and cons of each approach, what should we do? Stick with the current scheme? Move to text-based code? Or...?

Comments

[Joe]

The text-based code looks good, but in the third image the line numbers and hyphens really clutter it up. I'd get rid of those to make the code look clearer.

Perhaps there is also a way to turn the text "line 10" to a link that actually brings you to, or highlights line 10, so you don't need the line numbers printed as reference.

[R. Mark Volkmann]

I vote for sticking with images. I like how if the font in the images is small, you can click the image to zoom in and rotate it to display better.

I'd also like to hear about the technical issues that are preventing you from publishing Programming Ruby in mobi format.

[Michael Houghton]

Can the Kindle display landscape text? Jumping out to a landscape page might be appropriate in some cases.

[Simon Harris]

+1 for text and landscape mode. Images always look a little blurry to me and when I'm on a hand-held device, it's the prose I'm _really_ interested in.

[Bruce Williams]

The fact code gets chopped off, to me, is a clear no-go. I'd rather have to deal with word wrapping than incomplete code... and file size is not a small concern.

I'm assuming using text would make it easier for you to modify to support future Kindle text improvements, as well.

[nightshade427]

I vote for sticking with the images approach.

[Dave Thomas]

We can't make it switch to landscape, only the user can. And we can't highlight lines dynamically.

The line numbers are there because the text references them. It's easy to take out, but I'd rather find a visual way of decluttering (I wanted to invert the colors and make a solid margin, but can't find a way to do that on the Kindle)

[John Wang]

One thing you should keep in mind also, is that the Kindle allows you to highlight Text for future reference and is also available to be downloaded online from Amazon.com. It does not allow you to highlight images for download afaik. And from what I have seen on my Kindle, it does not do OCR on the images either.

I do find the Kindle's highlight and notes feature to be extremely useful when it comes to technical books such as the Prag Prog books.

[Michael Niessner]

I like the code as text. Although, the hyphens and line numbers on the last image are too much. Enlarging images is slow (you have to scroll to the image, then click and wait, read the example, then click and wait to go back to the page you were on). Also you can't highlight/take notes of parts of the code when it's an image.

[Keith Fahlgren]

Search is the biggest reason we try to avoid images in Mobi files. The thought is that the reader has paid to have a portable and searchable version of the text, rather than getting the dead tree version. Removing some of the most interesting content from the search index seems like a big loss.

You already offer PDF & ePub versions that can represent the code decently (though Adobe's Digital Editions ePub renderer has its own flaws when rendering code) if folks actually need to sort something out, so I'd argue that you should ditch the images in the Kindle.

[Matthew Williams]

I like the images as if I really need to, I can select the image and blow it up and view it in landscape mode.

[AgentMunroe]

How feasible would it be to have two different versions - one with the code font and one with the images?

If it's a significant amount of work I don't think I'd worry about it - I already appreciate getting all eBook editions for one price - but that way people could pick and choose.

Personally, I sort of prefer the code font, and actually don't think the wrapping is completely awful. (Same way it would look in TextMate/Xcode/etc.) Also, missing out on search/highlighting/etc. seems borderline criminal to me... but what do I know; I don't even have a Kindle yet. :-)

[Robert Hahn]

two ideas:

* use images inline with context, but link them to an appendix containing text versions (to enable searchability), with links back to the images so people can see what the context was.
* maybe talk to Amazon and explain the problem? Perhaps they'll update their software to serve you better...

[BushyMark]

Having read several of the PragProg books on the kindle now, I haven't had to search for the text all that much. I am much more of a fan of the images . . . when I want to dive in further, I just zoom the image . . . so + 1 for images from me.

Also, the messed up line breaks would just confuse the heck out of me . . .

I think Robert Hahn's idea is really creative though:
* use images inline with context, but link them to an appendix containing text versions (to enable searchability), with links back to the images so people can see what the context was.

Although I don't know how technically feasable this is.

Also I second R. Mark Volkmann ... what kind of technical difficulties are you running into with Programming Ruby 1.9? I SO love reading my PragProg books on my kindle now since you introduced it, and know you have been unable to bring this book to the kindle for technical reasons . . . is there something the community could do to help with it? (*Volunteering to help!*)

[Ryan Briones]

I noticed code text wrapping the other day while reading "Cocoa Programming for Mac OS X". It wasn't a fixed width font either. It REALLY bothered me and I was wondering at the same time "I wonder how the prag books are on this..."

I think I like the image approach and if something like Robert Hahn's suggestion is possible, then that would be a great compromise.

[Dave Thomas]

The problem with turning the PickAxe into an eBook is one of technologies used. Our other books are authored in our own markup system, and they're amenable to a systematic conversion process. The PickAxe predates these books, and is written using a very involved toolchain based on TeX. It makes significant use of TeX magic, and converting the 960 pages into the xml needed to create the eBooks would be a horrendous job.

[Carl Brown]

Line wrapping in code makes it almost not worth trying to figure out, as far as I'm concerned. I have had good luck with the code listings of the PragProg books I have on my Kindle at the moment, and haven't missed being able to search code so far.

The .mobi file sizes aren't a problem, for me either - PragProg books make up 21 of the 98 books I have on my Kindle 2 (including a converted PDF of the 1.9 Pick Axe), and I still have 1.2 Gig free.

So I'd say stick with the images (although I would like them rendered with syntax highlighting, when it becomes feasible).

[Philippe Monnet]

My opinion is that since a) text is searchable, b) the text version still looks ok, and c) Amazon will most likely improve the rendering over time, I would proceed with using text. How about using the Topaz embeddable fonts?

[Ian Farbrother]

Have you considered trying a non-fixed-width font for code? I know it's an extremely venerable tradition, but with tabs for indents instead of spaces I suspect it could be made to work.

[Geoff Lanotte]

I second, third or whatever the image approach. I know that text wrapping doesn't bother some, but I find it a bit more involved to read than I generally prefer. The only pro I can see to a text based approach is the for searching and that is somewhat moot on the kindle.

[Jason]

I'm with Ian. You don't need a fixed-width font for the text, only for the spaces at the front. How about setting the indent-important whitespace as fixed-width and letting the rest be a well-supported font?

[Dave Thomas]

The problem with using a non-fixed width font is that the Kindle only has its serif font and a fixed font: if I could use a decent sans, I'd jump at it.

The sad thing is that it's relatively easy to hack a Kindle and substitute your own fonts. I wish Amazon gave us this option officially, so then we could recommend switching to a narrower font for code.

[Nathan Youngman]

The line numbers and hyphens definitely confuse things in the text version.... what's code and what's not? Rather than trying to find a way to make a hard margin, could you use a little arrow on just the wrapped lines? Another thing to try, would be to indent the wrapped lines the same amount of space as the line above, plus 1 or 2 spaces. At least when doing so will fit without breaking the word. That may mean more vertical lines, but the structure of the code would be more clear.

If none of that works, the images seem like a very good compromise until Amazon gives better font support.

Btw, thanks very much for pursuing .epub and .mobi support.

[Mike Doel]

Hmmm - maybe this is gonna help:

http://www.engadget.com/2009/05/03/nyt-big-screen-kindle-coming-from-amazon-this-week/

[Jocke Selin]

I have deja-vu's from 1995 again. Company logos and headers rendered as images. This is horrible, horrible horrible. Which ever way you dress it up, it's a cludge.
I won't buy an e-reader until issues like these are solved, but when they are solved, I will cling to my e-reader for all those searchable and indexable pieces of code I now have scattered over several several meters of paperbooks.
You need to address this issue with Amazon and the Kindle. This is something that should NOT turn an author into a developer (i.e you shouldn't start fixing Amazon's Kindle issues, but focus on the book).
Many books rely heavily on the typography to be the exact book it is. An e-book should be no less than this.
In short; Please don't provide Amazon with custom-built-book that has got no shelf-life. Tell them to fix their problems, and write the book as it's intended to write. This surely is a mere firmware issue on the Kindle.