RSS RSS feed | Atom Atom feed

Thoughts on Writing and Formatting an eBook

AsciiDoctor is your friend, if you let it.

A friend who knows that I write books of various sizes asked me about writing an eBook, in particular, how I actually write it. I guess my answer went a bit beyond the question, but here's what I wrote:

Writing: I start by organizing my thoughts into a high-level outline. After that I am not organized: I write in whatever order the words come to me. Some writers say they'll write from start to finish in order, but I cannot. Words come to me in great clumps, based upon my knowledge and/or research. These clumps of words I then "write down" (pour into the computer) and insert in an order that I hope will make sense. When the book is long enough, I stop writing. I revise constantly, going back over and over the text, finding both typos and better locutions, moving text around, splitting and joining sections, adding entire parts that I may have missed. My original outline is neither a stone tablet nor an impediment to writing, but a guideline to be bent into the final shape of the book as it emerges.

When I have something I think is readable, I show it to family or friends who are interested in the subject. If they like it, and find it generally readable, I will work on it some more based on their feedback. If not, I will either give up on the project if it now seems hopeless (if the subject matter is already nearing obsolescence), or, go back and re-write the parts which failed to perform their duty to inform and amuse.

Tools: I want to be able to format an eBook into PDF, ePub, and various other formats, so I don't use Microsoft Word or LibreOffice. Instead, I use what is at once an archaic concept and the best tool for the purpose: a text formatter, AsciiDoctor ( I can then edit using almost any plain text editor (think Notepad or TextPad or EditText, but in fact I use the Unix graybeard's tool vi, which makes me far more productive than any mouse-based editing tool). The actual formatter AsciiDoctor (and its original, AsciiDoc, ), were named because they read ASCII (plain text) and produce nice Documents from it. AsciiDoctor is "AsciiDoc Two"; it accepts the same format (plus extensions), but runs much faster. The 9,300 or so words of a biography I'm working on formats to pretty good HTML for previewing in under one quarter of one second on a three-year-old MacBook Pro, which is two orders of magnitude faster (100x faster) than the time it takes Microsoft Word just to start up on the same machine. he latest AsciiDoctor includes asciidoctor-pdf which as the name implies can generate PDF directly (older versions had to go through some internal phases that slowed it down); this takes over two whole seconds(!) to generate a !30-page PDF, so it still takes Word ten times as long to start as it takes asciidoctor-pdf to finish.

In addition to a couple of ongoing eBook projects, I have done the Third Edition of the Java Cookbook (850 pages) entirely in AsciiDoc, and will be doing the entire Second Edition of the Android Cookbook (around 700 pages) the same way. In both cases the publisher's tooling group converted the manuscript from previous formats into AsciiDoc for me, thankfully.

For any more discussion on why AsciiDoctor is a good thing for writers, the reader is referred to

Tags :

Looking for a local wedding photographer?

Local wedding photographers
Image courtesy of: SnapKnot - Local Wedding Photographers

How did everyone except me know this OSX Workaround?

Mac OS X; SoftwareUpdaterLauncher; hangs

For any random OS X update that hangs in the dreaded "SoftwareUpdateLauncher" gray screen, do the following:
  1. Unplug all external peripherals including secondary monitors
  2. At this point the SoftwareUpdaterLauncher should allow the Apple Menu to work.
  3. Select the Apple Menu Logout button.
  4. Count to five.
  5. Click your heels together and repeat: "I want to go back to Kansas Working MacOS"...
  6. Take a deep breath and press the Return/Enter key.
  7. After a second or so you will see life again: a prompt on whether to Restart or to install and Restart. Since you're here for that update, you might as well choose Install and reboot.
  8. Watch it install, and restart.
  9. There is no next step. You are done. If not, try the Apple support forums.

Java folk, please vote up Jsr-310

Getting JSR-310 into Java 8 is a major step (see, but to make it even more useful it should be recognized by major other APIs. There are issue trackers where you can trivailly vote on to help get this message across to API suppliers:

JPA ->
Android ->

A great burst of enthusiastic voting might help the powers that be realize that devs are really ready for a real Date/Time API. Because it's time.


Tags :

Another Day, Another Year

"When you're young, five years drags. An eternity. When you're older, five years rushes past, dragging you kicking and screaming toward  eternity." -- Glynnis Campbell in "Retrospect", in Best of Star Trek graphic novel.

So another year has come and gone, and precious few blog entries have come or gone here. I'm still developing mobile software (Android) for University Health Network. Still teaching for Learning Tree. I'm finalizing the Third Edition of my Java Cookbook. And I'm doing some writing for InfoQ. And of course still making photographs.