(part 1) when scratching an itch becomes a stupid timesink

How adding a keyboard short-cut for the equation editor in google docs turned in to a week long mission into foreign lands such as google closure, chrome extension API, XPCwrappers and even a bit of C++

(For the title of the post I was trying to think of the suitable case in the "scratching an itch" software development analogy for when the problem starts consuming time and effort for little reward, and I thought of maybe an over engineered robotic itch scratcher anyway I gave up and abandoned the analogy)


Anyway, on to the purpose of this post... During my recent revision period for some exams I was using Google Docs to produce solutions documents to past exam papers, to share with other students for revision. There were a few "early attempt" documents which were full of embarrassing wrong answers, so I was keen to use some system that keep hidden my past mistakes with the best version.

I did try a few other online and offline platforms, such as zoho, libreoffice, various flavours of latex online but as collaboration was important google docs seemed a natural choice.

One of the key features of the google docs "word" document editor was the insert Equation feature. The Equation editor is a pretty basic TeX based widget that leverages the Chart API to produce nicely formatted formulae. Printing and offline use were not a requirement so google docs was a good compromise.

However.... After a while it becomes clear that docs is a quite limited environment, there are bunch of little things that start to become annoying when using it day-in day-out, some of these are;

1. There is a bug in the editor where some pages are not editable immediately, and the page needs to be refreshed to give it "a kick". (this seems to be a problem on firefox)
2. Caret and scrolling problems. This is actually a problem in blogger as well, where the text insertion point jumps around and doesn't correspond to where text actually appears when entered.
3. There are many little responsiveness issues where you are left hanging mid-word for the screen to update.

But one thing that started to annoy me, which I felt that I might be able to do something about was the fact that there is not keyboard short cut for the inserting a new equation menu item.

No bloody short-cut, gah!

It becomes quite tiresome if the document is interspersed with text and formulae to keep moving from keyboard to mouse to insert equations. This is also a factor due to the limitation on the size of expressions that are possible in the chart API, hence frequently its required to break-up large expressions into smaller chunks with separate equations to be inserted.

If you have ever used greasemonkey or worked with any browser extensions for firefox or chrome, then you would imagine that it would be a trivial project to bind an event listener to some suitable keystroke and trigger a Javascript function.

So as soon as the exams were over, I decided that this is what I would do.

In terms of selecting which keystroke to use, I was wary of treading on other UX patterns keystrokes, as many of the ctrl-somekey combinations are well associated with other functions, however I had recently been using the http://stats.stackexchange.com version of stackexchange and they are using a $ and $$ based token system to delimit phrases that should be interpreted as TeX. (They use mathJax which actually looks pretty cool)

Obviously that is slightly different in that the $$ and $ are used to delimit a string which is subsequently replaced with a formatted equation on parsing, whereas google docs is actually initiating the "insert equation" widget in the flow of typing.

However it seemed to work quite well, i.e. I decided to use a $ character followed shortly by another $ character to initiate the "insert equation" widget.

So basically, I catch keydown events, and if I see a $ (the ascii char with decimal keyCode 52, with the shift key set) I store a global with a setTimeout to clear the variable after 1 second. If the global has been set, then I insert the new equation.

Google uses the tab key to jump out of the equation editor, which seems to work fine, so there was no apparent need to handle the equation editor exit pattern.

However at this point things started to go pear shaped... (see part 2)