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.

Special Characters

Section 11.12 of the The Chicago Manual of Style’s sixteenth edition recommends including a list of special characters at the end of any manuscript (a special character generally being anything not found on a standard keyboard). Because I’m lazy I want something to do the work for me so I don’t have to track what characters I’m using through revisions. Let’s make LaTeX track the special characters we use.

Since the glossaries package supports multiple glossaries we can use a special one just to track our special characters. Update the premable with something like this:

\newglossary[spg]{special}{sps}{spo}{Special Characters}

Now we can add any special characters specifically to this glossary with a few extra fields filled out:

\newglossaryentry{e-acute}{
  name = \'{e},
  description = {e with acute [U+00E9]},
  type = special,
  sort = eacute
}

Notice the description and type fields? These provide information about the symbol (in this case, é) including it’s Unicode representation and they tell LaTeX to put it in the new glossary we created in the last step. These fields are critical to get the behavior we want so no skipping steps.

Now we can start putting our \gls{e-acute} tags wherever we want but that’s pretty hacky. Instead let’s add another glossary entry that does the work for us:

\newglossaryentry{cafe}{
  name = {caf\gls{e-acute}},
  description = { }
}

Now we can write like normal and wherever we put \gls{cafe} we get a nicely formatted “café.” The last step is to actually print the special characters we’re using at the end of our document:

\printglossary[type=special]
Special character listing

Not only can we avoid manually keeping track of what characters we use while editing, we even include page numbers where our special characters appear.

Naming Characters (and Places, Groups, Gods…)

I’m awful with names. Actually that undersells how bad I am. I’m the kind of person who likes things to be precise and correct from the beginning (engineering hat) so I don’t even like having placeholders and calling my characters Bob, Janet, and Tony. I’ve tried, really, but I keep fidgeting and will spend hours trying to come up with the perfect name. Plus even if I somehow move on find/replace can only do so much. If I screw up and talk about how Bbo and Tony are trying to one-up each other to take Janet on a date we all know what’s going to happen.

The solution: placeholders. Yeah, even though I hate them they’re still the best option. Let’s look at a practical example.

\newglossaryentry{first-guy}{
  name = {Bob},
  description = { }
}
\newglossaryentry{second-guy}{
  name = {Tony},
  description = { }
}
\newglossaryentry{girl}{
  name = {Janet},
  description = { }
}
\gls{first-guy} and \gls{second-guy} both have a crush
on \gls{girl}.  I'd tell you who gets her in the end but
 I haven't actually thought that far ahead.

That’s from a stupid LaTeX file I just wrote that spits out the following: “Bob and Tony both have a crush on Janet. I’d tell you who gets her in the end but I haven’t actually thought that far ahead.” Notice how their names only appear in one place each, where I define the glossary entries? This means I can come in later, change Bob to Brad, and after I process the file again I end up with: “Brad and Tony both have a crush on Janet. I’d tell you who gets her in the end but I haven’t actually thought that far ahead.”

Now I can pick names that are good enough (mostly ones I blatantly pilfer from video games) and I don’t have to worry about find/replace letting me down when I go through later with better names. It’s already helped me once when I realized there were two businesses with “Irving” in their name (courtesy of Lloyd Irving from Tales of Symphonia) so all I had to do was update one entry in my glossary files and my name duplication issue went away.