Writing Like a Geek

A few people have asked me for more details on my writing process so I figured the easiest thing is to document it here. This about the literal process of how I put together my projects.

Editor

Kate in action
Chapter 2 in kate

My main editor these days is Kate. Kate is a plain text editor but since it’s part of the KDE project it comes with a huge number of slick features include vi mode (vi is an unbelievably powerful editor once you make it past the learning curve). I use LaTeX markup for everything (more on that later).

Project Structure

Each project gets its own folder (current project is named “hammer” due to an old work working title). Each chapter is split in a couple files but how many depends on my mood when I worked on that particular piece (you can see in the above screenshot that the chapter is split in four files: one for each of the three scenes and a fourth to put them together). Files are named with a one-letter prefix based on the act (A, B, or C), a number (the chapter in that act), and a short name describing the point of that file. Each act has its own file that puts the chapters in order (named part-A.tex, part-B.tex, and part-C.tex).

Generating Output

LaTeX is a pain to work with directly (it pollutes the working directory and has no dependency management) but CMake solves both of these problems. CMake doesn’t support LaTeX out of the box, but I hacked together a module to manage LaTeX projects.

create_target(wolf-A "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files_A}" FALSE)
create_target(wolf-B "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files_B}" FALSE)
create_target(wolf-C "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files_C}" FALSE)
create_target(wolf   "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files}"   TRUE)

create_target(wolf-pub   "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files}" FALSE)
create_target(wolf-lulu  "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files}" FALSE)
create_target(wolf-scrib "${CMAKE_CURRENT_SOURCE_DIR}" "${tex_files}" FALSE)

The first four lines let me produce manuscript-formatted output for either the whole novel or individual acts, the bottom three produce typeset content, typeset content for a 6″ x 9″ page (per the requirements on Lulu), and individual chapters (for posting to Scribophile). The main targets I leverage are the first four, mostly because manuscript formats build much faster than non-manuscript formats.

Using LaTeX means I get lots of slick features when I generate the typeset output, including kerning, hyphenation, ligatures, old-style numerals, and micro-typography (this adjusts things like the spacing within words and overflowing into the margins to get whitespace that looks uniform to the human eye). Both typeset and manuscript forms leverage LaTeX features like the csquotes package (automatically manages quote matching across languages, including nested quotes).

Each target can be built in pdf, html, or odt. I can also generate “full” versions which include some post-processing on the output, but that’s only required for the full manuscript (required to generate Special Characters).

You can compare chapter 2 of The Howl of the Wolf in both manuscript and typeset formats.

Tools

I use apsell for spellchecking and integrate it with cmake using a custom command.

add_custom_target(spellcheck)
foreach   (file ${spellcheck_files})
    add_custom_command(TARGET spellcheck
                       COMMAND ${ASPELL} -t -p ${CMAKE_SOURCE_DIR}/aspell_dict check ${file})
endforeach(file)

If you don’t speak geek, this runs the entire project through aspell using a custom dictionary isolated to that project. My current plan is to delete the dictionary and run a clean spellcheck before publishing (just in case I accidentally added a word by mistake), but for now I can tolerate a few spelling errors.

I have a few scripts to help with analysis and file management. The most obvious example is word counts (splitting chapters/acts across lots of files makes this hard).

sh ../chapwc.sh 
A-00  3015+1+0 (1/0/0/0) Total
A-01  3688+0+0 (1/0/0/0) Total
A-02  2920+0+0 (1/0/0/0) Total
A-03  2471+0+0 (1/0/0/0) Total
A-04  2412+0+0 (1/0/0/0) Total
A-05  2718+0+0 (1/0/0/0) Total
A-06  1401+0+0 (1/0/0/0) Total
A-07  1117+0+0 (1/0/0/0) Total
...

All changes are tracked using git.

Posting

Before posting anything to Scribophile I run it through Pro Writing Aid to help with grammar and style. If you haven’t tried Pro Writing Aid give it a shot, the site is amazing (it found the exact same sentence being used twice in the same chapter; not similar, the exact same). I usually work through one report at a time, updating my raw files and generating new output as I go to make sure I don’t miss anything.

After going through Pro Writing Aid I check for troublesome words. When I’m done cleaning those up I do one last check through spellcheck and Pro Writing Aid to make sure I didn’t introduce new problems.

Once the sanity check is done I spit out the chapter in html (easier than dealing with copy/pasting through a pdf) and copy/paste in Scribophile.

Version Control for Fun and Profit

Keeping track of old versions of your work is one of those things you don’t appreciate until you have it. Most people keep old versions with a mishmash of file names (novel.doc, novel-backup.doc, novel-backup2.doc, novel-backup-september-2015.doc, …) or using a service like Google Drive or Dropbox. These solutions work but to say they’re lacking is an understatement. Enter git.

Git is a piece of software used to track history of source code. While it’s fine-tuned for this behavior it’s still phenomenal at tracking changes in projects that are structured similar to software. If your project has the following properties git makes an excellent choice:

  • work is stored in plain text (i.e., non-binary files)
  • files are small to medium-sized
  • files are human-readable

Since I use LaTeX all these conditions are met (most word processors have an option to store contents in flat files which gets you most of the way here).

So how useful is git? Think about the backups spread across different services and folders with God-only-knows what names. Count how many you have and compare it to the history of my project.

$ git log --oneline | wc -l
177

177 versions at the time of this post, all of which are time-stamped with metadata about what actually changed. The last two commits look like this:

commit 42bf73d45dfe7fea13996ef9e3b2cdd0e122dc0a
Author: K.P. Wayne
Date:   Sun Jan 29 20:02:52 2017 -0700

    Polish up first part of chapter 1 using Pro Writing Aid

commit 297b676edc97643f901be6f6d0f846546534f2d5
Author: K.P. Wayne
Date:   Sun Jan 29 18:54:26 2017 -0700

    Work in feedback from Scribophile

Not only is backing up offsite trivial, but each backup contains the entire history of the project. As of right now my entire repository, meaning the full history of my project, is a whopping 652 kilobytes; less than half the space of a floppy disk.

You can also mark specific versions with symbolic names (the git term for this is a tag). This makes it trivial to see what changed between two different versions.

git diff –color-words scrib-bk1-a01..master bk1/A-01mine.tex

In fairness git has a learning curve and last time I checked most gui tools ranged from awful to bad (coworkers assure me this has changed). A simpler option is mercurial and Joel Spolsky put together a simple tutorial for anybody unfamiliar with version control.

It’s not for everybody and I haven’t tested git with popular tools Scrivener but if it fits in your workflow give it a go.