Writing a (Technical) Book in an IDE

I find myself writing again more, in particular writing technical books. For this I am using a number of tools, some of which I’ve described in Writing a Ruby Related book(let) on LeanPub.

In this post I focus on the writing itself including the setup I use. When starting fresh, I use the zip file with a default content provided by LeanPub. When unzipped, the folder structure looks like this:

% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.txt
    ├── chapter2.txt
    ├── chapter3.txt
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

2 directories, 7 files

I have used Markdown in previous books and am now using Markua (a markup format created by LeanPub). Since both are similar and many editors & IDEs identify the file type by the file name suffix, I use ‘.md’ as the suffix for the files. Also, I find renaming the files ist easier than reconfiguring editors. To do this I use rename:

% rename -g  -s .txt .md  "a_potential_book/manuscript/chapter*.txt"
% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.md
    ├── chapter2.md
    ├── chapter3.md
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

On a Mac rename can be installed using Homebrew:

brew install rename

Now the file Book.txt needs to be updated, to also list the ‘*.md’ files:

ls *.md > Book.txt

With this set up, I import the folder into RubMine, and have a look at ‘chapter2.md’:

Notice this line

![Palm Trees](palm-trees.jpg)

This is the Markua (and Markdown) way of to insert an image (‘palm-trees.jpg’ in this case) into the text using the cation ‘Palm Trees’. In terms of RubyMine the image file is a resource — and it would be handy to be able to open it with just a click. Here’s how to configure this in the IDE:

1. 320Hover the mouse pointer over the folder name ‘resources’ and
2. Open the context menu with a right click:
   
3. Open the sub menu entitled ‘Mark Directory as ▸’, and click ‘Resource Root’
   

Now, if you CMD-click the file name in the text, the image is displayed. Nice.

For my Ruby related book, I created a sub directory within ‘resources’ named ‘code’. Any files inside that folder will now also be found by the IDE and opened, when CMD-clicked.