PragDave

Technical eBooks part II

In the previous post I mentioned the epub format in passing, saying it also had issues. However, I didn't bother to qualify that, nor did I give an epub sample.

When I went back to create the sample, I discovered that the 1.5 release of Adobe Digital Editions no longer worked with the epubs generated by our toolchain (and, by no longer worked, I mean looped-burning-up-CPU-until-crashing no longer worked—DE is a remarkably fragile piece of software.)

Anyway, I fixed that up (and, in the process, discovered that while id="fig:one" should be perfectly valid xhtml, epubcheck and DE both say not. Sigh).

So, here's the complete list of the versions of that sample chapter.

• In PDF format.
• In a rough-and-ready HTML format
• In .mobi format (which is suitable for the Kindle—just copy it to your Kindle's documents folder). You'll want to right-click and "Save As" to download this link.
• In .epub format (which I've only tested in DE). Again, you'll want to right-click and "Save As" to download this link.

epub is clearly better than mobi for formatting, but still has issues. But, I thought I'd post them all here for comparison purposes.

Help us decide: are eBooks ready for technical content?

About once a week, we get a request from a reader to have our books available in a format that can be read on an eBook reader (typically, nowadays, the Amazon Kindle).

In fact, we've had a prototype form of that capability for a while now, but we've always held back. Frankly, we didn't think the devices worked well with our kind of content. Basically, the .mobi format used by the Kindle is optimized for books that contain just galleys of text with the occasional heading. Throw in tables, monospaced code listings, sidebars and the like, and things start to get messy. The .epub format (used, for example, by Adobe Digital Editions) is slightly more capable, but it also has issues.

Last week, I reopened the can of worms and tried a quick hack. Rather than render code as text, I now create individual graphics files for each code listing, and embed those in the file eBook. The result is a lot better, but still has some drawbacks:

• the code doesn't scale when you scale the font size of the body text
• the code gets chopped off a the right margin
• code listings can't be longer than a page
• the fonts are not as readable as they would have been as text, as we don't get the pixel-level control you get with native fonts.

However. even if the display code problem is (kinda) fixed, we still can't have code fonts (or any other font) inside paragraphs. And we have issues with sidebars and tables.

So, here's the question. Given all these limitations, should we go ahead and publish eBook formats alongside our PDF formats? (If we did, a single purchase would get you access to all formats.) To help you decide, here's an (unedited) chapter from Stripes: ...and Java web development is fun again:

• In PDF format.
• In a rough-and-ready HTML format
• In .mobi format (which is suitable for the Kindle—just copy it to your Kindle's documents folder). You'll want to right-click and "Save As" to download this link.

If you don't have access to a Kindle, I put some screenshots down below. The last 3 show what code listings look like.

So... what do you think. Is this workable? Should we make these available, even though they're not very good, or should we wait for a later generation of eBook that's closer to the capabilities we need? Comments are open... :)

Cheers

Dave

---

Sample Kindle pages—click each for a full size version.

If you work for Apple, we need your help...

So, it's been a week. The iPhone 3G was released, and the iPhone 2.0 software upgrade shipped. We can now all write applications that will run on what is undeniably a cool platform. You can even download the iPhone SDK for free.

We love Apple stuff. Andy and I both run Macs as our main machines (at last count, I have 8 Macs in my home). When the App Store was announced, we were keen to spread the word. We have a new book on iPhone software development. We have a brand new section in Bill Dudney's Core Animation book. And Mike Clark has a set of screencasts on how to write code for the little fella.

And we can't show you any of them.

Why? Because in order to get the iPhone SDK, you have to agree to the terms and conditions—you know, that standard box of legalese that you skip over before pressing I AGREE. Except, in this case, the legalese has some unfortunate consequences. For example, it says:

3. Confidentiality. As a Registered iPhone Developer, you may be receiving information from Apple. You agree that all information disclosed by Apple to you that relates to Apple's products, designs, business plans, business opportunities, finances, research, development, know-how, personnel, or third-party confidential information, will be considered and referred to collectively as "Confidential Information." ..... You agree not to disclose, publish, or disseminate any Confidential Information to anyone other than to other Registered iPhone Developers who are employees and contractors working for the same entity as you and then only to the extent that Apple does not otherwise prohibit such disclosure in this Agreement. Except for your authorized purposes as a Registered iPhone Developer, you agree not to use Confidential Information in any way, including, without limitation, for your own or any third party's benefit without the prior written approval of an authorized representative of Apple in each instance.

Then, later on, it says

10. Use Of Apple Trademarks, Logos, etc. You agree to follow Apple's Guidelines For Using Apple Trademarks and Copyrights as published on Apple's website at www.apple.com/legal/guidelinesfor3rdparties.html and as may be modified from time to time. You agree not to use the marks "Apple," the Apple Logo, "iPhone," "iPod touch" or any other marks belonging or licensed to Apple in any way except as expressly authorized in writing by Apple in each instance.

So, to write a book about the iPhone SDK, you have to download it. In order to download it, you have to accept the agreement. And the agreement says that the download will contain confidential information that you can't pass on to third parties. That makes it hard to publish the book. And, if that wasn't enough, it also appears that you can't even use the word "iPhone" (for example, in a book title).

We'd hoped these restrictions would be lifted at the announcement of the 3G. They weren't. We'd hoped they'd be lifted when the 2.0 software shipped last week. They weren't. We'd heard rumors they'd be lifted on July 14th. They weren't. And, what's worse, we can't pin down anyone who'll tell us just what is going on.

We're not the only people in this particular boat. Manning, for example, has an iPhone development book. They've published the part on doing web-based iPhone development (using the iPhone as a browser), but they're having to hold back the SDK-related material.

So, here's where you can help. If you work for Apple, and have any ideas on who we can contact to find out what's going on, we'd really appreciate knowing. We'll keep your personal information confidential. Just drop me an e-mail at dave@pragprog.com.

Thanks

Dave