One of my goals with this blog is to post more code snippets. It is something I did occasionally on my old blog. It's one of those things that should be simple, but ends up being a bit of a pain. I've used a Wordpress plugin in the past, but I was never fully satisfied with it. Lately I've seen some other programming blogs I read using a client side Javascript solution. After some digging the two "ready for prime time" packages I found were Chili and SyntaxHighlighter.

This is a comparison of those two. If you feel I missed another package let me know in the comments.

Chili

License: MIT
Includes: jQuery(21KB), core (7KB), PHP CSS(1KB), PHP JS (37KB)

One of the things I initially liked about this package was that it used jQuery, which is my new favorite Javascript library, although then I realized, as much as I use jQuery on my web apps, I don't really have a need for it on this blog. So having to include it was just additional baggage.

I'm not crazy about the overall size. The PHP "recipe" is 37KB alone. Much bigger than any of the others. Another drawback is the weak documentation. The Chili page is long, dominated by the change log - which is good information, but placed poorly. A simple "how to use Chili" section with code samples - USING THE FREAKING PACKAGE would be nice [Update July 24, 2007 - Chili has a new quickstart page. I'll leave me rant here for entertainment purposes].

You know, something like:

1) Include jQuery and the Chili Javascript files. Your paths may be different.

<script type="text/javascript" src="/js/jquery.js"></script>
<script type="text/JavaScript" src="/js/chili-1.8b.pack.js"></script>

2) Chili can automatically find the recipes it needs - simply tell it where to look.

<script id="setup" type="text/javascript">
    ChiliBook.automatic = true;
    ChiliBook.recipeFolder     = "chili/js/";
    ChiliBook.stylesheetFolder = "chili/css/";
</script>

3) Wrap your code and tell Chili which recipe to use. Remember to replace & with &amp; < with &lt; and > with &gt;

<pre><code class="php">
<?php
    class family_friendly() {
        function censor($word) {
            return '*' . gettext($word) . '*';
        }
    }

    function get_license() {
        return 'Creative Commons';
    }

    printf('This guide is released under the %s license.<br />', get_license());
    printf('Seriously, Chili author, if you are reading this, move 95% of the %s onto secondary pages and include this simple tutorial.<br />', family_friendly::censor("crap"));
?>
</code></pre>

That's all you need. Thats all the information 99% of your users need. I shouldn't have to figure out which of the five example pages I need to view source on to get this working. Especially when they have such confusing names as: examples-all-combinations.html (which appears to be a joke, that I don't get), examples-dynamic-automatic-adhoc.html, examples-dynamic-automatic-adhoc-metaobjects.html, examples-static-automatic-adhoc.html. Huh?

I'm done with my rant. I'll say some nice things about Chili now. One of the features that is really cool is that it's completely automated. You simply wrap your code with the correct tag and Chili does the rest. Also since it is a plugin for jQuery it degrades nicely, leaving the code less pretty, but still completely readable.

Now that I said something nice I can go back to ranting. The samples provided with the download have Google Ads in them. I can understand having them on the actual site, but in the downloaded samples it seems a bit tacky to me. Even worse the ads are all food related, that is when they're actually in English. I assume the author simply took the pages directly from the site and rolled them into the download, but I still find it annoying.

Also the author makes the claim "You just put the code you want highlighted in a code tag AS IS". Then not even 300px later he states "Always escape the content of the code element for HTML: at least substitute any & by &amp; and any < by &lt; in this order. If you want to highlight HTML you also need to escape any > with &gt;." So it isn't exactly "AS IS".

SyntaxHighlighter

License: GNU
Includes:CSS(4KB), core(11KB), PHP (5KB)

SyntaxHighlighter is obviously a much lighter solution. It too has separate includes for each language, called brushes here. The instruction page is also well done. In addition to highlighting and formatting the code SyntaxHighlighter adds buttons that allow the user to view plain, copy to clipboard and print. On the downside it isn't automated like Chili, although you could certainly use jQuery, or some custom javascript to execute HighlightAll on a page load. Like Chile you need to encode the < character (but not > or &).

1) Include the core files and the brushes for any language you want. Your paths may be different.

    <script type="text/javascript" src="/syntaxhighlighter/js/shCore.js"></script>
    <script type="text/javascript" src="/syntaxhighlighter/js/shBrushPhp.js"></script>
    <script type="text/javascript" src="/syntaxhighlighter/js/shBrushJScript.js"></script>
    <script type="text/javascript" src="/syntaxhighlighter/js/shBrushXml.js"></script>

2) Put this at the end of your file. If you put it before the code you want highlighted it won't work.

<script class="javascript">
dp.SyntaxHighlighter.ClipboardSwf = "syntaxhighlighter/js/clipboard.swf";
dp.SyntaxHighlighter.HighlightAll("code");
</script>

3) Wrap your code and tell SyntaxHighlighter which brush to use. Remember to replace < with &lt;

<pre name="code"  class="php">
<?php
    class Highlighters() {
        function result($highlighter) {
            switch ($highlighter) {
               case "chili":
               default:
                  return "FTL";
               case "syntaxhighlighter":
                  return "FTW";
            }
        }
    }

    $highlighters = new Highlighters();
    printf("Chili is a nice effort, but just not for me.  Chili %s", $highlighters->result("chili"));
    printf("I am going to give SyntaxHighlighter a shot.  SyntaxHighlighter %s", $highlighters->result("syntaxhighlighter"));
?>
</pre>

Wrap Up

If you're already using jQuery and want to highlight non-PHP then Chili is worth checking out. For this blog I'm going to give SyntaxHighlighter a shot. I think end result of SyntaxHighlighter is nicer looking and the additional buttons are useful features.

If you have any experience with either feel free to write about it in the comments.