No Recommended Reading today, and I know you’re sad about it. I’ve got a lot of interesting things to share, I assure you, but for the time being I thought I would sit on them (i.e., I don’t really have time or interest to putz with it today) and prattle on about something else: programming.

Now, it should be noted at the outset that I am not a programmer, not do I have any pretense to being any good at the code I do write. I will admit that what I write is more or less effective, but that’s not to say it’s particularly well-written (although I do try to follow what patterns and practices I picked up working as a tech writer, listening in on heated debates about code style during end-of-week retrospectives). But I’m writing this as someone who is not a programmer for people who aren’t, either, but whom I think should nevertheless learn to code anyway.

The other day I had occasion to pull out an old RaspberryPi 2 that my dad gave me years and years ago and try to get it up and running again (now that I have an external monitor) to test a work thing. (While I admit that I do work at a tech publisher, and work with writer-programmers, I maintain that learning to code is just as useful in non-technology adjacent fields, if not more so.) By this point, that version of the Pi is a little too old, slow, and underpowered for what I wanted to do with it, but getting it back up and running was fun, like a little puzzle. The stakes were low – if I didn’t get this thing going, it wasn’t going to affect my job or my relationship with this particular author – but it was, importantly, a way to stretch a different part of my brain that I usually get to stretch. All of which is to say, even outside the strict confines of improving my “productivity” or “value” at work, it was a gratifying experience all the same. And so a sub-thesis of this is that learning to program can be fun, and working on some programming something or other can be a fun way to break up an otherwise boring day.

SIDEBAR: My computational lit/digital poetics professor from UMass Boston is teaching a short digital poetics workshop, if you’re interested in that sort of thing. I can say nothing but good things about Dr. Bertram and their teaching.

I suppose the point of the RaspberryPi story is not the Pi itself, but rather what that led to: annoyed with nano, one of the easier terminal/command line file editors, I spent a little time later that day working through the first couple of chapters of a book on vi and Vim (apologies for the small work-plug). In fact, I wrote the first little bit of this article in vi before heading back to Atom (because I love it, and the terminal window was too small and I was too lazy to change the font settings). And although this new knowledge is more of a curiosity for the time being, it nevertheless will help me down the road: we use git to keep the source files for the books we publish, and when you’re doing a merge, what do you write your comments in but…vi!

Perhaps a better example: when page breaking a book (i.e., when ensuring that there aren’t words hyphenated across pages, that images and figures are appropriately sized, that widows and orphans are appropriately dealt with), one of our main strategies, since our backend is ultimately HTMLBook, is to add a keep-together class to a span containing the text we want to push to the next line.

For example, in HTML:

<p>I have complete confidence in his discretion, and he had orders, if he were dissatisfied, to proceed no further in the matter. You will excuse these precautions, but I am a man of somewhat retiring, and I might even say refined, tastes, and there is <span class="keep-together">nothing more unaesthetic</span> than a policeman.</p>

Or in asciidoc:

I have complete confidence in his discretion, and he had orders, if he were dissatisfied, to proceed no further in the matter. You will excuse these precautions, but I am a man of somewhat retiring, and I might even say refined, tastes, and there is [.keep-together]#nothing more unaesthetic# than a policeman.

(Quoting from The Sign of Four by Arthur Conan Doyle)

Either way, it’s a lot of keystrokes, unless… you can write just a little code to do it for you!

Working in Atom, my “hacking” language to work on this “hackable” editor is Javascript. I’ve worked in and around web technologies since I was a little kid, but Atom is not only written in Javascript, but also Coffeescript, which is a whole other pickle. But in any case, knowing just enough Javascript to learn just enough Coffeescript enabled me to write just a little code, and then use a keybinding such that whenever I click “Cmd-shift-K”, the keep-together class is added to whatever text I have selected – even if there are multiple selections!

For asciidoc files, it looks as simple as this:

# I separated this out into its own function, since I use it for a number of different purposes
wrapAdocTag = (selection, tag, selectTag) ->
  wrapped = "[.#{tag}]##{selection.getText()}#"
  selection.insertText(wrapped)
  if selectTag == true
    selection.selectLeft(wrapped.length - 2)
    selection.clear()
    selection.selectRight(tag.length)

# Add a "keep-together" class
atom.commands.add 'atom-text-editor', 'asciidoc:kt-keep-together', ->
    editor = atom.workspace.getActiveTextEditor()
    scope = editor.getRootScopeDescriptor()
    if `scope  == '.source.asciidoc'`
      selections = editor.getSelections()
      for selection in selections
        wrapAdocTag(selection, "keep-together", false)

I can’t tell you how much time this saves me at work (really: I didn’t make it through enough projects without it to get a sense of how much time it previously took). It saves me so much time, in fact, that when I come across similar issues, I have time to write code to solve them, as opposed to banging my head against my desk every time I need to add a snippet.

And again, this was a fun distraction from the work. Page breaking can be a pretty mind-numbing exercise, especially when it’s a 400-page technical book, but being able to take a break to do something different with my brain – while still being productive enough that I didn’t feel bad about doing it on the clock – helped a lot.

I suppose, in the end, it comes down to tools. There is the old adage about the hammer and everything else being a nail, and I think a lot about this in terms of my writing life, in terms of how the tools writers use affect their work (e.g., Hemingway’s newspaper cables or Nabakov’s index cards or Jane Austin’s fan, which I’m ashamed to have just recently learned about). The cool thing about knowing just a little bit of coding is that you can then go on and create whatever tools you need. And I mean this in some strong sense.

For example, in most of my non-work writing life I write prose. I tend to get overwhelmed when it comes to big projects in some ways, and I get really fucking annoyed when large Word documents take forever to load, search, or scroll. So instead I moved to writing in asciidoc (see here), and with the include:: syntax, I’m able to break larger works down into more manageable pieces, and go from there. And while I have defintiely gone overboard with this (e.g., a story which was originally 100 secitons of 100 words, whose containing folder was a frightful mess to sort through), this has overall made my work, I think better, since I am now able to focus on discreet pieces of writing and make them (hopefully) better.

As an aside, this also allows me to work in sentences or phrases as needed. Sometimes, to get a passage where it needs to be, it's helpful to have syntactical or other units all on their own lines -- not unlike Nabakov's notecards, in a way. For example:

At the hardwood table atop new hardwood floors
in the house at the bottom of the block
in the county town of Creve Coeur,
the family of four sits down to
Shabbas dinner,
all the children home.

Especially when I want to write rhythmically (though the above passage needs work, I agree), being able to compose in this way and then have it output as regular, paragraph-broken prose (e.g., there are no line breaks in the output) is super helpful.

I suppose I should say that there are some dangers (e.g., I just fell down a too-big rabbit hole because of the dark-theme syntax highlighting which I’m still not 100% happy with and wasted at least a good fifteen minutes), but overall knowing just a little can go a long way.

So why bother learning how to code?

In the end, it’s learning how to do enough to build enough little programs and snippets to make your life just that much easier so you can focus on whatever it is that you really want to focus on (in my case, at least theoretically, writing). It’s learning enough so that you don’t have to bother IT or your tech tools guy every time something goes a little amiss. It’s a way to pass time and stretch your brain.

Dare I say, sometimes, it’s even kind of fun.

Brief plug: Though I am not really ready to restart the how-to-asciidoc project just yet, if you’re interested in playing with this stuff and want to try Atom, here are some useful little snippets like the above that you should feel free to play around with.