A couple of weeks ago, I finally managed to update my second book, Cognitive Productivity with macOS®: 7 Principles for Getting Smarter with Knowledge, on the iBookstore. The delay was due to problems with iTunes Producer, the software one uses to upload books to iBookstore.

In case you’re curious, here’s a bit of background.

I wrote this book in a delicious flavor of Markdown that is designed specifically for writing rich books, Markua. I think I was the first person to develop a multimedia content-rich book in Markua. I use Leanpub to convert the book to e-pub, PDF, and .mobi formats. I never had any problem opening the epub version in iBooks. Yet iTunes Producer kept reporting upload errors. Alas, iTunes Producer’s error messages are very opaque. And that app does not offer a convenient interface for copying the errors. One has to click a “report error to Apple” button in order to get a selectable version of the error message.

In June, I hired a contractor to convert my book to an epub file that iTunes Producer would accept. (Parenthetically, that contractor actually assed me for my Apple ID and password so she could upload it to iBookstore for me. Of course, I said “no way”!) She couldn’t simply summarize the many syntactic changes she made to my book, and I obviously didn’t want to rely on a contractor to repeatedly update my book for me. (My books are “lean”, which means I need to be able to update them frequently.) So in my non-existent “spare time”, I rolled up my sleeves to address the problems.

To make a long story short, some of the difficulties iTunes Producer had with my epub files had been foreshadowed by status messages generated by Leanpub’s Markua-to-epub processor. But there were other formatting issues that Leanpub had not flagged. (For as long as I have been using computers, I have had the unfortunate knack of discovering limitations in others’ software —useful if you are a QA specialist, which I am not.) I spoke directly with some iBookstore representatives at Apple, but they couldn’t isolate the problems with the epub file. I wanted to find the issues myself with an epub process, but Apple does not provide an e-pub validator. The link to the e-pub validator page in their email messages is itself invalid… (I did eventually download an epub validator from github.)

So, I dealt directly with Leanpub, who kindly pointed me to all the remaining formatting issues with my book (including many broken links). I fixed all of them, and was finally able to update Cognitive Productivity with macOS on iBookstore via iTunes Producer.

So: the iBookstore version has finally caught up with the Leanpub version of my book.

Still, I recommend interested readers purchase my books on Leanpub rather than Amazon or iBookstore. By purchasing on Leanpub, you get free access to the book’s “extras”, and you get the book in three formats (PDF, epub and .mobi). My Cognitive Productivity books, and this website, explain why I think Kindle is not as useful for delving ebooks as iBooks (or Skim, for that matter).

Cognitive Productivity with macOS also contains several tips on delving with iBooks and PDF readers.

Release notes for Cognitive Productivity with macOS are here.