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

Two New Metaprogramming Episodes

I'm about to head off for a couple of weeks vacation, but I didn't want to leave folks waiting for new episodes in the Ruby Object Model and Metaprogramming screencast series, so Mike and I decided to release this week's and next week's episodes together.

Episode 4 looks at instance_ and class_eval, and lays the foundation for a whole bunch of metaprogramming to come. Episode 5 is probably my favorite so far (although I'm rather partial to the Public Service Announcement in #2). In #5, we take a fairly simply programming task and code it up nine different ways, using all of the metaprogramming techniques we've learned to date. It's pretty much pure coding for 36 minutes.

People asked for chapter markers, so we now have chapters in this series. People asked for Ogg support, so we've now got experimental Theora Ogg versions available alongside the Quicktime and iPhone/iPod formats.

I'm really liking this series—it's fun researching it, and fun learning the ins and outs of producing it.

Enjoy!

Dave

Silly Ruby 1.9 trivia

  first, *, last = 1,2,3,4,5
  first  # => 1
  last   # => 5

Screencasting Ruby Metaprogramming

I've been teaching Ruby (and in particularly, metaprogramming Ruby) for almost 7 years now. And, in that time, I've gradually found ways of cutting through all the confusing stuff to the actual essentials. And when you do that, suddenly things get a lot simpler. I've always know that Ruby didn't really have class methods and singleton methods, for example, but until recently I didn't have a simple way to explain that.

Then, when preparing to give an Advanced Ruby Studio, my thinking crystalized. Metaprogramming in Ruby becomes simple to explain if you focus on four things:

• Objects, not classes.
• There is only one kind of method call in Ruby. The "right-then-up" rule covers everything.
• Understanding that self can only be changed by a method call with a receiver or by a class or module definition makes it easy to keep track of what's going on when metaprogramming.
• Knowing that Ruby keeps an internal concept of “the current class” which is where def defines its methods. Knowing what changes this makes it easier to know what's going on.

I tried this approach in a number of Studios, and refined it during some talks for RubyFools in Copenhagen and Oslo.

So Mike Clark, who's producing our new series of screencasts, started pushing me to put this description into video. Last week I finally cleared the decks enough to record the first three episodes.

First, I have to say it was a blast. I'd never recorded this many minutes of screencast before, and I was blown away by the amount of time it takes. I was also surprised at the level of detail involved, from microphone setup (which I messed up for a couple of segments) to color matching between codecs, it was fun to learn a whole new set of technologies.

I was also surprised at how hard it was to talk to a microphone. When we write books, we always try to write as if the reader was sitting there next to us. I tried to to the same approach with the screencasts, but it takes a whole new set of skills...

What I really liked was the way that I could live code examples to illustrate points. The first episode has maybe 50/50 code and exposition, and the second and third episodes are mostly code. And the code acts as a great skeleton on which to hang the concepts. Apple-R also keeps me honest.

So, if you're interested in how the Ruby object model really works, and want to improve your metaprogramming chops, why not check them out?

So I've been doing some music...

A while back, I was asked during an interview what I'd do if I had three months off. I said I'd take piano lessons.

Well, my wife read that and very sweetly got me some. And then reality hit home. I really do have totally uncoordinated hands. I try to play, but I'm getting nowhere.

At the same time, I still enjoy noodling around with music. So my piano teacher (in a move motivated by self-preservation, no doubt) suggested we should look at composition instead. And I've been having a whole bunch of fun ever since.

But then Chad Fowler reminds me that the test is having it heard, which is kind of scary. But here's my first piece. Be gentle...

(Update: people asked for the transcription: it's here. Some of the pedal marks are screwy: I'm using Encore, and it seems to move them around every time I save. I might well end up going back to Sibelius. Forgive any amateur mistakes.)

New lambda syntax in Ruby 1.9

I'm slowly getting used to the new -> way of specifying lambdas in Ruby 1.9. I still feel that, as a notation, it could be clearer. (I'd personally like just plain backslash, because that looks pretty close to a real lambda character, but that's not going to happen.) But having punctuation, rather than the word lambda, makes a surprising difference to the way my eyes read code.

For example, you could write a method that acts like a while loop.

def my_while(cond, &body)
  while cond.call
    body.call
  end
end   

In Ruby 1.8  and 1.9, you could call this as

a = 0
my_while lambda { a < 5 } do
   puts a
   a += 1
end

But my brain finds that seriously hard to scan. The Ruby 1.9 -> syntax makes it slightly (just slightly, mind you) better:

a = 0
my_while  -> { a < 5 }  do
   puts a
   a += 1
end

I suspect this is just a question of time. In a year or so, we'll parse the -> syntax in our heads without thinking twice. Once it does become natural, I suspect we'll find all sorts of new uses for procs.

Code in Presentations, Part II

OK, enough people asked, so...

http://github.com/pragdave/codex/tree/master

Every good relationship starts by establishing some basic ground rules. Here's ours: you're on your own. Totally, bleakly, and emptily on your own. No support. No requests for enhancements. No cards on your birthday. And I want to continue to see other developers.

But I will consider patches. In particular splitting it up so it can be installed as a Gem would be really nice. You'd probably need some kind of generator to create a new slide show. I'd guess this would contain just a Rakefile, a slides/ directory and an html/ directory.

Enjoy.

Zachary Got His Black Belt Today

Zachary has been studying karate for almost 5 years now. About 2 months ago he got cleared to test for his black belt. Since then, he's been in intense training, leading up to two consecutive weekends of testing. Last week was the formal stuff—a verbal presentation and his kata. This weekend was the fighting part. He had to go through a set of eight self-defenses he'd created, then do some grappling. The session finished with 15 consecutive 2 minute sparring sessions with a mixture of classmates and black belts, with a 30 second break between each, topped of with a no-holds sparing session with an instructor, followed by a session of two-on-one sparring. It's been a couple of hours, and I think all of our heart rates are all still elevated.

He has worked so incredibly hard for this. I'm so proud of him.

Now I have to work out how to live with a teenage son who is both bigger than me and formally trained in martial arts :)