Highlighting Code Snippets

Windows Live Writer seems to be a popular blogging client, especially with the Code Formatting plugin. After the last post however, its shortcomings became very apparent. The writer’s formatting is fickle and limited. The code formatter is messy and unreliable (it refused to highlight the code in the last post).

It’s sad that with all our technology, we still have yet to make very reliable WYSIWYG text editors. That means writing HTML directly, or finding an intermediate markup language to do the job. So I setup and tried two lightweight markup language for writing blog posts.

reStructuredText

reStructuredText has been officially accepted as the Python inline code documentation formatter. It currently doesn’t handle code formatting, but it’s in the works. This fellow notes that Pygments already has a way to integrate with reStructuredText. It took a lot of finagling (and realizing my PATH was wrong), but I got it working.

Here’s what I did (perhaps not the best way)

• Download Docutils and unpack it.
• Run setup.py build which creates a build directory
• Move all the files in the build/scripts-2.5 directory to the build/lib directory
• Running rst2html.py will now work, but it can’t do highlighting yet
• Download the Pygments source and .egg file for the proper Python version
• Randomly run a bunch of commands on the Pygments source and/or .egg until it somehow gets installed as a Python lib (yes, that’s pretty much what happened)
• Find the rst-directive.py file amidst the Pygments source, copy its contents, and paste it into rst2html.py right before the last line of that file.

reStructuredText will now recognize the sourcecode directive. There are other options you can set in that Pygments directive code (such as enabling the :linenos: option).

asciidoc

asciidoc works right out of the box, but needs GNU source-highlight for code highlighting (although I guess you could hack it to use whatever else you want). You can download a very old Windows binary, but the latest version has many more highlighters that aren’t compatible with older versions.

Since source-highlight needs some of the boost libraries. I didn’t have much hope in building it with MinGW, so I just went with the Cygwin build. The build process is pretty painless:

• Using the Cygwin setup, download the boost libraries under the Devel category.
• Downloaded the latest release of source-highlight
• Unpack it into a path without spaces (the build with fail otherwise)
• Fire up the Cygwin shell and cd into the directory
• 10+ minutes of ./configure, make, and make install, and you’re done

Running asciidoc.py with the -s option removes the HTML header/footers, and source-highlight inlines all its CSS with the code. After getting it working, I recreated the last post in asciidoc format, and replaced the post with the generated output.

It looks really nice.

Blogging with asciidoc

All-in-all, asciidoc is very usable and powerful, but it does a lot more than I wanted, and the syntax isn’t as natural as I would like.

By default asciidoc and the blogspot styling don’t completely get along. The listingblocks don’t have the overflow: auto style, and it takes some tweaking to fix it for both Firefox and IE. There is also a lot of extra spacing added due to several layers of tags, but that’s not hard to fix.

I started an asciidoc syntax configuration for jEdit.

I wonder if there’s a way to create a tool like this for blogspot.