SHJS - Documentation

To highlight source code in an HTML document using SHJS, perform the following steps:

Note: All SHJS CSS classes, JavaScript functions and file names begin with the prefix sh_ to avoid conflicts with other names in your HTML document.

Automatic loading of language scripts (new in version 0.5)

As of version 0.5, you can instruct SHJS to load language-specific scripts automatically, so that they do not require <script> tags. To do this, call sh_highlightDocument with two arguments, PREFIX and SUFFIX. For every <pre> tag with class CLASS, SHJS will automatically load a language-specific script from the URL formed by concatenating PREFIX, CLASS, and SUFFIX.

For example, for the following HTML document, SHJS will automatically load the language file located at the URL lang/sh_java.js.

<html>
<head>
<script type="text/javascript" src="sh_main.js"></script>
<link type="text/css" rel="stylesheet" href="css/sh_nedit.css">
</head>

<!--
PREFIX = 'lang/'
SUFFIX = '.js'
-->
<body onload="sh_highlightDocument('lang/', '.js');">

<!--
CLASS = 'sh_java'
PREFIX + CLASS + SUFFIX = 'lang/' + 'sh_java' + '.js'
                        = 'lang/sh_java.js'
-->
<pre class="sh_java">
public class X {}
</pre>

</body>
</html>

In the next document, SHJS will load the language file sh_cpp.min.js from the current directory:

<html>
<head>
<script type="text/javascript" src="sh_main.min.js"></script>
<link type="text/css" rel="stylesheet" href="css/sh_nedit.min.css">
</head>

<!--
PREFIX = ''
SUFFIX = '.min.js'
-->
<body onload="sh_highlightDocument('', '.min.js');">

<!--
CLASS = 'sh_cpp'
PREFIX + CLASS + SUFFIX = '' + 'sh_cpp' + '.min.js'
                        = 'sh_cpp.min.js'
-->
<pre class="sh_cpp">
class X {};
</pre>

</body>
</html>

Note that the language-specific scripts must be located on the same host as the HTML document from which they are loaded.

Adding support for new languages

SHJS comes with definitions for highlighting more than 30 different languages. If your favorite language is not among them, you can create a new language definition.

SHJS uses the same file format for defining languages as GNU Source-Highlight. This format is defined in the source-highlight manual. Briefly, each language construct (keywords, variables, strings, etc.) is specified by a string pattern (usually a regular expression) and given a name. When highlighting the language, SHJS will place every instance of a language construct in an HTML span element; its class attribute will be the name of the construct with a sh_ prefix (e.g., sh_keyword). These span elements are then highlighted by the document's style sheet. (Note that a construct with the name url is somewhat magical: SHJS will turn it into an HTML hyperlink.)

Almost any language definition that works for source-highlight will also work for SHJS. However,source-highlight uses Boost regular expressions, while SHJS relies on JavaScript regular expressions. SHJS is capable of converting some simple Boost regular expressions to JavaScript (for example, SHJS converts Boost word boundaries to JavaScript word boundaries), but in general you should avoid using regular expression constructs not supported in JavaScript. For example, avoid the use of Boost's lookbehind operator, as there is no equivalent in JavaScript.

Once you have defined the language, you must convert it to the JavaScript format used by SHJS. You will require the sh2js.pl script from a source distribution of SHJS. The sh2js.pl script is written in Perl and requires the Parse::RecDescent module.

Suppose your new language definition is contained in the file foo.lang. Then the following command will generate the JavaScript file needed by SHJS:

perl sh2js.pl foo.lang > sh_foo.js

You can then reference the sh_foo.js file in your HTML document. You should place source code snippets in a pre element with class="sh_foo".

Creating new themes

The easiest way to create a new highlighting theme is to customize the sh_style.css file in the top-level directory of the SHJS distribution.

Copyright © 2007, 2008 gnombat@users.sourceforge.net GPL Logo SourceForge.net Logo