Setting up the Electric Book workflow on Windows

electric-book-tools-setup-windows.md

Setting up the EBW tools on Windows

These steps have worked for me on several machines. Every machine is a bit different, so your mileage may vary.

On OSX? I've written up guidance for installing the EBW tools on OSX here.

1. The first steps are to get Ruby and Jekyll installed. I have a whole separate piece on that here. Go and read that, follow it closely, and come back here when you're done.

2. Download and install PrinceXML. See princexml.com/doc/installing for instructions. Note that this is proprietary software (the only proprietary tool we use). You can try the trial version for free; it adds a watermark to your first page.

3. Install PhantomJS. [Note: this step is only necessary for Electric Book template v.0.15 and earlier. Phantom is not required from v0.16.0] This is necessary for building search indexes for websites. (And, in older repos to Electric Book template version 0.12, for creating PDFs that contain maths.)

   Download the Windows zip file from phantomjs.org and extract it.

   PhantomJS doesn't have an installer. So making it work on your computer involves two steps: saving the exe file somewhere permanent, and listing its location in your PATH. To do this, I recommend:

   1. Create a folder on your C: drive called PhantomJS, and copy the extracted contents of the zip file into it. This should include a bin folder that contains phantomjs.exe.
   2. Add the location ‘C:\PhantomJS\bin’ to your PATH. Your PATH is the list of places where your computer will look for .exe files when you ask it to run a program. So by adding the folder that contains phantomjs.exe to your PATH, you're making it possible for the computer to find it when you send commands to phantomjs. Editing your PATH seems scary at first, but if you're careful it's really easy. Here's a good walk-through.

4. Install Pandoc. This is mostly for exporting to Word, and can be useful to help with converting Word documents to markdown. I recommend downloading and running the official Windows installer at pandoc.org.

5. Install Git for version control. Git isn't easy to understand at first, but it's worth the effort. I recommend both of these two options:

   • GitHub Desktop is good if you're new to Git and you're using GitHub to store your repositories.
   • The official Git for Windows is light and simple, and includes a visual interface (GUI). (Note that you need to install this in addition to GitHub Desktop, even though Desktop does includes its version of Git.

6. Install a good text editor. I like VS Code and Sublime Text 3. Brackets is also good. (Atom is lovely, but may still have a markdown bug that could also affect Brackets and VS Code.)

7. Install Gulp and Graphicsmagick. We use these together to create multi-format images. To do this:

   1. Install Node.js using the offical Windows installer.

   2. Now that Node is installed, to install gulp you enter this from the Command Prompt:

      npm install --global gulp-cli

      (If you need more detail, see the official docs.)

   3. To install GraphicsMagick, you can download the installer from SourceForge. We have had trouble with v1.3.36, which does not actually run after installation. So it may be best to use v1.3.35. (A newer version may have been released in the meantime.)

      Technical note: the Windows installer should automatically include a tool called 'Little CMS'. Little CMS is required for managing colour profiles during image conversions. It is not installed by default on Mac when installed with Homebrew.

Dependencies for creating apps

Creating apps is more complex than other output formats, so this is for advanced users.

If you want to create app versions of your books, you will need to install:

1. Apache Cordova
2. Android Studio for Android apps
3. Visual Studio for Windows apps

The Electric Book scripts will use these in the background, and for some build steps you'll have to use these directly.

You cannot create Apple apps on a Windows (or Linux) machine.

Note: GraphicsMagick 1.3.36 has a problem on Windows as reported here. When you try to run it, you may get the error 'the application was unable to start correctly (0xc0150002)'. For now, you may need an earlier version.