Don't overthink it (Installment #247)

I volunteered to do a tedious job at work -- copy/paste about maybe 200-400 parameters scattered throughout a group of FORTRAN files. The parameters may be in one of maybe 3 different formats. Also, the parameters came with multiline comments (with each commented line starting with !), and sometimes just big wodges of comments on their own that serve as documentation. The goal was to transform these snippets into something our customer could scan using Excel.

I volunteered to do it because it made no sense for a highly paid developer to do such a menial job; also, I kind of like taking on little challenges like this, developing a new technique or learn some new tools, and seeing how quickly I can rip through them. Then it's just a matter of putting on the headphones, pressing a few keys repetitively so the computer does most of the work, and voila.

I realized that my initial solution for this would be overly complicated, as it always is, and that the exploration process as I groped my way toward simpledom would be haphazard, as it always is. I thought "How can I use Applescript to parse the text? Should I just copy the fragments into Word and use Word's formatting functions? Should I use a text editor with some text formatting Services?" (DevonThink makes a killer set of text-formatting services available to Mac users for free; DevonThink not required to use them.)

I spent about 5 hours over the weekend scarfing up text-formatting Applescript code, messing with text editors, messing with Automator, messing with some copied fragments that I was using as my test case, messing with Applescript in Word (which adds its own complications), and seeing possible workflows getting more complicated.

Sometime around Monday evening my brain settled down and I decided on my workflow:

  1. Copy each parameter and comment into a Word file.
  2. Fix the formatting of each snippet to remove the extra lines, excess ! marks, and insert tab marks judiciously to make importing into Excel easier.
  3. Transform the tab-delimited text into a table using Word's Table>Convert>Text to Table command.
  4. Copy and paste the tables into Excel and format accordingly.

The intent of this workflow brings in what I've mentioned before, about batching similar actions together. With this workflow, I could check each line off as done and move fully to the next set of operations. I could do each set of operations more quickly and efficiently than transitioning from 1 to 2 to 3 to 4 within each file.

#2 gave me the headache, of course, and is where I spent the bulk of my think time. I had on blinders as I was sure I could use some sort of Applescript in Word that would reformat everything in one go, without needing multiple passes. And because I thought it could be done, I thought I had to do it that way.

However, I had set myself a time limit for the R&D, and I had passed it. Time to drop that all-in-one solution. As I looked at the line fragments, I noticed that the bulk of the work would be done in the first line of each multi-line fragment. OK, let's start there.

That shift brought me back to the Agile programming maxim of, "Do the simplest thing that could possibly work." This is when I turned back to Keyboard Maestro; it's not as powerful as QuicKeys (or my beloved Macro Express in the Windows world), but it's quick, dependable, and does the job. In this case, I was using it as a robot typing the keyboard, but that keeps it simple.

That's when I cobbled together my workflow for #2:

  • With the text in Word, select the lines that will be reformatted.
  • Run Joe Kissel's great Clean Up Text script (scroll down the page to read about how to coy and paste his code into the Applescript editor). This script removes all spaces and tabs and removes multiple line breaks, making each fragment a unified paragraph. Kissell's article also tells you how to assign a keystroke to a script.
  • For a multi-line parameter with comments, the bulk of the delete symbols/insert tab action happens in the first line of the reformatted paragraph. So, position the cursor on the first line, and run the Keyboard Maestro macro (assigned to the F19 key) that manually moves the cursor, deletes a character, inserts a tab, etc. and then stops. Because the macro is working within Word, I added keystrokes to take advantage of Word's keyboard-based cursor movements.
  • For the remainder of the ! comment marks now studding the reformatted paragraph, select the entire document and use a simple Word find-and-replace to replace all the ! with " ".

Hm. Well, that still looks pretty complicated, doesn't it? But it's faster than me burning hours to get my head deep into Applescript territory, with delimiters, variables, if-thens, and so on.

The other advantage of this workflow is that this should cover about 80% of the code I'll have to reformat. I now have a base set of actions that I can clone and customize to handle the exceptions.

Anyway, the lesson as always: don't overthink it. Keep it simple.