google-code-prettify tutorial

perm url with updates: http://xahlee.org/js/google-code-prettify/index.html

Google-code-prettify Examples

Xah Lee, 2009-06-20

This page gives some examples using Google-code-prettify technology, and evaluate its quality.

Google-code-prettify (GCP) is a javascript library that syntax color computer lang source code in html. It does the job on the fly. Project page at: http://code.google.com/p/google-code-prettify/.

Basic Use

It is very easy to use. All you have to do is to download the javascript files. Then, in your web page, add these lines:

<link rel="stylesheet" type="text/css" href="gcp/prettify.css">
<script type="text/javascript" src="gcp/prettify.js"></script>
<body onload="prettyPrint()">

Then, in places you want your source code to be colored, wrap it with a “pre” tag like this:

<pre class="prettyprint">
x = 1+1;
# something something
</pre>

Advantages:

  • Your lang source code is still readable in raw html. This means, if you need to edit it or update it, it can be easily done.
  • Easy to use. You don't need to run some script to generate span markup in the first place.
  • Easy to install. Works in all major browsers.
  • Support all major langs (e.g. any lang with C-like syntax). Also support some wiki syntax, auto link urls.

Disadvantages:

  • Requires js turned on. If js is not turned on in browser, readers won't see colored syntax.
  • The coloring is heuristic based. Quite often it is wrong. if your source code processes html or url, has lots regex, or in general is a web application such as Javascript or PHP, it will confuse GCP and sometimes the displayed source code text may be botched.
  • If your lang has complex syntax, such as Perl, PHP, Ocaml, then GCP doesn't handle it well due to it being generic and heuristic based.
  • Often, it makes your web page a invalid HTML.
  • If your source code contain chars that needs to be html encoded, such as the “less than” sign in if (x<y) {print 4;}, then you still need to html encode the “less than” sign. If you don't, it's a invalid html. This introduces complexities in 2 aspects. (1) you still need to pre-process your source code before inserting into your html page. If you don't, it can be a potential problem for some languages that may screw up your browser's ability to display the text. (2) How the js code colors “&lt;” is a heuristic guess.

Examples

Here are some examples with different languages. For comparison, each example has a version using html span, done by htmlize elisp package with emacs.

Java:

Python:

Perl:

Emacs Lisp:

Conclusion

Google-code-prettify is suitable only for small number of lines or for non-critical writing such as on wiki or blogs. It is probably not suitable for online documentation of a computer language or a book length tutorial.

It will very often create bad coloring or even truncate your source code in the display when your lang has lots regex, or if your code deals with processing url/html/xml/css/javascript, or if your lang has complex syntax, such as perl, or niche langs such as Mathematica or OCaml. For code over 2 hundred lines, it also takes a second to load. In comparison, bulky html with span wraps that has more coloring and correct syntax is still instaneous.

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs