I’ll start this chapter by telling you a story of a big mistake I made. I wrote an 80,000 word book. I set up my AsciiDoc authoring tools and wrote it in AsciiDoc. I figured I’d get to the publishing setup when I was done writing.

When I finished writing, and editing the book, it was time to produce it for ePub and publish on Smashwords. I had been making PDFs as I wrote, so the PDF was fine. But I needed ePub for the eBook. So I started learning how to convert the plain text into an eBook (ePub format). How hard can it be, I thought. The free app I tried was in beta and did not work for me. I got lots of errors. I had a deadline and I did not have enough time to debug such a large book to find out what I had done wrong.

This is why I now suggest iterations of writing small batches of content and testing how it renders (the production system) so that if you have a problem, you can narrow it down. You know what you just created in a period of a week or so; it is still fresh on your mind. This small batch approach avoids having months of effort that you have to dig through to find an error. I tried large batch, waiting until the end of the project and having to debug much more content to find an error I added that broke the book.

So in a hurry, I abandoned my plan to use free tools and went to Microsoft Word. I ran into issues trying to get that into an eBook. I spent days trying to figure out what was wrong before giving up on Microsoft Word. Next, I opened the Word file using Mac Pages. It turns out that Pages has a publish to ePub function. I used that, and made an ePub file. But Smashwords said there were issues so it did not go into all their network of distributors.

The lesson I learned was configure your eBook publishing at the start of the project. Use a small book, like I did for PDF, and iterate your tests until you figure out how to publish successfully to ePub. Then write the 80,000 words confident that the production process will work. I’m recommending you test all that up front so you can feel at peace it will work at the end.

Since then, I’ve learned how to use Sigil for creating the ePub from the HTML that AsciiDoctor renders. It is easy and reliable. My experience is what leads me to recommend that you figure out your production process at the start so you can practice it as you write.

So let’s install the tools you need.

I’ll be frank. This is the point where non-technical people may lose heart and give up. Installing multiple tools can seem overwhelming to some people. I promise it is worth sticking through this part and I’ll walk you through it step-by-step. You don’t have to do this set up for each book project. You only have to do this set up once for each computer you buy.

Here is a list of the apps you need to set up.

  • Asciidoctor

  • Sigil

  • PDF Tools (optional)

I will walk you through it step-by-step.

Install AsciiDoctor

WHY? You need an app to render the AsciiDoc plain text to HTML and other formats.

Asciidoctor works on Linux, OS X (Mac OS) and Windows.

  1. If you did not already read [CommandLine], then go back and read that before continuing.

  2. Open a terminal window and type in the following to check if you already have ruby installed.

    ruby -v
  3. If you see something like ruby 2.2.2p95 (2015-04-13 revision 50295) [x86_64-darwin14] then that means you already have ruby installed. Macs often already have Ruby installed.

  4. If not, then you need to install ruby using the following steps.

    1. Go to the ruby installation page https://www.ruby-lang.org/en/documentation/installation/.

    2. For your operating system (Windows, MacOS, Linux), go to http://rubyinstaller.org and follow their instructions.

  5. Test if your ruby installation worked by running ruby -v again in the terminal.

Once you have ruby installed, then we can install AsciiDoctor.

  1. Ensure you have an internet connection. If you’re behind a company firewall, this is very challenging. If you’re at home, it is easy.

  2. Open a terminal window and type in the following.

    gem install asciidoctor
  3. Test if it worked by typing the following.

    asciidoctor --version
  4. If you see something like Asciidoctor 1.5.4 [http://asciidoctor.org] then it was successful.

On Windows, you have to be in the directory folder where you installed the asciidoctor app for it to run.

Install Sigil

WHY? You need an app to correctly save your book content into the picky format of eBooks. This app makes it easy.

I have found Sigil to be the easiest eBook tool to use with a bit of initial guidance. It is not obvious what to do with it the first time however, so I’ll tell you how.

  1. Go to https://sigil-ebook.com to read about the app.

  2. To download, go to https://github.com/Sigil-Ebook/Sigil/releases and scroll down to the downloads section.

  3. You should see a list of options (the version number 0.9.6 may change):

    • Sigil-0.9.6-Mac-Package.dmg

    • Sigil-0.9.6-Windows-Setup.exe

    • Sigil-0.9.6-Windows-x64-Setup.exe

  4. Determine if your machine is 32-bit or 64-bit. Most new machines are 64-bit processors in 2017.

    1. For Windows OS, View the System window in Control Panel.

    2. Click Start, and then click Run.

    3. Type sysdm.cpl, and then click OK.

    4. Click the General tab. The operating system is displayed as follows: For a 64-bit version operating system, Windows XP Professional x64 Edition Version < Year> appears under System.

    5. If MacOS, click on the Apple menu and then choose About This Mac.

    6. Locate the Processor Name.

    7. Ask Google if the processor name is 64 bit.

  5. Select the Sigil download package that works for your platform. If Mac, use the .dmg. If windows 64 bit machine, select the Windows-x64-Setup.exe version.

  6. Follow normal methods for installing a dmg on Mac or an exe file on Windows.

  7. Look up on Google if you’re not sure.

Install PDF Tools

WHY? You need these tools if you want to create PDF files to go to print for your book.

Installing PDF tools is entirely optional. If you only plan to produce eBooks using ePub or Amazon’s format, you don’t need the ability to render to PDF. I’m using PDF is just to go to print using print on demand providers like https://www.createspace.com.

If you get stuck trying to install Java on your computer, go to Youtube and look for videos of people doing it. You may have an easier time of it following someone’s video instructions.
  1. Download the Java Development Kit (JDK), which includes the Java runtime (and, naturally, an internet connection). You can use any recent JDK.

    1. Go to Java SE download site @ http://www.oracle.com/technetwork/java/javase/downloads/index.html.

    2. Under "Java Platform, Standard Edition" find "Java SE 8" or 9, and click the "JDK Download" button.

    3. Check "Accept License Agreement".

    4. Choose your operating platform, e.g., "Windows x64" (for 64-bit Windows OS) or "Windows x86" (for 32-bit Windows OS).

  2. Install the JDK.

    1. Run the downloaded installer, the *.dmg (Mac) or *.exe (Windows) that you just downloaded (e.g., "jdk-8u{xx}-windows-x64.exe")

    2. Accept the defaults.

    3. Follow the screen instructions to install JDK and JRE.

    4. Check the JDK installed directory by inspecting these folders using File Explorer.

    5. Take note of your JDK installed directory, which you will need in the next step.

  3. Verify the JDK Installation

    1. Launch a terminal or command line window.

    2. Type the following.

      java -version
    3. If you see something like java version "1.8.0_xx", Java™ SE Runtime Environment, then you succeeded.

  4. Install the asciidoctor-fopub app.

    1. Create a folder called asciidoctor-fopub. I put mine here, Users/klanham/Documents/A/asciidoctor-fopub.

    2. Go to https://github.com/asciidoctor/asciidoctor-fopub.

    3. Look for the download button on the right-hand side of the repository page on GitHub.

    4. Select the download button and then select Download ZIP.

      Figure 1. Asciidoctor-fopub App Download Button
    5. Once the download finishes, move the zip file to the asciidoctor-fopub folder you made.

    6. Extract the archive in the asciidoctor-fopub folder.

    7. Open a terminal or command line window and change to the book working folder directory using cd command followed by the file path.

  5. Test that the asciidoctor-fopub app works.


Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview