Ebookama

A small, extensible program to take the pain away from repetitive ebook wrangling

Installation

This program requires node.js v4+ and npm to be installed on your machine. Until we have time to put instructions here, head to Google.

Once you've got node and npm installed, you need to get this repository on your computer. Ways to do that, in order of goodness:

• Fork this repo, then clone your fork to your machine (requires installation and understanding of Git)
• Clone this repo to your machine (requires installation and understanding of Git)
• Download the repo and unzip it. You won't be able to easily update the program when we inevitably fix all the bugs we never thought of.

Now that you have the program on your computer, you need to set it up. Don't worry, it's easy. Open the terminal or command line, navigate to this repo on your hard drive, and run the following command (the $ just means "type this in the terminal and press enter"):

$ npm install

Before you can do anything useful with the program, you'll need to set up your config file. This involves simply copying sample.config.cson to a new file called config.cson.

If you want to run the amzn.js script (see below for reasons why you might (coming soon!)), you'll need to download Kindlegen from here and put it in the root folder of this project. I'm not allowed to host and share it on GitHub.

That's it. You're done.

Usage & Customization

To run Ebookama, type this in your terminal (note the --) and press enter:

npm run ebookama -- "path/to/ebook.epub"

Customization

The fractured state of ebook production practices means that we all have our own way of doing things. This program is written with this fact firmly in mind. You can use Ebookama to do many things, if your JavaScript is up to it. The only places you need to write code are the following, everything else is taken care of for you:

1. config.cson
2. src/modules/transformers.js
3. src/modules/util.js

Note: After changing either 2 or 3, you'll need to run the following in your terminal to compile it to dist/:

$ grunt

If you forget, your changes simply won't be reflected and your new method won’t work.

Let's go through the files one-by-one.

config.cson

Set things up here before running ebookama on your files. This file is in CoffeeScript Object Notation, the CoffeeScript version of json. The main reason for this, apart from the welcome lack of superfluous punctuation, is that cson supports multi-line strings, which is pretty useful for our purposes. There are several top-level keys: amzn, ignore, metadata, and regexes:

amzn: # set up the <guide> data for kindlegen conversion, grouped by filename (ecluding the .epub)
  'Book':
    toc_file: 'Book-1.xhtml'
    toc_id: 'contents'
    start_reading_file: 'Book-3.xhtml'
    start_reading_id: 'full-title'

ignore: # TBD
  html: []
  css: []
  opf: []

metadata: # grouped by filename (excluding the .epub) – used to populate your ebook's opf file
  'Book':
    title: 'Book'
    subtitle: 'A lovely read'
    ebookISBN: '9781234567890'
    author: 'John Writer'
    editor: 'Louise Editor'
    illustrator: 'Andy Illustrator'
    translator: 'Wendy Translator'

regexes: # should be self-explanatory
  css: [
    {
      find: '\\s*-epub-ruby-position:over;\\n\\s*color:#000000;\\n'
      replace: ''
    }
    {
      find: '\\s*color\\s*: #000000;'
      replace: ''
    }
    {
      find: 'font-family\\s*:\\s*"Minion Pro", serif;'
      replace: ''
    }
  ]
  opf: []
  xhtml: [
    {
      find: ' \\. \\. \\.'
      replace: '&nbsp;.&nbsp;.&nbsp;.'
    }
    {
      find: ' –'
      replace: '&nbsp;–'
    }
  ]

src/modules/transformers.js

This is where you shine. Write any javascript you can think of here, within the following limitations:

• Not a limitation, almost the opposite: Ebookama is proudly ES6. All your code will be run through Babel, so please feel free to use arrow functions, destructuring, for of loops, even generators... go wild.
• Methods are categorized by filetypes: currently, css, html (or xhtml), and opf. If your new method is under one of these properties in the transformers object, it will be run against all files of that type; and if it's not under one of these properties, it won't get called at all.
• Every method receives one argument – the file it’s getting run against, as a string. Every method must return one value – the file it’s getting run against, now modified (or not!), as a string.

Here is an example of a transformer that changes every instance of the words “quite” and “good” in every .html and .xhtml file in your ebook:

html: {
  // ... other transformers

  hyperbolic: doc => doc.replace('quite', 'amazingly').replace('good', 'incredible'),

  // ... other transformers
}

In old-fashioned JavaScript, that would be:

html: {
  // ... other transformers

  hyperbolic: function(doc) {
    return doc.replace('quite', 'amazingly').replace('good', 'incredible');
  },

  // ... other transformers
}

There are some examples in src/modules/transformers.js already. If you don't want to use them, get rid.

File API

Ebookama exposes a custom file API for your convenience. So far, it has 2 methods, as follows:

getFileList()

• To use it in your transformers.js, just call it like getFileList().
• returns: an array of file entries, which follow the structure as outlined here. So, for example, to get an array of full file paths, call getFileList().map(fileEntry => fileEntry.entryName)

getContentOf(fileNameSearch: String)

• To use it in your transformers.js, call it with a string representing some part of the filename you wish to read. So, for example, to get the content of all CSS files, call getContentOf('.css'). To get the content of Chapter-1.html, call getContentOf('Chapter-1.html'). Or getContentOf('ter-1.h') if you’re feeling lucky.
• returns: a Promise, that resolves with an array of strings that are the content of each file matched. So, for example, the following would log the entire text content of main.css:

getContentOf('main.css').then(contentArray => console.log(contentArray[0]));

// or if you're being really ES6-y
getContentOf('main.css').then(([content]) => console.log(content));

src/modules/util.js

Utility functions, for your transformers to use. I highly recommend that these be pure functions all.

An example of a utility function that you might use throughout your transformers.js:

const insertBefore = function(doc, locator, str) {
  const i = doc.indexOf(locator);
  return doc.substr(0, i) + str + doc.substr(i, doc.length);
};

Note: remember to add the names of your new util functions to the export list at the bottom of src/modules/util.js.

Where does the name come from?

• Ebook
• Ebook automation
• Kama Sutra