What can I use Booki for?

Booki supports any individual or group that wishes to write a book. Some typical uses of the platform might be :

Book Sprints

I am working for rights of immigrant workers. We need to create a booklet about workers rights. I read the (free) FLOSS Manuals online manual on Book Sprints and then organise 5 staff to dedicate 3 consecutive days the following week. The first morning we each create an account. I have already created the new book, given it an open license, sent the others the URL, and prepared the Index. We spend 3 hours discussing the chapters and decide who will write what. At lunch on the first day we start writing. We continue to write for the following 2 days. At the end of the last day we output an A5 book formatted PDF of 110 pages and take it to our local printer to make 500 stapled copies. Over the next 2 days peers from other offices log in to improve and build upon our work. We make the book formatted PDF freely available from our website to read or to print for distribution. Each of the other offices print copies locally and distributes them.

Customising Content

I am a developer that has contributed to several manuals on Free Software. My specialty is Drupal, and I have a client that I have just created a site for using Drupal. I want to create a manual for that client so I go to my user page and fork the existing FLOSS Manuals Groups manual on Drupal. I now have a standalone version of the manual on my account, any alterations I do will not be reflected in the original manual unless I merge the changes up stream. I remove several chapters not relevant to the client, add 4 new chapters that are specific to the client. I mark the new chapters as "Copyright : all rights reserved" and private so they are not reusable or seen by anyone else using the system. I write these chapters with information that is specific to my client and replace several existing screen shots in other chapters with screenshots of my clients site. I export the material to book formatted PDF, upload it to lulu.com print on demand service and buy 2 copies of the perfect bound book for my client. Later a potential client calls me for a meeting - I use my version of the Drupal manual, remove the client sensitive material, upload it, buy it, and bring the book to the meeting.


I am a volunteer translator. I want to translate a book on Mexican Cooking from the CookMe Group into French. I fork the existing manual from the CookMe Group to my user page. I force a machine translation of the content and mark all chapters "to be translated". I message others subscribed to the Booki French group that I need some help and with 3 others we translate the material and mark all the chapters "to be proofed" or "requires technical proofing" as we complete them. When we are finished I invite a friend to proof the content for us. She takes 1 week, doing it in her spare time. After each chapter is proofed she marks them "complete". Later I output the translated book to book formatted PDF, upload to lulu.com and buy a copy.

Multiple Formats

I am an educator and have written a text book on digital design using Booki. While writing I kept the book private but invited select users to view the material and leave comments - this was great feedback for me. Now the book is completed and has been picked up by a publisher - I output an .odt file from Booki and open this in OpenOffice.org, save to a .doc format (the publisher does not know about free software) and send to them. I also negotiated a Creative Commons license for the material with the publisher. I release the book on my website using the embed api and invite translations. Within 4 weeks there is a completed Spanish translation which is uploaded to a print on demand service and sold through my website. A Portuguese translation is ready 3 weeks later. After an enthusiastic response to the Portuguese translation in Brazil I output the material to multiple column PDF suitable for printing on large format newsprint. A school district in Sao Paolo finds a local printer, downloads the PDF for free, and produces 1500 copies on newsprint and distributes for free around schools - this costs the same as printing or buying 30 printed books so I feel good and the schools make a huge savings.


I am invited to facilitate a Book Sprint on farming techniques in a remote area. The venue is a farm with no internet connectivity. I know a little about how to install web services so I download and install Booki on my laptop. At the Book Sprint we have 4 laptops connected to the local network version of Booki running on my machine. We write the book in 5 days. We output the book formatted PDF from my laptop, print the book at a local printer and distribute locally as educational materials. Later I upload the sources to the version of Booki running on my own server so others can access and reuse the content as they please.

Organisational Documentation

My organisation wants to review and upgrade it's documentation. We have decided to use Booki to collaboratively rewrite and update our content. Our IT Guru has installed Booki on our server so writers can login and update documentation from any machine. We will use the versioning feature to keep track of documentation versions as our docs grow and develop over time. When final revisions have been approved they are 'published' to screen readable PDF and Book Formatted PDF. The Book Formatted PDF is printed off for our 'official documentation' while the Screen readable PDF stored on our server for easy digital access by staff.

Accessing Booki

Booki can be accessed in several ways depending on where it is installed.

There is an installation of Booki that anyone can use for any kind of book. This web site provides hosting for many groups and books and is found at http://www.booki.cc

Your organisation can also install a copy of Booki on your own server. In this case access would be made through a url provided by your organisation. The default look and feel of Booki 1.0 (Alpha) looks like the following (remember Booki is highly customisable so this might not look like your installation of Booki if you have changed the templates):

Once you have arrived the home page, most functions can be accessed via the Menu down the left hand side of the window.

Lastly, you can also install Booki on your own computer. The location of your local copy of Booki can be best determined by reading the information on how to install Booki.

Creating an Account

After arriving at Booki you will need to create a user account before beginning the creation and editing of books.

Account generation is simple:

  1. On the front page click on Sign in / Create Account at the top of the screen.
  2. Under Create Account add your desired USERNAME, E-MAIL, PASSWORD + CONFIRMATION and then your FULL NAME. Your full name is required for registration as it is used for copyright attribution on any works you create or contribute to.
  3. click Create Account.
  4. Booki will generate the account and display a Your account has been created message before redirecting you to your Profile Page.  Your user page is also accessed through My Profile on the menu.

Redirection from outside Booki

Organisations that have generated a group in Booki have the ability to redirect you to the Booki Create Account page from their website.  If the link for this link is set up properly you will also be added to their group automatically when you create your account.

Creating a Book

Ok, lets get to it. Assuming you already created an account there are two ways to create a new book in Booki.

Once a you have created an account you can create a book from your My Books page. This is as simple as entering the title of the book in the field provided and then choosing the desired license from the drop down menu.

  1. Click on My Books in the Menu to go to your Books page.
  2. Under Create new book enter the title for your Book and then select the Licence for the book from the Drop-down list. For more info on licences and which ones to use when - see the chapter on Licensing.
  3. Once you press Create, the book will then be generated and listed on your My Books page as well as under the Books heading on your user page. The book has by default no chapters, sections, or content.

Note: If you try to create a book with the same title as a book that has already exists, Booki will add '-1' to the end of the title and try again, then if the new title also already exists it will try '-2'... '-3'... and so on, until it finds a title that has not yet been created.

Creating Chapters

Once a new book is created click on the edit link next to the title of the new book on your Profile page to open the book's Editing page.

Inside the the Chapters tab, the page is divided into two areas, the top area is the Table of contents and the bottom area is called Hold chapters. Any chapter residing in Hold Chapters will not be visible in you books Reading page and will not be included when you publish your book (e.g. creating a book or web formatted pdf, or epub).

Creating a Chapter

  1. In the Chapters tab on the editing page click on NEW CHAPTER at the top or bottom of the Table of contents.
  2. The New chapter window opens, enter the Title of your new chapter and click Create chapter.


Editing a Chapter

Once you have created chapters, content needs to be added to them (text and images). This is probably how you will be spending most of your time in Booki; writing material, reviewing, editing and updating chapters as well as inserting and organising images.

Accessing the Chapter Editor

  1. First you need to be in the Editing page for the book you are working on.
  2. Make sure the Table of contents is visible by clicking on the Chapters Tab.
  3. Then click on the EDIT link next to the chapter you want to edit.
  4. The Chapter editor opens showing the Chapter Title and any content that has already been added.
  5. Type away!

Saving your Work

As with every other software application you need to save your work regularly to avoid losing those hours worth of effort due to your laptop battery going flat or some similar incident.

Booki has three buttons concerning saving your work which are located at the top of the Chapter editor. They are Save, Save and continue editing and Cancel.

Save : clicking on Save will not only save your changes to the chapter, but will also close the Chapter Editor and return you to the Book's Table of contents.

Save and continue editing : This button is extremely useful, when it saves your changes it leaves the editor open for you to continue making changes to the chapter. This is the button to use regularly to ensure you don't lose the changes you have made to the chapter.

Cancel : This button is only used if you decide that you don't want to keep the changes that you have made to the chapter.

The Table of Contents

Once several chapters have been created and developed, it is time to organise and order your Table of Contents.

Adding Sections to your Table of Contents

On the Book Editing page your newly created chapters will be sitting under the Hold chapters section, but before you add your chapters to the Table of contents, you may want to create separate sections for groups of chapters.

To add sections to a book, first you need to navigate to it's editing page, either via your Profile page or use the Books link in the menu to find and work on a book created by someone else.

  1. On the editing page click NEW SECTION at the top or bottom of the Table of contents.
  2. The New section window opens, enter the title of your new section and click Create section.
  3. The new section is created and placed at the bottom of the Table of contents.

Organising the Table of Contents

Hold Chapters

Inside a book's Chapters tab, the page is divided into two areas, the top area is the Table of contents and the bottom area is called Hold chapters. When a chapter is first created it is automatically placed into Hold chapters and stays there until you are ready to publish that chapter. Any chapter residing in Hold Chapters will not be visible in you books Reading page and will not be included when you publish your book (e.g. creating a book or web formatted pdf, or epub)

Re-ordering Sections and Chapters

If your sections need to be re-ordered click and hold on the up/down arrow at the left of the Section bar you wish to move, then drag the section up or down to get to it's rightful place. If you need to delete a section, drag it into the Hold chapters area of the Chapters tab.

Once the book's sections have been set up you are able to use the same technique to drag your chapters from the Hold chapters area into the correct section of the table of contents. If there are any chapters you are unsure about or want to make significant modifications to you can drag them back to the Hold chapters area so they wont appear in the Table of Contents on your Book's Reading Page.

Deleting Sections and Chapters

To delete a section, use the above method to move it into Hold Chapters once in there it will be deleted.

Currently chapters can't be deleted from Booki, but to prevent them from appearing in a book's Reading page or from being published drag them into Hold Chapters.

Editing Chapter and Section Titles

Once a chapter or section has been created, you may not always like the title or you might be re-organising the entire book and therefore chapters and sections need to be re-named for the new structure. Renaming is the same for both chapters and sections:

  1. Open your book's Edit page and make sure the Chapters tab is selected.
  2. Double-Click on the chapter or section name that you want to change. A text field opens allowing you to change your title.
  3. Make any changes you desire and then click on the SAVE button to the right of the text field. CANCEL will of course cancel any changes made and return you to the previous title.

Adding Images

When you want to add images start editing the chapter you want to add images to, get your cursor in the right place and click the import images button.

Now this is where the changes have been made, when the insert image window opens, you will see two tabs, Images and Upload image.

Images tab : The Images tab lists all the images currently uploaded to your book., click on an image name in the list and it will display a preview for you in the panel on the right. If this is the image you want to add to your chapter click Insert image.

Insert Images Tab

Upload images tab : If the image you want to insert is not visible in the Images tab then it still needs to be uploaded to Booki, it is time for the Upload images tab.

From here it is off to the Browse button, which opens the regular file browsing window for your system. Find the image you want and click on OK or Open taking you back to the Insert image tab. Once you are back you can see 2 settings for your image below the file location on your computer. The first setting is the Rights holder - Here you type in the name of the copyright holder. The second setting is the License -use a drop-box to choose the license for the image (note: Booki only allows content with a free license to be uploaded).

Upload Images tab

Below the license field is another Browse… button, clicking on this will let you upload a second image - each time you select a new image to upload, a new Browse… button appears at the bottom of the window allowing you to add another file to your upload list.

Once you have all the images ready to be uploaded (In the above example 2 images have been chosen for uploading), click on the Upload button. Booki uploads them from your computer and adds them to the available images list for you book. You can now insert the image you want into your chapter by selecting it from the list and clicking Insert image.


Once a book has been completed or finished to a satisfactory level it can be exported. Exporting can be sent to several different outputs - not just to standard print formats - each with it's own specific needs and uses.

First lets look at the formats available for exporting:

book formatted pdf - book(PDF) : Used for the creation of printed books, the book(PDF) file can be uploaded to a print on demand service or even sent to a local printer for printing of a standard bound book. It can also be used for printing a single copy of a book from a domestic printer.

newspaper formatted pdf - newspaper(PDF) : This format is used for printing multicolumn texts to large scale newsprint. This can be useful for cheaply printing off books using a cheap print format and local printers.

web formatted pdf - web(PDF) : This type of production is to be read on screen. It can be added to a website, or downloaded for off-line viewing on a computer or any compatible device.

epub : epub is used for e-book publication, it generates and e-book using the open epub format. Which can be read using any compatible device, including computers with appropriate software as well as portable devices such as the Sony Reader and Apple's iPod Touch and iPhone.

OpenOffice Rich Text format (.odt) : This output can be opened and edited in OpenOffice.org, enabling extra customisations to be added as well as conversion to Microsoft's .doc format for exchange with 3rd parties who haven't heard of free software. This can also be a good method of publishing if you want to customise the fonts and formatting of your published but aren't proficient in CSS.

HTML : the HTML output can be embedded into any website, so an organisation is able to export a book to HTML and then embed it into their website.

Exporting a Book

Once a book is ready from the Book page, click on the Export tab. You can now set the export options for your book.

Simple export

If you are happy with just a generic look and feel for your book and your aren't planning on selling copies to retail book stores, then all you need is a simple publication.

  1. Enter a Title for your printed book. By default this is the title used within Booki but it can be changed if required and forms the Title Page or cover for the book.
  2. Choose the output document type from the drop-down list.
  3. Choose a licence for the book from the drop-down list.
  4. Place a tick next to archive.org if you want a copy of your book sent there.
  5. Click on Publish this book

Booki will convert your book to the desired document type using objavi and when finished will display a link to the generated document. The page size for your book will be Comicbook which is 160mm x 260mm and you use a default style set for your fonts and layout.

Advanced options

Clicking on Show advanced options reveals a range of extra settings that can be used to customise the output of your book.

Book Design With CSS

Book creation is usually managed in multiple environments – the simplest tool chain consists of the writing and editing environment – usually a word processor – and the design environment – usually a Desktop Publishing software such as Scribus or InDesign. The transition is time consuming and ‘clunky’ and made worse if multiple text sources are to be combined in the design processes.

Additionally this process means there are 2 sources for the text. Changes made to the text once the source is in the design environment usually have to be copied also into the word processing files if the integrity of that source is to be maintained and vice versa.

It would be simpler if there was one environment that could be used for creating and editing AND for design. That is what we have created with Booki.

Booki enables content creation through a web interface. Chapters can be easily moved around and content can be easily modified through a very simple WYSIWYG interface. The design environment is also booki and is web based, and we have developed a technology for creating book formatted PDF using CSS.

The interface is simple to use – in the ‘export’ tab of any book you can paste CSS into the text field provided in the ‘Advanced Options’ press ‘export’ and a very short time later you have the book-formatted PDF complete with Table of Contents, numbering, headers, and margin control.

While the interface is easy to use the tool does not ‘by itself’ create a good looking book. The secret to a good looking book is a well defined style sheet and time spent manually tweaking some ‘content’ elements in the WYSIWYG editor (paragraph breaks, placement of images).

To understand the relationship between CSS and the final result there is no substitute for trial and error. Designers must first understand how a ‘web native’ technology – CSS – applies to page based media (books). This paradigm appears simple but it requires a slight re-alignment of how book designers think about designing books, and to do this designers must try the process and persevere until they succeed. After that initial success things become easier.

Probably the best way to start is to take an existing book and look at the CSS, then change it and see what happens. Generating a PDF takes anywhere from half a minute to a few minutes so this is a pretty quick method for seeing how CSS effects the layout of the book. For experimenting first create an account in Booki (http://www.booki.cc/accounts/signing/?redirect=/) and then visit the following page:


When on this page goto the ‘export’ tab and press the ‘Publish this book’ button. The PDF will be quickly generated – beware the ‘progress bar’ is rather fake…the PDF might be ready quicker or slower than the progress bar suggests.

Next, click on ‘Show Advanced Options’ scroll down and choose ‘Custom’ from the ‘CSS mode’ drop down menu. Now a text field will appear with the default CSS – the same CSS that was used for the design of the book you just created.

Now either change the CSS in the text box OR visit this site:


At the bottom of this page you will find a link to the CSS used for the print version of the second edition of this book – its the same book you are currently working on. You can see the CSS states:

/* Main CSS File: */
@import url("http://collaborative-futures.org/material/styles.css");
/* Uncomment based on the book size you export: */
/* A5 */
/* @import url("http://collaborative-futures.org/material/size/a5-hacks.css"); */
/* 5.5"x8.5" */
/* @import url("http://collaborative-futures.org/material/size/5.5x8.5-hacks.css");*/

This is CSS syntax that imports the ‘real’ CSS used which can be found here:


Copy this CSS, change it, and enter it in the CSS text field of booki then try exporting the book again. Experiment with changing the CSS and see what happens..

Creating a Group

Sometimes the group you want to join isn't there yet, so this is your opportunity to blaze a trail and start up a group of your very own.

  1. Click on My Groups in the menu. Once the page loads you will see the bottom section of the page is labelled Create new group.

  2. In the Group name textbox type in a name for your group and then type in a brief description in the What is this group about box below. Be sure that you have everything entered as you want it as currently Booki doesn't let you change your settings once the group has been created.
  3. Finally click on the Create new group button at the bottom of the page. Your new group will be added to the list on your My Groups page and you can click on it to take you to the group page.

Use Case

You are a primary school teacher and for a class project you want your students to work together creating a book that outlines the results of their research. Your hope is that the finished document will able to be used as a learning resource for future classes. To ensure that only your class are the editors you decide to create a group that the class will use for their project. You log in to Booki and click My Groups in the menu. You enter "Room 4 Class Projects" into the Group name text box and then type "Students from room 4 at Sildale Primary School use this group to create Books based on class projects." into the What this group is about text area. After clicking Create new group you see the group is now added to your groups list. You finally click on the group name "Room 4 Class Projects" which takes you to the group page.

Joining a Group

After joining Booki you may want to jump right in and create a book that will be listed under your name.  However, Booki has the ability to organise groups together to create books that share a common theme or interest.

To Join a Group

  1. Click on Groups in the menu.
  2. Find the group you want to join in the Groups-list and click on it.
  3. On the Group page click on the JOIN THIS GROUP button at the bottom of the main panel.
  4. You are added to the group and will see your name appear under the Members list. 
A group also has the ability to format a Hyperlink for Creating an account so when someone uses the link to register with Booki it also automatically adds them to a group.  For Example if FLOSS Manuals adds the following link to the registration page on it's website: http://www.booki.cc/accounts/signin/?redirect=/&group=floss-manuals, it will redirect the new member to Booki's Create Account page. At the bottom of the registration form a note is displayed informing the new member that they will also be added to the FLOSS Manuals group when they click on Create Account.

Removing yourself from a Group

At some point you may want to remove yourself from a group. 

  1. Go to the Booki home page and click on the link to the Group that you want to be removed from. You can also find the Group from your Profile Page, it will be included in the Group list.
  2. On the Group page click on REMOVE ME FROM THIS GROUP. You will be removed from the group and your name will disappear from its Members list.

Adding a Book to a Group

Once you have created or imported a book into Booki, it will sit in the Books list on your user page. As a member of a group often you will want the book that has been created to sit in the Group's list of books as well.

NOTE - A Book can only belong to one group at a time.

To add a book you have created or imported to a group:

  1. On your Profile page, click on the link to the Group you want to add your book to in the Groups list. You can also use the Groups link or My Groups link on the Booki home page to access a Groups list containing the link to the Group you want to add your book to.
  2. Once the Group page has loaded you will see a drop-down list containing the titles of books that you have either imported or created.
  3. Click on the list and select the book you want to add to the Group
  4. Now click ADD THIS BOOK TO GROUP. Your book now appears under the Books list on the Group page.

Removing a Book from a Group

At some point you may want to remove a book from a group. On the group's page under the Books list you will see a remove link next to your book. Click on the link and your book will disappear from the list.


When collaborating on a book, communication is a vital part of the process, whether working in a book sprint, taking your time on more long-term book generation, working locally in the same physical space or remotely online. These situations have different requirements and harmonising these into one system is where FLOSS Manuals has done a lot of real world research and Booki takes the best of what we have learned. Booki includes tools such as real time edit notifications to see who is editing what at this moment, a real time chat (web / IRC gateway), system level notifications, chapter status markers, book progress indicators, work flow tools, and live user status listing

Real time edit notifications

When you have clicked on an edit link for a chapter and someone else enters the books Editing screen your user name replaces the EDIT link in the Table of contents. This notification happens in real time, if you are looking at the overview screen when someone else clicks the edit link for one of its chapters you will see the edit button change to their user name.

Real time chat

Upon entering a book's Editing screen you will see a chat box for that book. The Chat is visible for the duration of the time you are editing the book, regardless of which chapter you are working on. Anyone else editing the book also has the chat box and you are able to communicate with them by typing directly into the text field under the the chat box. This feature is very useful for communication with remote participants in Book Sprints as well as any situation where contributors to are book are working on it simultaneously.

Other information is also communicated through the Chat box. When a contributor enters the book editing screen a JOINED marker is displayed along with their name in the Chat box. So anyone already editing a book can see that someone else has joined them in editing mode and they can start communicating.

Live User Status Listing

Below the chat box is a Currently editing panel which lists all authors currently working on the book. As an added feature of this panel not only is the users name listed but also a "What's on your mind ?" statement, which is edited from your Profile page. This statement can help communicate to others what you are working on (e.g. "I'm touching up formatting in the Introduction"), or how you are feeling (e.g. "Having bad day, don't want to talk...TO ANYONE").

System level notification

System Level Notifications are generated when the following actions are performed:

Booki generates and displays the messages in two ways: using the Chat Box and using the History Tab in the Editing Page.

Chat Box

When one of the above actions is performed the Chat box displays an INFO marker and brief description outlining what has taken place. This Notification is extremely useful in a Book Sprint environment where several participants are collaborating on a book simultaneously. Each participant is kept up to date of others' progress and can instantly reply to any notifications using the Chat Box.

History Tab

The History tab sits next to the Chapters tab in the Book Editing Page. Clicking to the History tab loads up a list of all the edits that have been made to the book (Note: on a mature book it can take a while to load the list due to the large number of edits that have been made). Every time one of the above actions is performed a new item is added to the history tab.

The History Tab is divided into 3 columns: action, user and time. The action column lists the type of action that has taken place and if necessary it includes extra detail regarding the action. For example if the action recorded is create or save then the detail will list the name of the chapter that was created or saved. The user column lists the Booki user who has performed the action and the date and time of the action is recorded in the time column.

To see more detail a user is able to click on the underlined chapter name in the action column which loads a history page for that particular chapter.

If an edit to a chapter has been very minor, for example a spelling correction, the author has the option to prevent a history record from being generated when the chapter is saved. This is carried out using the Minor change, don't notify tick box at the bottom of the Chapter Editing panel. Placing a tick in the box will prevent a history record from being generated when the chapter is saved.

An author also has the ability to add comments to the history record using three text boxes below the Minor change, don't notify tick box. The top box is a general comment box, followed by an Author text box, where the Author has the option of entering their name. The final text box is an Author comment box where the author is able to make another note. Comments entered into any of these text boxes will be added to a history record when the chapter is saved.

Chapter History

The history tab not only lets you see the changes that have happened to the book but it also allows you to view the changes that have happened to individual chapters. Clicking on a chapters name in the action column takes you to a chapter history display. Here you will see a list of all the edits made to a chapter from it's first creation down to the most recent revision. The Chapter History lists the revision numbers with the most recent revision at the top, it also includes the user who edited each revision, the time and date the revision was saved and also any comments made by the author in the general comment box mentioned above.

Using the compare column on the left you can review the differences between any two revisions. Simply select the left radio button for one chapter and the right radio button for the other chapter you want to compare, then click on the Compare revisions button to see the differences between the two chapters.

The records in the history tab can be very useful for working on a book over a long period of time where contributing authors are often not logged into Booki at the same time. It can display what edits other authors have contributed since the last time a participant logged on and help them to decide what areas to work on. This is especially true if the author has added comments detailing what they did and what further work they feel is needed in order to complete the chapter they have contributed to.

Chapter status markers

In the Chapters tab of the book editing page, on the right hand side of each chapter bar there is a status marker for the chapter.

This can be manually altered depending on what stage the chapter is up to. Clicking on the marker reveals a drop-down list. Click on the list and select the status required for the chapter. The chapter's marker is changed to the new status.

When working on a book that has been created from scratch, the default marker is not published. For a book that has been imported from another source, the default status for a chapter is imported even for new chapters that have been created from scratch after the import.

Book Notes

A books notes are where contributors can discuss and add comments about the book as a whole. Anything can be added to a book's notes including a suggested structure or outline for a book, which areas need urgent attention and even suggestions for a books direction. Book Notes are accessed through the Notes tab on the Book Editing Page. Once there you have a free text field to add a much or as little as you want. When you have added your notes, click Save the notes at the bottom of the Notes tab to save your changes, an INFO notification will be displayed in the Chat box saying that the notes have been saved.

Use Case

You log into Booki to make some additions to your book "Growing Vine Fruit", when you load up the Editing page you notice that another member of the Organic Gardening Group is already editing a chapter on Pruning as their name appears instead of the Edit Button for the Pruning chapter in the Table of contents. You use the chat bot to hi to the other Author and two of you have a brief conversation about the structure of the book before start on your own edits.

While you are typing away you suddenly see an INFO icon pop up in the Chat box saying that the other Author has saved the chapter "Pruning". A couple of minutes later you see their name disappear from the Currently editing panel below the Chat box, this reminds you of some ideas that came up in the conversation you had earlier. You think these would be good to share with everyone working on "Growing Vine Fruit" so you save your work and then click on the Notes tab. In the notes tab you type in a couple of sentences outlining a revised structure for the book. Now any other Author will be able to click on the notes tab to find out the proposed structure for the book and even make their own notes or additions.

Once you have finished your notes you decide that you want to compare the other Author's modifications to the "Pruning" chapter with an earlier revision. You click on the history tab. At the top of the history list is the changes saved to the "Pruning" chapter. You click on the chapter name in the list which loads up the chapter history listing every revision of the chapter saved. To compare the differences between the two most recent revisions you click on the left radio button for the latest revision and then the right radio button for the next revision down, now click on Compare revisions. The revisions are displayed with mark-up showing what changes have taken place in the latest edit.

More CSS Book Design

Contributed by James Simmons

One of the things that attracted me to the Booki project was the possibility of creating a printed book. I learned about Booki through the FLOSS Manuals website, which hosts several manuals written by Sugar Labs and the One Laptop Per Child project. These manuals had been written using an software which became the prototype for Booki.

I had been involved with Sugar Labs and OLPC for several years, and had written several Activities that run under Sugar, the operating environment used by the One Laptop Per Child project. I had learned to do this by reading Wiki posts, asking questions on mailing lists, looking at other people's code, etc. It had been a long, frustrating process. There was only one manual for making Sugar Activities, created by OLPC Austria, and it wasn't something that you could give to a new programmer. I program computers for a living and I still had to learn a lot before I could make my first Activity.

One of the goals of OLPC and Sugar Labs is to have teachers and students write their own Activities, and we really needed a manual aimed at that audience. It needed to be a manual that anyone could read for free on the web or as a downloadable e-book, but I wanted a printed book to be available too.

Booki has a lot to offer an author, even without the possibility of creating a bound and printed book, but there is something real about a printed volume that is a great motivator. Authors of printed books get invited on Oprah, are given respect, and get to trade wisecracks over lunch at the Algonquin Hotel. You don't get all that from making websites and e-books.

I have a pretty good collection of old books in my home and have a great deal of respect for the people who design books. I never bargained for being one of them, though. When we submitted my first book to Lulu I just used the default style sheet of OBJAVI (the part of Booki that generates PDFs from your HTML) and I was not too happy with the copy of the book I received. The font for the body text was too small, the font used for the formatted code samples was even smaller, chapter headings and subheadings were ALL CAPS, and there were some odd page breaks. For instance, subheadings would appear at the bottom of a page with the content for the subheading on the following page.

I really should have caught all this before submitting my PDF to the printer, but I didn't for a couple of reasons:

Fortunately Lulu is print on demand so you don't have a warehouse full of books to deal with, and we were able to remove it from Lulu while I worked on these problems. This meant creating my own style sheet.

Anyone who has ever printed out a web page knows that the state of HTML printing is lamentable. (At times as a professional web developer I've used stronger words, but "lamentable" gets the idea across.) The W3C has created some standards for style sheets that are used specifically for printing. No web browser actually implements all of these, and the "Webkit" browser engine used by OBJAVI doesn't either, but it does enough that you can use HTML and style sheets to create a usable and attractive book. There are some tricks involved, which I'll explain. First let's have a look at my style sheet:

body {
  "Palatino Linotype", Georgia, Serif;
  background: #fff;

h1, h2, h3, h4, h5, h6{
  "Gentium Book Basic";
  page-break-after: avoid;

  z-index: -66;
  margin-left: -1000pt;



h1 .initial{

  display: block;
  page-break-before: always;

body .objavi-subsection:first-child{
  page-break-before: avoid;

.objavi-forcebreak {
  page-break-after: always;

.objavi-subsection .initial {

  font-weight: bold;

h1 {
  page-break-before: always;
  background: white;

table {
  float: none;

  text-align: center;
  page-break-after: always;
  page-break-before: avoid;
  max-width: 700px;

  padding: 1em;

table.toc {
  /*border: 1px dotted #999;*/
  width: 95%;

td.chapter {
  padding-left: 2em;
  text-align: right;

td.pagenumber {
  text-align: right;

td.section {
  font-weight: bold;

p, ul, ol {
  page-break-inside: avoid;

pre, code, tt {
  "Courier New", "Courier", monospace;

pre {
  overflow: hidden;

img {
  max-width: 700px;
  height: auto;

This style sheet is mostly the same as the default one, with the following changes:

The last point needs some explanation. Ideally OBJAVI would know better than to put a subsection header at the bottom of a page and have the paragraph following on the next page. If Webkit supported the keep-with-next property of CSS this would be possible, but it doesn't. We need to give Webkit some help by inserting page breaks where they are needed. To do this we need to edit raw HTML.

Fortunately, this is not too awful. You need to turn on HTML mode in the page editor, then look for the heading you want to move down. It will look like this:

<h2>My Badly Placed Heading</h2>

Insert a DIV tag like this to force a page break:

<div class="objavi-forcebreak"></div>
<h2>My Badly Placed Heading</h2>

When you use the new stylesheet this DIV will force a page break wherever you put it.

Importing a Book

Books can be imported from several sources, Archive.org, WikiBooks, FLOSS Manuals and epub files. In this chapter we go through each of these scenarios.

Note: When importing text into Booki from it's respective locations and formats it is important to note that the document structure may not be a part of the source file. This would leave the entire text in a single chapter which will need to be broken up into its individual chapters and Sections once in Booki.

Note: If you try to create a book with the same title as a book that has already exists then Booki will add '-1' to the end of the title and try again, then if the new title also already exists it will try '-2'... '-3'... and so on, until it finds a title that has not yet been created.


The Internet Archive (http://www.archive.org) is a a non-profit digital library storing digitised collections of websites, music, moving images, software and books. With its stated mission of "universal access to all knowledge.", its purposes include offering permanent access for researchers, historians, scholars, people with disabilities, and the general public to historical collections that exist in digital format.

On your My Books page under Import select Import Archive.org book from the drop-down list, enter the Archive.org ID and press Import. The Archive id can be found in the Identifier field under the Selected metadata section at the bottom of the text's page on Archive.org.

The text is now imported from Archive.org using Espri and converted into a Booki-zip file (this may take a while). Once the process has finished the imported book will be added to the list of books on your My Books page and My Profile page.


Wikibooks (http://www.wikibooks.org) is a collection of open-content textbooks covering almost any subject. Wikibooks is hosted by the Wikimedia Foundation and as such its textbooks can be contributed to by anyone.

To import from Wikibooks, navigate to your My Books page, select Import Wikibook from the Import drop-down list, then enter the URL for the Wikibook you want to import into Booki. For example 'http://en.wikibooks.org/wiki/Book_Name_Goes_Here'

Once again the text is now imported using Espri and converted into a Booki-zip file (this may take a while). Once the process has finished the imported book will be added to the list of books on your My Books page and My Profile page.


The following notes are due to bugs currently in the importing script, eventually they will be seen to but are not currently on the urgent list.

ePub document

ePub, short for Electronic Publication is an open standard e-book format, that has the ability to optimise the text display for whichever device is viewing the book. ePub documents can be ready by several different devices, including the Kindle, iPhone, iPad and any Computer with ePub reading Software installed. Booki has the ability to import any document in ePub format.

NOTE: although ePub is an open format, not all books available in ePub format have open licences. Therefore, care needs to be taken when choosing to import an ePub document to ensure that it contains a permissive copyright.

To import an ePub document, first you need to get the url for the ePub book, then copy it's location. Then on your My Books page select Import epub from the Select Import Type drop-down list. Paste the ePub URL into the enter epub URL text box and click on Import.

The text is now imported using Espri and converted into a Booki-zip file (this may take a while). Once the process has finished the imported book will be added to the list of books on your My Books and My Profile pages.

Some Use Cases


You have recently joined the Organic Gardening group and have gone in search for already compiled texts that could be used to bolster the number books available under Organic Gardening. Searching through Archive.org you find a book on gardening from 1847, entitled "The Family Kitchen Gardener" by Robert Buist. Due to it's age, you have a suspicion that it may pre-date all the chemical methods employed by modern conventional gardening and therefore contain natural organic methods for growing edible plants. A brief read confirms this suspicion and also reveals that there are areas of the text that could do with tidying up as well as some updating for the 21st Century, cementing it as a great candidate for importing to Booki.

  1. You navigate to The Family Kitchen Gardener's page on Archive.org (http://www.archive.org/details/RobertBuiststheFamilyKitchenGardener1847);

  2. You scroll down to the bottom of the page where you find the section called Selected metadata.
  3. Here you can see that the Identifier is: RobertBuiststheFamilyKitchenGardener1847. You copy the Identifier and then go to your My Books page on Booki.

  4. Under Import Book, you select Import Archive.org book from the Select Import Type drop-down list and then paste the Identifier into the enter Archive.org ID text box before clicking on Import.

  5. Booki takes a couple of minutes importing the book and when it is finished you see The Family Kitchen Gardener added to the Books list on your My Books page and My Profile page.
  6. You can now click on it's title in the Books list to start reading.

ePub document

After importing The Family Kitchen Gardener you have been looking through Project Gutenberg (www.gutenberg.org) and have found a book entitled "Culinary Herbs: Their Cultivation Harvesting Curing and Uses" by M. G. Kains Originally published in 1912 it contains a lot of information not only around growing herbs, but also ways to treat, store and use them and provides a fantastic base for a book on organically growing herbs.

  1. After loading your My Books page in Booki, you open a new tab or window in your web browser.
  2. In the new Tab/Window you navigate to the home page for Culinary Herbs: Their Cultivation Harvesting Curing and Uses (http://www.gutenberg.org/ebooks/21414)
  3. Once there you scroll down to the Download this ebook for free section of the page. Under the Computer-generated files list you see two epub versions of the book one with pictures and one that is plain text.
  4. Thinking that it would be easier to remove any unneeded or unwanted pictures than to add new ones later on, you decide to import the version with pictures. You right-click on the main site link in the EPUB with images row of the list and click on copy link location (firefox, ...) or... (ie, ...), or... (safari, ...).
  5. Going back to the tab/window containing the My Books page you select Import epub from the Select Import Type drop-down list and paste the copied link into the enter epub URL textbox before clicking on Import .
  6. Booki takes a couple of minutes importing the book and when it is finished you see Culinary Herbs: Their Cultivation Harvesting Curing and Uses listed under Books on you My Books and My Profile pages.
  7. You can now click on the edit link next to it's title in the Books list to start editing the newly imported book.


Finally while browsing through Wikibooks you spot the Horticulture Textbook. While this book is not specific to organic gardening, organic practices and techniques are presented alongside conventional gardening methods. With some modification this could be a really good overview to organic gardening as a whole and you decide to import the textbook.

  1. You navigate to Wikibooks (http://en.wikibooks.org) type Horticulture into the search box and click on Search. This takes you directly to the home page for the Horticulture textbook.
  2. You select the entire URL for the Horticulture textbook in the Address Bar and copy it. In the case the URL is http://en.wikibooks.org/wiki/Horticulture.
  3. You now login to Booki and navigate to your My Books page.
  4. At the bottom of the page under Import Book you click on the drop-down arrow next to Select Import Type and select Import Wikibook.
  5. Now you paste the copied URL into the enter Wikibooks URL text box and click on Create.
  6. Booki takes several minutes importing the textbook and when it finishes, Horticulture is added to the list of books on your My Books page.
  7. You can now click on its title to read through the newly imported book or click on the edit link at the end of the title to start making changes to the book.

Export Options

On the Editing page for you book, you have a series of tabs at the top of the page, the Export Tab is on the far right.

The Export Tab

The simplicity of the Export tab when first opened disguises it's power and flexibility. Since there are so many options and customisations available for exporting your book, we wont look at everything in one go. Today I will explore what is available through the basic export options and will follow up with later tutorials that cover the different tools available under the advanced export options.

Notes on Exporting

When exporting a book, only the chapters inside the Table of Contents (ToC) are exported, chapters that are listed under Hold will be skipped during an export operation. This means you can easily export a book with a selection of complete chapters while keep ingthe 'unfinished' chapters in the Hold section.

Using Basic Export only produces documents in one page size - called COMICBOOK it measures 168mm x 260mm

Basic Export Options

Book Title : By default when you enter the Export tab the title used when your book was created is entered as the book title. However you can change this when you export your book. When you change the title it effects the text on the 'inside cover' of a print books and he cover of an ebook. The title can be anything you want such as "Booki User Guide: Your map for unlocking the secrets to Booki". This title would be cumbersome to use as your working/editing title in Booki, however it is easily added at publishing time.

Document type : This is the all important section where you choose the resulting file type and layout of your exported document. There are five types of outputs to choose from: Book formatted PDF, Newspaper formatted PDF, Web formatted PDF, Epub and Openoffice (currently disabled). The Web formatted PDF and Epub outputs are for electronic reading. While the other formats are designed for final use in print via different mediums.

Document Type Dropdown list

Book formatted PDF - this has been optimised for use with print on demand services such as Lulu.com but can also be used for other forms of bound printing.

Newspaper formatted PDF - this is highly experimental and not yet fully functional. It is designed for multi-column, black and white printing on news print, an excellent low-cost option for printing your book.

OpenOffice - While currently disabled we hope to get this back online soon. If you are a developer and wish to work on this please let us know. OpenOffice.org's Open Document Format (.odf), some uses may require your book to be in a document format such as .doc or .docx (for example, the de facto industry standard for a screenplays is Word's .doc format). OpenOffice.org is able to convert .odf to .doc or .docx.

Web formatted PDF - The popular pdf format tailored to reading electronically on the computer screen, includes the ability to use your book's index to link to it's different chapters.

ePub - an open standard electronic book format that can be read by a wide range of tools including both ebook software applications and standalone ebook readers (iPad, Android, Kindle etc).

License : The license of your book governs how it can be reused. Licensing is a big topic and trying to figure out which license to use is beyond the scope of this tutorial. Once place to start is the licensing chapter of the Booki User Guide (http://www.booki.cc/booki-user-guide/_v/1.0/licensing/) which gives a brief overview. For more detailed info for the Creative Commons and GPL licenses on offer you can visit: http://creativecommons.org/about/licenses and http://www.gnu.org/licenses/ respectively.

send to archive.org : This option sends a copy of your book to archive.org, this can be especially useful for people who have imported a book from archive.org to proof read in Booki as it takes care of sending the proofed version back to archive.org. Archive is also a good permanent archive of your material.

I you are working on an original you may still like to send a copy of your finished book to archive.org. It is a great place to store a copy of your work. Also many of the books in archive.org have expired copyrights which means they are quite old, so providing a contemporary book on a particular subject could be beneficial.

Publish this book :Once you have made you choices with the above options, click the Publish this book button. Objavi (The publishing engine for Booki) takes your book and exports it using your settings. When it's finished, it creates a link to your exported document at the bottom of the Export tab. You can use this link to download your book. Beware : the progress bar is currently a little fake! We will fix this in the weeks to come.

Link to exported Book

My Settings

Once you have created and account you can edit a number of settings to customise your appearance on Booki and to help communication with the members of any groups you may be a part of.

My Settings Page

To view your settings click My Settings on the menu. When you first enter this page you will see a generic image in the top left corner along with your email and full name you entered when creating your account.

On the right hand side of the panel you can edit your email and full name if either of those were typed in incorrectly or if they change in the future.

Below your full name is a text box where you can type in a blurb about yourself, and at the bottom of the page you can browse your computer for an image to upload for Booki for use in your profile.

Once you have made the changes you want to your settings click Save user profile to save your changes.

My Profile Page

The last user setting you can change is found on the My Profile page accessed from the Menu. Once the page has been loaded you will see in the top right hand corner of the page a text box asking What's on your mind ? You can click in this box and add any comment about how you are feeling and what you are thinking about, then click on Share to save the comment. This now appears under your full name on your My Profile page. And it also appears under your Icon in the Currently editing list when you are editing a chapter in a book.

Installing Booki

For most it will not be necessary to have their own Booki software, and every reason not to. Setting up your own Booki and backing up the data on a regular basis is a significant amount of work, and if you're going to share your work with the world there is really no reason not to use the shared Booki as well.

If you're not going to share, then having your own Booki makes sense. If you don't have reliable access to the Internet having your own Booki might make sense as well. A school with XO laptops that can connect to each other on a network but not to the Internet might find a local copy of Booki quite valuable. In my own case I set up Booki on a computer at home and another at the office.

My day job involves working on an application framework and teaching people how to use it. An application framework is to software what a chassis is to a car, more or less, and just as a factory can build many different cars on the same chassis you can have many applications using the same application framework. Teaching people to use this framework is a challenge, and teaching people who live and work on the other side of the Earth is a greater challenge. We had been using articles on a website, plus a Wiki, to contain the training materials, but after writing two FLOSS Manuals I came to the conclusion that what my company needed was an honest to gosh Book.

I installed the software at home because:

If your reasons are like mine, then let's set up our own Booki!

Getting The Software

You will need a recent version of Linux to run Booki on. Windows or a Mac will not run Booki. You won't need much of a computer to run it on. The computer I used at home was a refurbished IBM NetVista which I had bought online for about a hundred dollars. The computer at work was a discarded desktop model which was even older. I would not recommend trying to install this software on an XO laptop, but any desktop computer made in the last few years should be fine.

I used Fedora 13 for these Booki installs, but I don't recommend it. Fedora is used on the XO laptops, and since I write software for that platform I use it on my desktop computers as well. The downside of Fedora is that, so far, every time I've upgraded to a new version of Fedora I've had to back up all my data and do a complete reinstall. Other than this, the different brands of Linux are more or less the same. If I was going to recommend a Linux for Booki my choices in order would be:

The rest of these instructions will assume that you have Linux installed and have become comfortable running it. Getting comfortable with Linux is the subject for another book, so if you've never used Linux it would be a good idea to find someone who has to help.

Often the install program for Linux will ask if you intend to use it as a web server or if you are doing programming or if you want office software. Answering "Yes" to all three will save some time.

There are actually two parts to Booki, and you'll need both:

installing most software on Linux is no more difficult than checking a check box on an Add/Remove Software dialog, but when software is still under development like Booki is you'll need to get the source code and work with that. The source code for both is kept in a Git repository, so you'll need to have Git installed. Once you do, you can create a "src" directory in your home directory and from in that directory run these commands:

git clone git://booki-dev.flossmanuals.net/git/booki.git
git clone git://repo.or.cz/objavi2.git

This will create two directories under "src": booki and objavi2, which will contain the source code for these products.

Before you can continue, you'll need to check the README.txt file in Booki and the INSTALL file in OBJAVI 2 to find out what other software you'll need to install. For Booki the list is:

If you're lucky the latest redis will be included as a package in your distribution. Fedora users so far are not so lucky. They will need to download the latest source code from http://code.google.com/p/redis/ and compile it using the Makefile in the time honored manner:

sudo make install

If you installed it from a package in your distribution you should check the Services to see that it is enabled and running. If you compiled from source you can start it up like this:

sudo redis-server &

For OBJAVI the list is:

You can get everything from your distribution's packages except wkhtmltopdf. That you'll need to download from http://code.google.com/p/wkhtmltopdf/. You should get a precompiled binary and copy it to the /usr/local/bin directory as user root.

When you set up Linux you should get fonts as part of the basic install, but it would be a good idea to install more. In Fedora the Add/Remove Programs dialog has a section for Fonts that has over a hundred free fonts that you can install. If you use the Roman alphabet only you can limit yourself to the Latin fonts.

Disable SELinux

Fedora 12 and later has SELinux. SELinux is to Linux is as Aunt Polly is to Huckleberry Finn. Its job is to keep programs, including the Apache Web Server, from doing things they should not. Even without SELinux Linux is pretty secure. The web server runs as a user (in Fedora's case the user is named "apache") and it is only allowed to do what that user is allowed to do. On a personal or corporate network this is generally enough.

What SELinux does is add an extra layer of protection. Programs are expected to do certain things. If a program tries to do something that SELinux is not expecting, then SELinux stops it. To get around this you have to tell SELinux to expect this behavior from this specific program. Then it will be allowed. This extra layer of protection makes it more difficult for a malicious programmer to break the system. Sooner or later he will have to do something SELinux is not expecting. He will be stopped and his actions will be logged.

As commendable as this is, if you have a program that does more than a few unusual things SELinux will be a real challenge. OBJAVI falls into that category. It would be a great deal of work to get SELinux to tolerate all the things that OBJAVI is likely to do, and if you're running it on a private network there wouldn't be much benefit. We disable SELinux byediting a file /etc/selinux/config as user root. The file should look like this:

 # This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#       enforcing - SELinux security policy is enforced.
#       permissive - SELinux prints warnings instead of enforcing.
#       disabled - No SELinux policy is loaded.
# SELINUXTYPE= can take one of these two values:
#       targeted - Targeted processes are protected,
#       mls - Multi Level Security protection.

Change the value of SELINUX to disabled, save the file and reboot your computer.

Configure Booki and OBJAVI 2

If you've ever installed anything written in Python on a Linux system you're familiar with the setup.py program, which copies the Python code where it needs to go in the system. Eventually both Booki and OBJAVI will have these, but since they are still being developed they don't have them yet. We will be running the programs out of our home directory for now.

The configuration file for Booki is booki/lib/booki/settings.py. There is a file named settings.py.original which you need to copy to the name settings.py. There are several places you'll need to modify in this file. First is the doc root:

STATIC_DOC_ROOT = '/home/jim/src/booki/site_media'

This points to the site_media directory in the Booki source you got from Git. You'll need to make certain that this directory has a group ownership of apache (or whatever user apache runs as in your distribution) and that the group is allowed to read and create files in this directory. Next you need to set up some URL's:

# use this objavi server

#the name of the booki server (comment out to use os.environ['HTTP_HOST'])

IP Address is of course the localhost IP address. It is likely that you will want to change this to the IP address of your computer so that you can use Booki on the network. You can of course use a DNS name rather than an IP address.

Notice that we have Booki running on port 8000. We need to set up virtual hosts for both Booki and OBJAVI. If you can give each one its own IP address or DNS name there is no reason you can't run both on port 80 like a normal web application. If everything has to use the same IP address then you can distinguish your virtual hosts from each other using a port number. Note that OBJAVI has to run on port 80, but Booki can use any port. There is nothing magic about the number 8000. It just needs to be a port that nothing else is using. In the office I use port 86.

Next we have to set up the database entries:

# DATABASE_NAME = 'booki'             # Or path to database file if using sqlite3.
DATABASE_NAME = '/home/jim/booki/booki.db'             # Or path to database file if using sqlite3.
DATABASE_USER = ''             # Not used with sqlite3.
DATABASE_PASSWORD = ''         # Not used with sqlite3.
DATABASE_HOST = 'localhost'             # Set to empty string for localhost. Not used with sqlite3.
DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.

Booki can be used with Sqlite3 or Postgres. If you are willing to tinker with the code you could get it to run with just about any database. Sqlite3 is the easiest to set up and is completely adequate for Booki on a small private network. The only entry you need to touch is DATABASE_NAME, which is set to put the database in a directory that can be read and written to by user apache. There is no need to create the database file. Booki will create it.

Now from the command line, as yourself, run this:

export PYTHONPATH=$PYTHONPATH:/home/jim/booki/lib

where /home/jim is your own home directory. Then change to the booki/lib/booki directory and run this:

./manage.py syncdb

This will create your database tables. Now you can run Booki itself and check it out. First run this as yourself:

./manage.py runserver

Once this is running you should be able to point your web browser to and see Booki in operation. You should also go to and set up an admin user, plus you'll need to add a license like this:

Django Admin

You can fool around with Booki some more if you like, but be aware that this is not an adequate way to run Booki. You really need to run it under a virtual host in Apache. manage.py only supports one user at a time, and is only good as a quick sanity check to make sure everything is set up correctly. When you're done looking at Booki you can kill manage.py by pressing Ctrl-C in the terminal where you started it.

Next we need to configure OBJAVI. OBJAVI has its own configuration file, objavi2/objavi/config.py. You'll need to change some settings in this file, create some new directories, and make the directories readable and writeable by the apache group. The first setting to change is this one:

WKHTMLTOPDF = '/usr/local/bin/wkhtmltopdf'

When you downloaded the binary for wkhtmltopdf it may have had a name like wkhtmltopdf-static or something else. Change the value of WKHTMLTOPDF to whatever name it has in /usr/local/bin. (In my case I had renamed it to wkhtmltopdf, which hurt nothing).

The biggest change is to add an entry to SERVER_DEFAULTS. The first entry for '' is my own new entry. Use the actual IP address of your machine if you're going to use it over the network.

    '': {
        'css-book': '/static/simmons.css',
        'css-web': '/static/en.flossmanuals.net-web.css',
        'css-newspaper': '/static/en.flossmanuals.net-newspaper.css',
        'css-openoffice': '/static/en.flossmanuals.net-openoffice.css',
        'lang': 'en',
        'dir': 'LTR',
        'toc-encoding': None,
        'display': True,
        'interface': 'Booki',
        'toc_header': 'Table of Contents',
    'booki.flossmanuals.net': {
        'css-book': '/static/en.flossmanuals.net.css',
        'css-web': '/static/en.flossmanuals.net-web.css',
        'css-newspaper': '/static/en.flossmanuals.net-newspaper.css',
        'css-openoffice': '/static/en.flossmanuals.net-openoffice.css',
        'lang': 'en',
        'dir': 'LTR',
        'toc-encoding': None,
        'display': False,
        'interface': 'Booki',
        'toc_header': 'Table of Contents',

The entries that I changed are in bold. I use my own style sheet when creating PDFs for books, and you may wish to do that too. I indicate that I want to display this server in OBJAVI's list of servers and that I don't want to display the other entries. You'll see why in a minute.

You need to create some directories under objavi2/htdocs and make certain they can be read and written to by the apache group:

You'll also need to make certain that the static directory already in objavi2/htdocs is writeable by the apache group. Finally, you'll need to set up a log directory under objavi2 and make sjure that apache can create files there too.

Setting Up Apache Virtual Hosts

The simplest way to get Booki and OBJAVI 2 running under the Apache web server is to set up virtual hosts. What I did was to edit the /etc/httpd/conf/httpd.conf file as the root user using gedit. It is also possible to make configuration files outside of httpd.conf that will be loaded by Apache automatically. I didn't bother to figure out how to do that. The entries I put at the end of httpd.conf looked like this:

Listen 8000

<VirtualHost *:8000>
        # ServerName sugarlabs.simmons
        ServerAdmin nicestep@gmail.com

        DocumentRoot /home/jim/src/booki

        <Directory /usr/share/pyshared/django/contrib/admin/media/>
        Order allow,deny
        Allow from all

        <Location "/">

            SetHandler python-program
            PythonHandler django.core.handlers.modpython
            SetEnv DJANGO_SETTINGS_MODULE booki.settings
            PythonDebug On
            PythonPath "['/home/jim/src/booki/lib'] + sys.path"


        <Location "/favicon.ico">
            SetHandler None
        <Location "/media">
            SetHandler None

        Alias /favicon.ico /home/jim/src/booki/favicon.ico
        Alias /media/ /usr/share/pyshared/django/contrib/admin/media/

        ErrorLog /var/log/apache2/booki-error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog /var/log/apache2/booki-access.log combined
        ServerSignature On


<VirtualHost *:80>
        ServerAdmin nicestep@gmail.com
        #XXX set server name
        #ServerName objavi.halo.gen.nz
        # limit MEM to 800 million bytes
        RLimitMEM 800000000

        #Sometimes it takes a while. Wait.
        TimeOut 600

        DocumentRoot /home/jim/src/objavi2/htdocs
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        <Directory /home/jim/olpc/objavi2/>
                Options +All +ExecCGI
                AllowOverride None
                Order allow,deny
                Allow from all
                AddHandler cgi-script .cgi
                # Remove output filters in case mod_deflate is being used.
                RemoveOutputFilter .cgi

        DirectoryIndex index.html objavi.cgi
        ErrorLog /var/log/apache2/objavi-error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog /var/log/apache2/objavi-access.log combined
        #ScriptLog /tmp/objavi-cgi.log


A Virtual Host is a way of making Apache act like more than one web server. We have one Virtual Host for Booki, and one for OBJAVI 2. When you set up a Virtual Host you need some way for Apache to know which host is needed for a given request. You can do this by giving your server more than one IP address, more than one DNS name, or in my case more than one port. The Listen directive at the top says that we will be listening at port 8000 in addition to the normal HTTP port 80. When a request comes in on port 8000 it will go to Booki and when it comes in on 80 it will go to OBJAVI 2. Again, OBJAVI 2 must run on port 80.

For Booki we're using the mod_python plugin for Apache, so make sure it's installed.

Using OBJAVI 2

If you've done everything right you should be able to go to and see Booki running, and go to and see OBJAVI 2 running. OBJAVI 2 looks like this:


OBJAVI is run from within Book from the Export tab when you're editing a book. If all you want to do is create PDF's and EPUBs you may never need to look at this page. There is one thing you can do from here that you can't do from Booki's Export tab, and that is to create output as Templated HTML. To do that you choose Templated HTML as the Document Type.

Templated HTML is not a kind of e-book, but it is worthy of a brief mention. One of the ways that Booki is different from Wikis like Media Wiki (used for Wikipedia) is that with a normal Wiki anyone can edit any document and the edit is available to the readers of the Wiki instantly. A normal static website makes it easy to control who can update the content, but this control means that updating the content is more work. What Booki introduces is the idea of generating a static website from a Wiki. The Wiki is used by the book authors but is not seen by the book's audience. When the authors have something ready to publish to the world they use OBJAVI to generate a static website and copy it to the public web server.

By default the HTML looks like the FLOSS Manuals website. Because it is generated using templates, you can easily add your own stylesheets, corporate logos, and the like to make the generated site look the way you want it to.

You should definitely think about creating a templated HTML version of your book if the contents are likely to be updated frequently. The website version of your book can then act as a supplement to the e-book version. The stable content will be in the e-book and the latest minor tweaks and corrections will be on the website.

Command Line

This is some brief infomraiton on how to use the command line amdn tools for booki. Usingthese tools you can export and import books and change the URLS and titles of books

You can do a lot of damage with this, so be careful.


  django-admin.py help brokenlinks
  django-admin.py help bookimport
  django-admin.py help bookexport
  django-admin.py help bookrename


brokenlinks - check links inside of book(s).
   django-admin.py brokenlinks command-line my-book
   django-admin.py brokenlinks --no-remote command_line
   django-admin.py brokenlinks --ignore-url http://www.wikipedia.org/  command_line


bookexport - exports book into booki-zip file. this is not real export, and it does not exports historic data.
   django-admin.py bookexport command-line
   django-admin.py bookexport --output my-export.zip --book-version 2.2 command-line


bookimport - imports new book from booki-zip file. you can import it
under new name also
   django-admin.py bookimport book.zip
   django-admin.py bookimport --owner aerkalov book.zip
   django-admin.py bookimport --new-book-title "New title for Command
line" book.zip
   django-admin.py bookimport --new-book-title "New title for Command
line" --new-book-url commandline book.zip


bookrename - renames existing book.
   django-admin.py bookrename --new-book-title "New title" command-line
   django-admin.py bookrename --new-book-title "New title"
--new-book-url commandline command-line
   django-admin.py bookrename --owner aerkalov command-line


  1.  there is env.sh script in the root. you should read that with "./env.sh" before doing any work from the command line, and especially if trying to run any django management command. you should set it up (it sets pythonpath, path and some other things). when running django app, all this things are loaded trough wsgi script, but when using command line you should load it manually (or put it in your profile, and have it loaded every time. but this is not very smart). this is also place where you setup your DJANGO_SETTINGS_MODULE environment variable.
  2. never run anything as root, or god forbid as your user account (or have things installed in your personal /home directory). if booki is installed to be run as www-data user trough apache, then everything must be run as that user. if you use root account, it will work, but it will also screw file permissions on your log files, on your attachment files and etc. also, running things with super user privilege is not very smart. if you go to booki directory and you see more then one user in "ls -l" result list, you are doing it wrong.
  3. 3. django-admin.py and manage.py is result of not having defined DJANGO_SETTINGS_MODULE variable (and not having django/bin in your path). if you know what you are doing and what manage.py file you are running, it is ok to use it, but it is much smarter to be 100% sure with DJANGO_SETTINGS_MODULE  and django-admin.py. if you have more then 2 installations on the same machine, DJANGO_SETTINGS_MODULE is sane way to work with them. and etc..etc...etc...



How We Work

We are happy to extend our core team in time to include others that are enthusiastic about the project and can commit the time and energy. Currently we are a small team consisting of just the following members :

Adam Hyde - Project Manager
Aleksandar Eraković - Progammer (Booki)
Douglas Bagnall - Programmer (Espri, Objavi)

There are several others involved such as Jan Gerber and Andy Cat. We also work closely with the Archive.org team on several issues including epub import and export of content directly to the Archive.org servers.

The development of the FLOSS Manuals platform was really a process of experiencing first hand what is needed to develop Free Software manuals through two processes :

1. Community and individual writing of documentation
2. Book Sprints

With FLOSS Manuals the team would work with the community and Book Sprint teams creating documentation and then discuss what works and doesn't work and extend the platform accordingly. Sometimes this was done with the assistance of project funding, and sometimes without. In all cases we preferred (and still do) utility over complicated design. KISS.

We have now ceased work on the FLOSS Manuals platform to develop Booki and I think its fair to say that while the FM platform is fully functional and productive, we see it not as a 'finished' work but as a prototype and our primary feature-set design document for the current Booki development.

This short pre-history also explains our preferred development methodology. Although we do have milestones and we have a pretty clear idea of what we want to build, much of the detail and new ideas are worked out in discussion in IRC. If you wish to contribute to the code base then the process of getting involved is more about engaging with the resources listed below and asking questions than it is about reading our (non-existing) design documentation.

If you wish to help fix existing features please look at the Trac tickets.

You can also read the section 'How You Can Help' if you wish to tackle implementing new features.

The following are the main channels for communication and for getting the code.


IRC : irc.freenode.net #fm-tech
Email : http://lists.flossmanuals.net/listinfo.cgi/booki-dev-flossmanuals.net



Here you will find the repositories for Booki, Objavi and Espri



Primary Install


FLOSS Manuals


Bug Reporting

Bug Reporting - believe it or not, there are people out there that love bug reporting. If you are one of those people - we need you! 

How to Report a Bug

We use the a software called 'Trac' for reporting and managing bug reports. To contribute you must first create an account. You create an account on the Booki Bug Tracking (Trac) site at the following URL:


Once you have done that you will need to open a new 'ticket'. In this instance a 'ticket' is just another word for 'bug report'. You can click on the 'New Ticket' link located at the top right of any page in Trac. If you don't see this link then you are probably not logged in.

You will see a form with several fields :


Here are some tips on what to put in each field:

Summary - give a brief summary of the bug in no more than a dozen words. Keep it brief and descriptive. This in itself is an art!

Reporter - this should automatically display your name and you should not alter this information.

Description - describe the bug in much detail as possible. Be as specific as possible and provide information so that the developers can recreate the same error if possible. Don't worry about supplying too much information - put in here as much as you like. Additionally, if the bug has displayed an error message, copy and paste the entire message at the end of the description.

Type - leave this as 'defect' (bug).

Milestone - leave this as 'Bugs'.

Keywords - add a few keywords to help people find all bugs related to a specific topic using the search system in Trac. You could use keywords like 'registration' if the bug was found during the registration process, 'editing' if the bug while discovered while editing a book etc. You can provide many keywords but make sure they are all separated by a comma

Assign to - leave this blank (used by the developers)

Priority - you can set this as you like, probably someone will come by later (the 'bug manager') and set the priority level again.

Component - probably you will want to leave this set as 'Booki'. Only if you are testing Objavi (the publishing engine) will you need to set this as Objavi.

Cc - leave this as it is displayed. If you wish to be informed of any changes to this bug report then add your Trac username and the end of this list preceded by a blank space.

Once all is filled out press 'Create ticket'...now pat yourself on the back and find more bugs to report!


To understand Booki in more detail lets look at its principle features. The following is a brief description of the main features and some information on the progress so far. The list is not exhaustive and we invite brainstorming on features at anytime (although we want to remain focused on achievable milestones).

partially implemented
One of the most powerful features of Booki is the ability to easily copy and reuse content. Booki will use GIT as the versioning repository for the content. This means we can easily fork books into new versions for reusing, rewriting, translation, or recontextualising the content. Changes can be merged upstream if desired. At the moment versioning is supported but not by GIT. Instead versions as flags set in the database and this is manipulated via the Booki python code.

Book Formatted PDF Output
implemented (Objavi) -- http://objavi.flossmanuals.net
The server side creation of Book Formatted PDF is a pivotal feature of Booki. Booki creates book formatted PDF using the Webkit PDF rendering engine. With Booki if you want to update a book, you edit it in the browser and create another print ready PDF in a matter of minutes. Furthermore, the book formatted PDF supports Unicode, bi-directional text, and reverse binding for printing right-to-left texts on a left-to-right press and vice versa. The formatting engine will output customisable sizes including split column PDF suitable for printing on large scale newsprint.

CSS Book Design
implemented- http://objavi.flossmanuals.net
The PDF rendering engine has CSS support. This changes the language of design from Indesign to CSS - which means any web native can control the design of the book.

implemented - http://objavi.flossmanuals.net
Booki is really a Comprehensive Text authoring environment, one output of which is books. Users can be able to publish to static HTML for linking from a website, to .odt (OpenOffice rich text format), standalone HTML, epub, and screen readable PDF. Other XML, and 'e-book' output options can be developed as Extensions.

Real Time Collaboration Tools
partially implemented
Book Sprints, remote, and asynchronous authoring all have their own communication requirements. Harmonising these into one system is where FLOSS Manuals has done a lot of real world research and Booki will take the best of what we have learned. Booki has tools such as real time edit notifications to see who is editing what at this moment, a real time chat (web / IRC gateway), system level notifications, and chapter status markers. More is to come including book progress indicators, work flow tools, messaging, and live user status listings.

not currently implemented
Booki needs to available in any language where it is needed. Hence we will integrate the mature Pootle code base into Booki to enable localisation of the environment.

not currently implemented
Content can be forked and marked for translation. A translation version of a book will provide link backs to the original material, be placed in a translation work flow, and edited in a side-by-side view where the translator can also see the original source. We are considering a World Wide Lexicon Extension to add machine translation to the work flow

implemented - http://objavi.flossmanuals.net/espri.cgi
Booki is also useful for importing book content. Currently Booki supports the import of Archive.org epubs (1.6 million), Wikibooks (from Wikibooks.org), and any epub online. Currently the Wikiboks importing is very experimental.

implemented -
Booki is installable to run as a web service of locally. Installation can be done from source that will require python knowledge. At a later date Ubuntu and Debian users will be able to easily install Booki using the .deb packages (no knowledge of python required).

Booki Service
implemented - http://www.booki.cc
FLOSS Manuals will itself use Booki for development of manuals about Free Software. We will also run a free Booki service on the domain http://www.booki.cc for those who do not wish to install their own version.

Embed API
not currently implemented
Many users will want to use Booki to author material to host under their own domain. Booki will provide an API similar to the FLOSS Manuals beta API for embedding books with indexes in their own websites. This means users need only cut and paste a few lines of HTML into their website and the book will appear as if hosted under their domain.

User Pages
partially implemented
Booki puts the user in the center of the design. From the users point of view this makes Booki user-centric, not content centric. At the moment the user pages show just the users profile ad the list of books and groups they have created. Later a user page will become homepage when you log in and from here you can monitor changes in books, communicate with others, and participate. From this page you can create books, create and join groups, make announcements about Book Sprints or other activities, track changes on your own or others books, and subscribe to user services.

Dynamic Groups
Booki groups are self associating collections of users that collaborate to write books on a given topic. For example, FLOSS Manuals would be one such group, which aggregates manuals about Free Software. If I want to help others write Free Software manuals I would subscribe to the FLOSS Manuals group.

pariially implemented
Users have personal RSS feeds that can be used to track changes. Books can not yet be syndicated with RSS.

Copyright Tracking and Management
partially implemented
All attributions are currently automated in Booki. We also desire to reduce the overhead for finding the rights holder for any work authored in Booki so the process of obtaining re-license and re-use permission will be partially automated. Meaning that the technical process of managing licenses is taken away from the user, making the permissible reuse of content very easy.

Book Management
In Booki new chapters can easily be added to the Index, redundant ones removed, and the Index can be managed with a drag and drop interface.

License Control
Users can decide the license for any book they create. At a later date Booki will ensure, as far as it is technically feasible (its difficult to prevent simple cut and paste copyright violations), that content from within a Booki content base is not recombined with incompatibly licensed material. Licenses can also be managed on a chapter level. Open content licenses will be used by default.

Core Components

Booki is made from three separate projects - Booki, Objavi, and Espri.


Booki is the core component and what most users refer to as 'Booki'. This component is largely developed by Aco and it looks after user and group management and the creation and editing of books. Booki also houses all the communication tools required for collaborative authoring.

When a user requests a book to be imported Booki sends a request to Espri, Espri then sends Booki a Booki-zip file.

When a user publishes a book Booki sends Booki-zip files to Objavi for creating outputting formatted PDF etc.


Objavi is the output ('publishing') engine. Objavi 1 was developed by Luka Frelih in 2008, Objavi 2 in 2009 by Douglas Bagnall. Objavi takes Booki-zip files from Booki and currently outputs to PDF (web readable, book formatted, and newsprint formatted), ODT, and epub.

Objavi is primarily used for generating book formatted PDF which is uploaded to a print on demand service. The PDF layout is controlled by CSS, supports bi-directional text and is unicode compliant.

Objavi can be accessed directly as a web service or accessed via the Publishing tab in the edit interface of any book.


Espri is the importer - handling the import of books from the internet and converting them to Booki-zip. It was developed in 2009 by Douglas to import manuals from FLOSS Manuals but it now has assumed the role of a general importer. Espri prefers to receive either Booki-zip files directly, or epubs. If neither of these are available then Espri manages the conversion of the content into Booki-zip through external conversion scripts.

Espri currently does the following :

1. Archive.org Import : import directly from Archive.org. In this case the user inputs the Archive.org ID for a book into the appropriate field on their user page. Booki then sends this request to Espri. Espri will request an epub for the book directly from Archive.org. Espri then converts this epub into Book-zip and sends it back to Booki.

2. Wikibooks Import : imports books from wikibooks.org. In this case the user must input a Wikibooks URL into the appropriate field on their user page. Booki then sends this request to Espri. Espri then launchs Wiki2epub which in turn retrieves the files from wikibooks.org, creates an epub and sends this file to Espri. Espri then creates a Booki-zip file and sends this to Booki.

3. Import Epub : imports any epub online. The user enters a URL for an epub into the appropriate field on their homepage. Booki then sends this request to Espri. Espri retrieves the epub, creates a Booki-zip and hands this back to Booki.

Technology Used in Booki

Booki is Python based, built with the (bare) Django framework, and using JQuery for dynamic page elements. Postgres is our prefered database, and we use a Redis database for caching.

XHTML is the file format for content. Booki uses the Xinha WYSIWYG editor for creating content. epub is increasingly becoming the default import format for content coming from external projects.

The PDF generation requires Webkit as a rendering engine - we have chosen this above other PDF rendering engines since Webkit has unicode, CSS, and bi-directional text support. However we would rather use the Mozilla Firefox layout engine (NGLayout & XPFE projects but usually known somewhat incorrectly as Gecko) and this will be implemented as the default renderer in time.

There are other tools required for some outputs from Objavi, for example the rendering of .odt requires OpenOffice to be installed with unoconv.

The format for exchanging books between the three core components (Espri, Objavi, and Booki) is a format defined by the project called Booki-zip. Booki-zip contains mostly xhtml files and a JSON file.

The Web/IRC gateway optionally require a standalone IRC service running locally.

For development we will use Apache2 for http delivery, but other deployments can use any http service.

To be Implemented

Content will eventually be stored in GIT. Pootle will also eventually be integrated into the core of Booki, and hence interface texts will be kept in Portable Object files (.po). Rabbitmq will be implemented to manage message queues (such as import or export requests). We would like to implement OpenID for logins.


Each release will be as source. Beta and later releases will also be available as Debian .deb packages. The license is GPL2+.


Django - http://www.djangoproject.com/
JQuery - http://jquery.com/
Postgres - http://www.postgresql.de/
Redis - http://code.google.com/p/redis/
Xinha - http://trac.xinha.org/
epub - http://www.idpf.org/specs.htm
Webkit - http://webkit.org/
Mozilla Layout Engine - http://www.mozilla.org/newlayout/
- http://git-scm.com/
Pootle - http://translate.sourceforge.net/wiki/pootle/index
OpenID - http://openid.net/
Rabbitmq - http://www.rabbitmq.com/


Created in Booki : http://www.booki.cc
Source URL : http://www.booki.cc/booki-user-guide/_v/1.0/edit


div#PageBreak {
height:0px !important;

body {
background: #fff;
color: #000;
font-family: "fontin sans";
font-size: 10.2pt;

p {
/* text-align: justify;*/
/* white-space:pre-line; */
font-size: 10.2pt;

div.page-footer .page {
font-size: 8pt;

color: #000;
text-decoration: none;
font-style: Italics;
border-bottom: dotted 1px #777;

h1 {
font-size: 23pt;
page-break-after: avoid;
page-break-before: always;

h2 {
font-size: 15pt;
page-break-after: avoid;

h3 {
font-size: 12pt;
page-break-after: avoid;

div.chapter-number {

div.captionBox p{
font-size: 8pt;
font-style: italic;

ul, ol, blockquote{
page-break-inside: auto;

page-break-before: always;
height: 7em;
display: block;

page-break-after: auto;

z-index: -66;
margin-left: -1000pt;

color: #000;

h1 .initial{
color: #000;
font-size: 1.6em;
font-weight: normal;

float: right;
margin-left: 8pt;

font-size: 0.8em;
margin: 0;

display: block;
page-break-before: always;
/* page-break-after: always;*/
/* text-transform: uppercase; */
font-size: 20pt;

body > .objavi-subsection:first-child,
body div#chapter-1 .objavi-subsection:first-child{
page-break-before: avoid;

.objavi-subsection .initial {
font-size: 1em;
color: #000;

font-size: 36pt;
font-weight: bold;

/*h1.first-heading {
page-break-before: avoid;

margin-top: 70%;
font-size: 20pt;
text-align: center;
page-break-after: always;
page-break-before: avoid;
max-width: 700pt;
font-weight: normal;

padding: 1em;

/* TOC ******************************/
table {
float: none;

table.toc {
/*border: 1pt dotted #999;*/
width: 95%;

table.toc td{
padding-left: 0.5em;

td.chapter {
padding: 0 0.5em;
text-align: right;

table.toc td.pagenumber {
text-align: right;

td.section {
padding-top: 1.1em;
font-weight: bold;

/* End TOC **************************/

pre, code, tt {
font-family: "Courier", "Courier New", monospace;
font-size: 9.8pt;

pre {
/*overflow: hidden;*/
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */

img {
height: auto !important;
text-align: center;

table {