One of the annoying things about using Instiki (which is, I should say, not specific to Instiki but goes for anything where the processing goes on "over there") is that to see what a page really looks like, I need to send it to the server and have a look. This can be irritating as I might need to do several minor tweaks to get things looking right, and I can never figure out the indentations first go on lists. In addition, using the it's all text addon for firefox, I can edit pages using Emacs. It's extremely annoying to have to essentially close the file and reopen it for a minor edit (okay, I have Emacs running in server mode so it doesn't take long, but I lose my place in the buffer and have to load in any modes again). Fortunately, the formatter for Instiki can run as a standalone process.

---

Unfortunately, I needed to install a few things to get it working and I don't have root privileges on my work machine. So I had to download and install ruby locally. The ftp site is [ftp://ftp.ruby-lang.org/pub/ruby/]. I chose the latest 1.8.x branch as that is what is used by Instiki. To configure:

./configure --prefix=$HOME/local --enable-shared

Then make, make test, make install. As there was already a version of ruby installed on my system, I made sure that I did a rehash after installing ($HOME/local/bin is early in my path so $HOME/local/bin/ruby gets picked up before /usr/bin/ruby, but only once the shell knows about it).

Next, get the rubygems package. Installation was fairly simple:

export GEM_HOME=$HOME/local/lib/ruby/gems/1.8
ruby setup.rb

However, ruby has to be told about rubygems so that leads to:

export RUBYOPT=-rubygems

Of course, these environment variables go in ~/.zshenv as well.

To get maruku, simply

gem install maruku

That doesn't put the scripts anywhere useful, so a couple of symbolic links are necessary:

ln -s ~/local/lib/ruby/gems/1.8/gems/maruku-0.6.0/bin/marutex ~/local/bin
ln -s ~/local/lib/ruby/gems/1.8/gems/maruku-0.6.0/bin/maruku ~/local/bin

Next stage, itex2MML. Being no stranger to bzr, I use that to get the latest version. Somewhere sensible, I did:

bzr branch  http://golem.ph.utexas.edu/%7Edistler/code/itexToMML/ itexToMML

Then in itexToMML/itex-src, the standard

make
make ruby
make install_ruby

So long as all has gone to plan, this will have installed everything in the correct places - i.e., the local directories not the global ones. Note that if you forgot the --enable-shared flag when compiling ruby, you'll get some errors here which will take a long time to track down. Fortunately, the internet is great (and Gentoo doubly so).

With a bit of luck,

maruku -m itex2mml

Will now work.

Next step is to configure Emacs to run this as a compiler script, much as it currently does for latex. Fortunately, I have already written an overlay of the tex-mode.el file to enable easy switching for different outputs for TeX/LaTeX documents (you can get a copy here). It was easy enough to add an option for maruku to this. The problem with using TeX mode for maruku documents is, of course, the fact that they are not a variant of TeX. Where this is really noticable is when using font-lock. Fortunately, Jason Blevins has written a markdown-mode for Emacs which has plenty of good font-locking already written. So when editting a maruku document, we use the TeX major mode but load the markdown font locks.

To do this, we need to load the markdown lisp file and also define a function to switch the font lock defaults (thanks to stackoverflow for this one!).

(require 'markdown-mode)

(defun markdown-font-locks ()
  "Set the font lock to that of markdown mode."
  (interactive)
  (set (make-local-variable 'font-lock-defaults)
       '(markdown-mode-font-lock-keywords))
  (set (make-local-variable 'font-lock-multiline) t)
  (setq font-lock-mode-major-mode nil)
  (font-lock-fontify-buffer)
  )

Ideally, we want these to be triggered automatically when loading a file from Instiki. There's some code on the n-lab site that should help.

It is also worth turning off a few error messages in maruku, namely the one that complains about not creating links. This is because maruku tries to make links out of wikilinks. Instiki protects against this by escaping the wikilinks before they go through maruku. Although this would be a possibility, as this is simply a preview, it's best just to ignore them. Ideally, this should be a switch to maruku. At the moment, my ruby knowledge is enough to know how to comment something out!

--- to_html.rb  2009-09-24 16:12:22.000000000 +0200
+++ to_html.rb~ 2009-09-24 16:13:19.000000000 +0200
@@ -712,9 +712,9 @@
            a.attributes['href'] = url if url
            a.attributes['title'] = title if title
        else
-#          maruku_error "Could not find ref_id =     #{id.inspect} for #{self.inspect}\n"+
-#              "Available refs are     #{@doc.refs.keys.inspect}"
-#          tell_user "Not creating a link for ref_id =     #{id.inspect}."
+           maruku_error "Could not find ref_id =     #{id.inspect} for #{self.inspect}\n"+
+               "Available refs are     #{@doc.refs.keys.inspect}"
+           tell_user "Not creating a link for ref_id =     #{id.inspect}."
            return wrap_as_element('span')
        end

@@ -730,8 +730,8 @@
            a.attributes['title'] = title if title
            return a
        else
-#          maruku_error"Could not find url in     #{self.inspect}"
-#          tell_user "Not creating a link for ref_id =     #{id.inspect}."
+           maruku_error"Could not find url in     #{self.inspect}"
+           tell_user "Not creating a link for ref_id =     #{id.inspect}."
            return wrap_as_element('span')
        end
    end