E-Book Enlightenment



Booki is a website used to create e-books.  The URL is:


Most Internet users have encountered Wikis before.  Everyone has at least heard of Wikipedia, the encyclodepia written and edited entirely by volunteers.  Essentially, a Wiki is software that enables people to edit a website from within the website.  Many free software projects use Wikis for documentation purposes, and both the One Laptop Per Child project and Sugar Labs have their own Wikis.  While Wikipedia is an example of what this approach can achieve, very few Wikis are as well maintained as Wikipedia.

Some people involved with the free software movement felt that what was needed was not Wikis, but free manuals.  A Wiki tends to branch off in all directions. However, a manual needs to be more formally structured, with a Table of Contents and attributed authors, and ideally should be something that you can copyright, print and bind, give an ISBN number, and sell on Amazon.

The website FLOSS Manuals was created to meet this need. The letters FLOSS stand for Free and Libre Open Source Software.  If you've been paying attention you probably realize that the book you are now reading came from that very site.  This book and the others on the site are not just articles on the web.  You can create a PDF from them and read it as an e-book, and quite a few books on the site can be ordered as bound and printed books from a publish-on-demand service like Lulu (http://lulu.com/).

FLOSS Manuals originally used a modified version of Wiki software called TWiki, and a good part of this book was written with that version of the software.  The longer-term goal was to create a web-based platform specifically for making books.  That software, you've probably guessed, is Booki.

One key difference between FLOSS Manuals and Booki is that the FLOSS Manuals website is only for manuals for free software, nothing else.  You need to propose a topic for a manual on the site mailing list, and if it is approved someone will create the book for you.  When you are ready to publish your book on the site you'd need to send another request to the list to ask for that to be done.

Booki is different.  Anyone can create a book on Booki, on any subject.  Where you publish the book is up to you.  The software will let you generate your book in a variety of formats, including HTML, PDF, and EPUB.  You can take this output and host it wherever you like.  The PDF and EPUB could be donated to the Internet Archive as a Community Text, and you could publish the HTML on your own website.  FLOSS Manuals will continue to be hosted on the FLOSS Manuals website.

This is what Booki looks like when editing a book (in fact this very book, under its original title).  You will notice that I'm using the Sugar Browse Activity, which is completely adequate for the purpose:


Booki is one of the best tools available for Sugar users to create e-books.  It can be used on the XO or from Sugar on a Stick.  It supports many authors collaborating on a single book.  It supports translating books into many languages.  It can create PDFs and EPUBs.  It can create books formatted for print-on-demand services.  It can create documents in Open Office ODT format (which Open Office can convert to MS Word format).  It can even be used to download, proofread, and correct EPUBs created by the Internet Archive.

Booki is an excellent option for teachers preparing textbooks, but it can be used by students for their own projects too.  Here is another screen shot showing how you can upload Journal entries containing images to the image directory for a Booki project:

Booki Upload Image

 Here's another one showing how you can select an image and insert it into your book:

Booki Select Image

In addition to Browse you'll want to get the Sugar Commander Activity which has a number of useful functions that involve creating and updating Journal entries.  The latest of these is a button to resize image files to any width.  Booki needs images to be 600 pixels wide or less, and Sugar Commander can do the resize with the push of a button:


I even used Sugar Commander to resize the screen capture above for this book:


After this, I uploaded the resized screen capture into the book:


A complete description of how to use Booki is outside the scope of this book.  If you want to learn more, check out the Booki User's Guide:


A Few Thoughts On Collaboration

The main reason to use Booki rather than a word processor to write a book is to effectively collaborate with other authors.  The book you are reading is my second attempt to do this (and the Spanish translation of my first FLOSS Manual would definitely qualify as a third) so my opinions on this might be worth something.

The first thing is that there are good reasons to collaborate and not so good.  A good one is that your collaborator can bring expertise to the book that you don't have.  A bad one is that you think there will be less work for you if you have a collaborator.  There are many human activities where "Many hands make light labor".  Writing a book isn't one of them.

Many successful software manuals have been written using the "Book Sprint" method.  This involves getting a small group of people in the same physical location for about a week and having them write the whole manual together in that one week.  I had a coworker of mine involved in the Book Sprint to update the manual for CiviCRM, a software package used by non-profits.  She had done some work on the software to support the Jewish calendar because her synagogue needed it, and this work had impressed the developers of CiviCRM enough that they invited her to participate in their Book Sprint.  They had a grant, so they paid her traveling expenses to Lake Tahoe and put her up at someone's home for a week.  She took a week's vacation to work on it.  Others worked on the book remotely.  Nobody got paid for their work.

If you're interested in doing a Book Sprint there is a FLOSS Manual on the subject, plus another FLOSS Manual on "Collaborative Futures" which is itself the product of a Book Sprint.

My books were not written using the Book Sprint method. My books were more of a slog than a sprint, and I didn't get a bunch of people to commit to working on my book full time for a week.  What collaboration there was was informal and spread over months.    My first FLOSS Manual was a book on creating Activities for the Sugar platform; in other words how to write programs that would run on the XO laptops used by the One Laptop Per Child project.  There is no way a Book Sprint could have produced that book.  I had to create a bunch of short programs to demonstrate everything that can be done on that platform and how to do it simply.  I needed to be test and debug them.  I had to set up several versions of test environments.

You might not think of that book as a collaborative effort, since I wrote every word in it, but in a very real sense it was.  I got lots of feedback from other developers, help debugging my examples, help resolving problems with the test environments, and many useful suggestions.  Writing the book on the web made that kind of collaboration much easier.

There were a couple of people who offered to write chapters for the book, but this did not come to pass.  In the end this didn't matter; the book ended up doing what it needed to do.

After this first book was published there was interest in creating a Spanish version.  Some of the most successful OLPC projects have been in South America, so I definitely wanted there to be a Spanish version.  Unfortunately, I don't speak any Spanish, so I didn't feel qualified to do it.  I explained on our mailing lists that it would be very simple to request a book project to be set up on the site for a translation, and that the site offered an interface where you could view the original chapter while writing the translation (when we started this we used the original TWiki software for the translation.  Booki doesn't have a side by side translation view yet).  Several people offered assistance, but nobody requested the project to be set up.  I decided to do this myself, even though I couldn't translate anything.

After the project got set up a couple of people got accounts on FM and looked over the book, and one of them translated a few paragraphs.  Several of the people who had offered to help were concerned that they did not have the technical knowledge to translate the book, and for several days it looked like nobody was going to work on it.

A friend suggested using Google translate to create a base translation that native speakers could correct.  I ended up using Babel Fish instead because the HTML generated by Google Translate had a lot of extra stuff in it like JavaScript and the original English text being translated.   After I started doing this a retired teacher who was fluent in Spanish started to correct the text, and I went through and untranslated things that should not be translated, like code examples.  It really needed native speakers to get it into shape.   The retired  teacher sent out an email on some lists explaining that we had a translation going that needed to be corrected.  After that several native speakers got accounts on the site and started to correct the text.

What I learn from this is that starting a book from nothing is intimidating.  However, once the book reaches a critical mass and there is no doubt that there will be a finished book you'll find that getting help and feedback is easier, almost inevitable.

This was not the end of the problems getting the book translated.  While we had several people willing to polish up the Spanish in the earlier chapters, none of them were confident in their ability to update the more technical chapters later on.  We were fortunate enough to have someone come along who did have a technical background, but she wanted to start the whole translation over again, using no automated translation at all. 

She felt very strongly that while a machine translated book might be tolerable for adults, for students still mastering their native language it needed to be much better.  The Spanish teacher in her school often pointed out the relationship between mastering your first native language and mastering of formal languages, including mathematics.  Adults can deal with a poorly translated book but children should not have to.

I was not sure this was a good idea, but she did manage to recruit a large team to do a complete translation that way. Since she was starting over the whole job was done in Booki and the old Twiki version was abandoned.

The work her team did was absolutely terrific, but I still believe that if we didn't start with the awful machine translated version we would never have gotten the good one.

This second translation involved a twelve native speakers with technical skills.  It was practically a Book Sprint.  The leader of the project, Ana Cichero, recruited the volunteers and made them responsible for individual chapters.  They put footnotes at the end of each chapter to indicate who translated what, in addition to the "Credits" chapter at the end.  She also set a deadline to get the book published (the Winter solstice). She came up with an interesting way to assign chapters to translators: In the name of the chapter in the main page the translator would put his name and the percentage complete of the translation.  For chapters with no translator there would be question marks.  This allowed everyone to see the progress of the book at a glance:

Instead of publishing the book several times as it was being worked on Ana wanted to publish it only once when it was completely finished.  (She tells me that in retrospect publishing several times might have been better).  She reached a point where the translation was ready to go but it turned out that there were still problems with the book:

  1. When you create a book with Booki every picture in the book must be contained within the book.  You cannot link to a picture elsewhere and have the picture show up in the published book.  Unfortunately, the HTML editor Booki uses does show the picture if the URL is outside the book, so even though the picture is not put in correctly it looks like it is there, both in the editor and in the View page.  This makes this kind of problem difficult to detect.
  2. Some of the team members preferred to use Word to edit their chapters rather than the Booki editor.  This can cause problems, because Word produces HTML that is poorly formatted and which contains extra style information that can cause problems when making a PDF.  Again, the Booki HTML editor makes the page look just fine.  You need to activate the HTML mode to see the problems.  Some used word processors to do spell checking.  (The web page editor in Booki actually offers spell checking, but it wasn't working at the time).
  3. Some team members used Google Translate to create a starting point for their own translation.  Unfortunately this creates HTML with a lot of extra tags, including the original text alongside the translation.  If you want to do an automated translation Babel Fish HTML is much cleaner, although the translation may not be as good as Google's.
  4. In a couple of cases team members used plain text with a large font instead of h1, h2, h3, etc. tags.  This looks fine but hides the structure of the book from OBJAVI, so it can't do as good a job of generating tables of contents.

There was a lot of unexpected work at the end, but I can't argue with the results.  The translation team did an outstanding job! 

The best motivation to collaborate on writing a book is a desire for the book to exist. To quote Antoine de Saint-Exupery:

“If you want to build a ship, don't drum up people together to collect wood and don't assign them tasks and work, but rather teach them to long for the endless immensity of the sea”

If you can sell people on the idea of the book you'll get collaborators.  That's another reason you may have to write a substantial chunk of the book before collaborators show up.  A partial book is easier to sell than an idea for a book.

With the book you are now reading I got collaborators in the conventional sense of the word.  Before I had worked on Make Your Own Sugar Activities! I had written the Get Internet Archive Books Activity described  in an earlier chapter.    In the process of doing that I met some people from an organization in Oregon called the Rural Design Collective.  This is a group that has done work for both the Internet Archive and the One Laptop Per Child project.  They have a summer mentoring program where talented students get involved with an Internet project and learn skills that may lead to a future career.

When I announced that Make Your Own Sugar Activities! was finished I got an email from Rebecca Malamud of the RDC congratulating me.  The book you are now reading was in the thinking stages and knowing of her work with the IA I told her about my plans for the new book and asked if she'd like to contribute.

At that point the RDC was contemplating what to do for their summer mentoring program and they decided that working on my book might be just what they were looking for. 

We all wanted the book to exist, but for different reasons.  The RDC is focused on training young people to create websites, and so they chose to focus on the graphic design of the book more than the content.  They did provide some content: the chapter on publishing e-books with gCI is mostly theirs (the RDC created that software).

The RDC found a talented young artist who did some terrific cover and interior illustrations (the small ones at the top of each chapter).  The cover illustration that everyone liked didn't really go with the title I had proposed, so I ended up changing the title.  (The same artist also did new cover art for the printed Make Your Own Sugar Activities!)  Another of their mentees created style sheets which they used to create a really beautiful bound and printed edition of the book.  The page layouts he came up with were fancier than anything Booki could create, for instance having multiple columns on some of the pages.

One of the best ways that Booki can help you collaborate is to send you emails when anything in the book has been changed.  The emails have links that let you compare the previous and current versions of changed chapters side by side.  Booki also lets you add notes to each chapter.

In addition to the RDC's work I also got much help and encouragement from the forums of DIY Book Scanning and Distributed Proofreaders.  Again, this is not collaboration in the way the word is normally used, but it was a vital contribution to the book.  I would post a link to the book on the FLOSS Manuals website and ask for comments.  The comments I got often contained valuable information and suggestions.

So in summary I'd say that even if you can't afford to send a bunch of people to Lake Tahoe for a week you'll still find Booki is a good way to collaborate on writing a book!

Using Booki To Correct Internet Archive EPUBs

In the chapter on e-book formats I was a little harsh describing the EPUBs distributed by the Internet Archive.  Actually, I am at the same time full of admiration for them.  IA books are submitted as PDFs containing only page images, without text.  From this IA's software does OCR on the pages, formats the text into paragraphs, figures out where illustrations are on the pages then crops them to size and puts them into the e-book reasonably close to where they would be in the original book.  As a professional computer programmer, I consider this no less miraculous than transforming sausages into a live pig.

Having said this, the fact remains that these books need lots of proof reading and correcting.  If the book is one you donated yourself, it is possible to download the generated EPUB from IA, correct it using an EPUB editor like Sigil, and then replace the original EPUB on the IA website with your corrected version.  Booki lets you do the same thing on the web with collaboration.

You can easily copy any IA EPUB into Booki using this page: 


The Identifier "ThirteenWomen" is from the IA website page for a book I donated, Thirteen Women by Tiffany Thayer.  Click Create and the book will be downloaded from the IA website as an EPUB and imported into Booki.  Once there anyone can work on it just like any other Booki project.  This is the Big Aviation Book For Boys being edited in Booki: 


Using the example of the Big Aviation Book For Boys, suppose your school has a club for model aviation enthusiasts and they wanted to fix up this book and others like it as a club project. One thing they'll want to do is set up a Group for all the books they plan to work on:


Any books they import can be added to this Group.

Most of the proofreading for this book can be done without referencing the original book.  There will be things like page headers and footers to remove, paragraphs split across two pages that need to be re-joined, illustrations that need to be moved to between paragraphs that currently are stuck in the middle of a paragraph, formatting chapter headings and correcting obvious misspellings.  In this book several numbers are garbled, and the only way to correct those and errors like them will be to refer to the original book in PDF or DjVu format.  Rather than do that every time they see such an error, our club members might prefer to use the Notes tab to list all such errors that they find so they can be corrected at the same time:


When the Prop Spinners are satisfied that the EPUB is in good shape they can send it to the Internet Archive using the Export tab:


It is likely that the Prop Spinners would be correcting books they did not donate themselves, so replacing the original generated EPUB will not be an option for them.  What they can do is to create a new entry in the catalog containing just their corrected EPUB.

The Replacing Textbooks Project

Sugar Labs has begun a project to create Open Educational Resources to replace ordinary textbooks.  This project will have its own installation of Booki.  If this sounds like something you'd like to participate in you can read about it here: