EBT - EBook Tools

(Note that the tools on this page turned out to be reasonable, but not a total sucess.)

In March 2014, I published an eBook via Amazon. It was a technical programming book, and needed:

  • a mixture of fonts
  • program code with indentation (spaces at the left)
  • chapter numbers, section numbers, sub-section numbers
  • Bullet points, numbered lists.

From reading Amazon's docs, and a few blogs of other experiences (see below), I thought that trusting Word to export properly was risky, so I decided to work in plain text. I knew a bit about HTML, so could handle the formatting. Here, I'll describe some programs I wrote to help me simplify my writing (the main one renumbers chapters and sections), and will provide a download and some (scrappy) documentation. I'm not selling them, and would rather use them than document them for others - but I hope someone finds them useful.

Written in Pascal

Firstly, you might say that I have re-invented the wheel. Possibly. I know about markdown, and the Gnu/Linux command-line tools, such as sed. However, I had some programs I wrote years ago, and they were easy to adapt. I also wanted them to be easier to use than e.g sed.

I wrote them in Pascal (Delphi), and they run on Windows - to use on Gnu/Linux, you could recompile them on Linux with the Lazarus IDE. (With minor changes to do with end-of-lines). Lazarus also runs on Windows, if you don't have Delphi.

Windows Command Line

Don't use it! These tools use the command line, but please avoid running them in that manner. Instead, put them in a bat file, and run it with a double-click. If you don't know about bat files, here is an example, showing the Amazon KindleGen eBook creator in use.

Using e.g. notepad, create a file with these 3 lines:

 
rem: my book opf file is cppordinary 
c:\kindlegen\kindlegen.exe cppordinary.opf -c0 -verbose 
pause 
The first rem: line is optional. Rem: means 'remark' - you can put a comment here

The second line is what you would normally enter at the command prompt.

The third line - pause - stops the black window from closing, so you can read any error messages.

Save the file as e.g. runkindlegen.bat, in the same folder as the files it has to work on. From now on, run the file from Windows Explorer.

Example of One Tool: replacebatch

The usage is similar for each tool, so we will look at one in detail. (I assume you have downloaded it, etc). It has 3 'command-line arguments' (sometimes called parameters) and often these are file names. Our task (let's invent one) is to replace every blank line by </p><p> and to replace every h3 by h2. Here is a bat file:

rem: toy demo example 
replacebatch.exe mybook.txt  editdemo.txt newbook.txt 
someOtherTool.exe newbook.txt  someSettings.txt new2.txt 
pause 
The documentation (below) tells us that replacebatch has 3 parameters: an input file (it exists already), a command file, which has settings, etc, and an output file, which is the result of the edits.

Often, we use the new output file as the input to another tool (someOtherTool above) so we have a 'pipeline' of tools . (We might have used the pipe feature of Windows or Linux, but it is useful to have the intermediate stages in files, so we can debug the output).

Let's look at what could be in editdemo.txt:

STARTCOMMANDS 
h3 
h2 
CRLFCRLF 
CRLF</p><p>CRLF 
ENDCOMMANDS 
All of these command files must start and end with STARTCOMMANDS and ENDCOMMANDS. Don't litter extra spaces around - they will have a wrong effect.

The other lines are pairs of strings. The first 2 say 'replace every h3 by h2 throughout the file'. We could also have used html angle brackets - this would be safer, in case we have an h3 in our normal text. The next 2 lines use the 'magic word' CRLF, which stands for the end of line marker (it is unlikely that we have CRLF in our book. We want to find an empty line (2 end-of lines together) and put a close para and start para there, between the 2 ends. The 2 strings can hold any text, including spaces. There can be any number of string pairs in a command file. Alternatively, you could run replacebatch several times in a pipeline. Sometimes, this helps you to see what is going on.

Finally, the 3rd parameter is an output file name, which will be overwritten if it exists already. File names can also be paths. If the file name contains spaces, wrap the names in quotes, as in "my file.txt".

In the example bat file in the download, you see how it can be used to create bulleted lists etc

Replacebatch is the simplest tool, and the most complicated one does auto-numbering of chapters, sections, subsections, and also generates a contents and a nav file.

Incidentally, any line starting with COMMENT is ignored, so you can use it for commenting the commands, as in:

COMMENT increase the heading size  

Choosing Magic Words

When you want to create (for example) bulleted lists, you would prefix each item by a magic word, which your tool would replace by 2 'item' tags. The main thing is to choose some unusual text which does not occur in your book. I chose 'ii' but it might be neater to choose a '-' at the start of a line, which you can do by CRLF-.

Chapter and Section Numbering

The xxxxx tool generates numbers. You do not put actual numbers in your book. There are some magic words (changable) which introduce chapters, sections, and sub-sections. For example, we might have a resulting output file containing:

Chapter 3: Some Stuff
     etc   
3.1  My Life  
        etc
3.1.1  Childhood 
           etc
 

3.1.2 Teenage years 
      etc
 

3.2  Work 
    etc
  
The tool can also produce a 'nav' file, and a table of contents which can be pasted into your book.

Indexing

This tool is untested, but you might find it useful. You can put marker characters round a word. Every such word is placed in an index - a word can appear several times of course. Clicking on an index entry takes you to the word.

Programming Textbooks

Two of the tools I found useful to handle the insertion of program code excerpts automatically, from a code file.

Downloads

Here is the documentation.

Here are the programs, etc

You can run the bat files on the chapters provided.

here is a link to my 'C++ For Ordinary People' . It costs around 2-3 dollars, depending on where you live.

The source code is in the zip - look at the dpr files.

Let me know if you find them useful.

Which Editor if you use plain text?

There are lots of nice editors: pspad, notepad2 etc. I chose Word! It has spellchack, different fonts etc. Of course, when you export as plain text, then you lose the fonts, but it made my programming book easier to create. If you don't want different fonts, it is still worth thinking about running your stuff through Word (or clone) for the spell/grammar check.

Sites I Used

Here are some sites with excellent info on Amazon eBook publishing:
Helen Hanson
About.com - Jennifer Kyrnin
Rhys Tate
CJ - Easy As Pie!
Jeff Friesen