Adding SmartyPants to Instiki
October 20, 2006 at 11:18 PM by Dr. Drang
I’ve been using Instiki to hold project notes at work, and it’s worked out well. I can zip around from note to note, print out notes for when I’m going to be away from a computer, and access it remotely through an ssh tunnel. I chose Instiki partly because it’s a Rails application, which makes it all modern and cool, but mostly because it allows me to use Markdown to format the notes. I’ve really come to love Markdown and I write everything I can in it: reports, notes, email, and these blog posts.
Because Instiki is written in Ruby rather than Perl, Instiki can’t use John Gruber’s canonical Markdown—it uses a Ruby implementation known as Bluecloth. (Redcloth is Ruby’s implementation of Textile, which is also available in Instiki.) Actually, Instiki doesn’t use the standard Bluecloth. It uses its own tweaked version, called, with great cleverness, “bluecloth_tweaked.rb.” I haven’t looked into the source code to see what the tweaking is, but I’m guessing it’s an addition or two to handle WikiWords.
Sadly missing from Instiki is a version of SmartyPants, Gruber’s almost-as-good-as-Markdown program for transforming plain ASCII quotation marks, apostrophes, and dashes into typographically correct glyphs. Ruby has an implementation of SmartyPants called RubyPants, but Instiki doesn’t use it. Since I use SmartyPants in conjunction with Markdown in all my other writing, this omission ate at me—I got tired of seeing " and -- in my notes.
Eventually I broke down and started digging a bit into the Instiki code to see where and how I could insert RubyPants. It turned out to be surprisingly simple, just two added lines and the presence of the RubyPants library.
First, the library. I added RubyPants to my overall Ruby system by installing it with gem: sudo gem install rubypants. I believe you could also download and unzip rubypants.rb and put it in Instiki’s lib directory, but I haven’t tested that. (I just realized that I wrote the phrase “unzip rubypants” without seeing it as a joke. I need to step away from the computer more.)
Next, the two added lines of code. Open up bluecloth_tweaked.rb in Instiki’s lib directory. Near the top are a set of require lines. Add one more require so it looks like this:
require 'digest/md5'
require 'logger'
require 'strscan'
require 'rubypants' # this is the added line
Now scroll down to the bottom of the to_html method and add the line that does the RubyPants transformation. When you’re done it should look like this:
# Now swap back in all the escaped characters
text = unescape_special_chars( text )
@log.debug "After unescaping special characters: %p" % text
text = RubyPants.new(text, 1).to_html() # this is the added line
return text
end
The second argument to the new method tells RubyPants to change double hyphens (--) into m-dashes, which is how we used to write our term papers back in the typewriter days. In Gruber’s SmartyPants, this is the default behavior, but you can also choose the more TeX-like transformation of double hyphens into n-dashes and triple hyphens into m-dashes. The RubyPants default—which you get if you omit the second argument to new—is to do the TeX transformation. Both SmartyPants and RubyPants refer to the TeX transformation as “old-school” in their comments, but I’m pretty sure typewriters are older than TeX.
In any event, with very little effort my wiki notes now look the way they should.
