Writing Like a Geek

A few peo­ple have asked me for more details on my writ­ing process so I fig­ured the eas­i­est thing is to doc­u­ment it here. This about the lit­er­al process of how I put togeth­er my projects.

Editor

Kate in action
Chap­ter 2 in kate

My main edi­tor these days is Kate. Kate is a plain text edi­tor but since it’s part of the KDE project it comes with a huge num­ber of slick fea­tures include vi mode (vi is an unbe­liev­ably pow­er­ful edi­tor once you make it past the learn­ing curve). I use LaTeX markup for every­thing (more on that lat­er).

Project Structure

Each project gets its own fold­er (cur­rent project is named “ham­mer” due to an old work work­ing title). Each chap­ter is split in a cou­ple files but how many depends on my mood when I worked on that par­tic­u­lar piece (you can see in the above screen­shot that the chap­ter is split in four files: one for each of the three scenes and a fourth to put them togeth­er). Files are named with a one-let­ter pre­fix based on the act (A, B, or C), a num­ber (the chap­ter in that act), and a short name describ­ing the point of that file. Each act has its own file that puts the chap­ters in order (named part-A.tex, part-B.tex, and part-C.tex).

Generating Output

LaTeX is a pain to work with direct­ly (it pol­lutes the work­ing direc­to­ry and has no depen­den­cy man­age­ment) but CMake solves both of these prob­lems. CMake doesn’t sup­port LaTeX out of the box, but I hacked togeth­er a mod­ule to man­age 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 pro­duce man­u­script-for­mat­ted out­put for either the whole nov­el or indi­vid­ual acts, the bot­tom three pro­duce type­set con­tent, type­set con­tent for a 6″ x 9″ page (per the require­ments on Lulu), and indi­vid­ual chap­ters (for post­ing to Scri­bophile). The main tar­gets I lever­age are the first four, most­ly because man­u­script for­mats build much faster than non-man­u­script for­mats.

Using LaTeX means I get lots of slick fea­tures when I gen­er­ate the type­set out­put, includ­ing kern­ing, hyphen­ation, lig­a­tures, old-style numer­als, and micro-typog­ra­phy (this adjusts things like the spac­ing with­in words and over­flow­ing into the mar­gins to get white­space that looks uni­form to the human eye). Both type­set and man­u­script forms lever­age LaTeX fea­tures like the csquotes pack­age (auto­mat­i­cal­ly man­ages quote match­ing across lan­guages, includ­ing nest­ed quotes).

Each tar­get can be built in pdf, html, or odt. I can also gen­er­ate “full” ver­sions which include some post-pro­cess­ing on the out­put, but that’s only required for the full man­u­script (required to gen­er­ate Spe­cial Char­ac­ters).

You can com­pare chap­ter 2 of The Howl of the Wolf in both man­u­script and type­set for­mats.

Tools

I use apsell for spellcheck­ing and inte­grate it with cmake using a cus­tom com­mand.

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 cus­tom dic­tio­nary iso­lat­ed to that project. My cur­rent plan is to delete the dic­tio­nary and run a clean spellcheck before pub­lish­ing (just in case I acci­den­tal­ly added a word by mis­take), but for now I can tol­er­ate a few spelling errors.

I have a few scripts to help with analy­sis and file man­age­ment. The most obvi­ous exam­ple is word counts (split­ting 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 post­ing any­thing to Scri­bophile I run it through Pro Writ­ing Aid to help with gram­mar and style. If you haven’t tried Pro Writ­ing Aid give it a shot, the site is amaz­ing (it found the exact same sen­tence being used twice in the same chap­ter; not sim­i­lar, the exact same). I usu­al­ly work through one report at a time, updat­ing my raw files and gen­er­at­ing new out­put as I go to make sure I don’t miss any­thing.

After going through Pro Writ­ing Aid I check for trou­ble­some words. When I’m done clean­ing those up I do one last check through spellcheck and Pro Writ­ing Aid to make sure I didn’t intro­duce new prob­lems.

Once the san­i­ty check is done I spit out the chap­ter in html (eas­i­er than deal­ing with copy/pasting through a pdf) and copy/paste in Scri­bophile.

Special Characters

Sec­tion 11.12 of the The Chica­go Man­u­al of Style’s six­teenth edi­tion rec­om­mends includ­ing a list of spe­cial char­ac­ters at the end of any man­u­script (a spe­cial char­ac­ter gen­er­al­ly being any­thing not found on a stan­dard key­board). Because I’m lazy I want some­thing to do the work for me so I don’t have to track what char­ac­ters I’m using through revi­sions. Let’s make LaTeX track the spe­cial char­ac­ters we use.

Since the glos­saries pack­age sup­ports mul­ti­ple glos­saries we can use a spe­cial one just to track our spe­cial char­ac­ters. Update the pre­mable with some­thing like this:

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

Now we can add any spe­cial char­ac­ters specif­i­cal­ly to this glos­sary with a few extra fields filled out:

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

Notice the descrip­tion and type fields? These pro­vide infor­ma­tion about the sym­bol (in this case, é) includ­ing it’s Uni­code rep­re­sen­ta­tion and they tell LaTeX to put it in the new glos­sary we cre­at­ed in the last step. These fields are crit­i­cal to get the behav­ior we want so no skip­ping steps.

Now we can start putting our \gls{e-acute} tags wher­ev­er we want but that’s pret­ty hacky. Instead let’s add anoth­er glos­sary entry that does the work for us:

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

Now we can write like nor­mal and wher­ev­er we put \gls{cafe} we get a nice­ly for­mat­ted “café.” The last step is to actu­al­ly print the spe­cial char­ac­ters we’re using at the end of our doc­u­ment:

\printglossary[type=special]
Spe­cial char­ac­ter list­ing

Not only can we avoid man­u­al­ly keep­ing track of what char­ac­ters we use while edit­ing, we even include page num­bers where our spe­cial char­ac­ters appear.

Naming Characters (and Places, Groups, Gods…)

I’m awful with names. Actu­al­ly that under­sells how bad I am. I’m the kind of per­son who likes things to be pre­cise and cor­rect from the begin­ning (engi­neer­ing hat) so I don’t even like hav­ing place­hold­ers and call­ing my char­ac­ters Bob, Janet, and Tony. I’ve tried, real­ly, but I keep fid­get­ing and will spend hours try­ing to come up with the per­fect name. Plus even if I some­how move on find/replace can only do so much. If I screw up and talk about how Bbo and Tony are try­ing to one-up each oth­er to take Janet on a date we all know what’s going to hap­pen.

The solu­tion: place­hold­ers. Yeah, even though I hate them they’re still the best option. Let’s look at a prac­ti­cal exam­ple.

\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 stu­pid LaTeX file I just wrote that spits out the fol­low­ing: “Bob and Tony both have a crush on Janet. I’d tell you who gets her in the end but I haven’t actu­al­ly thought that far ahead.” Notice how their names only appear in one place each, where I define the glos­sary entries? This means I can come in lat­er, 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 actu­al­ly thought that far ahead.”

Now I can pick names that are good enough (most­ly ones I bla­tant­ly pil­fer from video games) and I don’t have to wor­ry about find/replace let­ting me down when I go through lat­er with bet­ter names. It’s already helped me once when I real­ized there were two busi­ness­es with “Irv­ing” in their name (cour­tesy of Lloyd Irv­ing from Tales of Sym­pho­nia) so all I had to do was update one entry in my glos­sary files and my name dupli­ca­tion issue went away.