SHJS - Documentation

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

Place each source code snippet in a pre element. (Currently SHJS cannot highlight code which is not in a pre element.) The pre element must be in the class sh_LANGUAGE, where LANGUAGE specifies the programming language in which the source code is written. For example, for C++ the correct class is sh_cpp.

<pre class="sh_cpp">
#include &lt;iostream&gt;

using namespace std;

int main(int argc, char ** argv) {
  cout &lt;&lt; "Hello world" &lt;&lt; endl;
  return 0;
}
</pre>

The following table shows the correct class to use for each language:

Language	HTML class
Bison	`sh_bison`
C	`sh_c`
C++	`sh_cpp`
C#	`sh_csharp`
ChangeLog	`sh_changelog`
CSS	`sh_css`
Desktop files	`sh_desktop`
Diff	`sh_diff`
Flex	`sh_flex`
GLSL	`sh_glsl`
Haxe	`sh_haxe`
HTML	`sh_html`
Java	`sh_java`
Java properties files	`sh_properties`
JavaScript	`sh_javascript`
JavaScript with DOM	`sh_javascript_dom`
LaTeX	`sh_latex`
LDAP files	`sh_ldap`
Log files	`sh_log`
LSM (Linux Software Map) files	`sh_lsm`
M4	`sh_m4`
Makefile	`sh_makefile`
Objective Caml	`sh_caml`
Oracle SQL	`sh_oracle`
Pascal	`sh_pascal`
Perl	`sh_perl`
PHP	`sh_php`
Prolog	`sh_prolog`
Python	`sh_python`
RPM spec files	`sh_spec`
Ruby	`sh_ruby`
S-Lang	`sh_slang`
Scala	`sh_scala`
Shell	`sh_sh`
SQL	`sh_sql`
Standard ML	`sh_sml`
Tcl	`sh_tcl`
XML	`sh_xml`
Xorg configuration files	`sh_xorg`

In the head element of your document, include the sh_main.js script and the script for the programming language you are using. (If you have multiple languages in the same document, you can include multiple scripts.) For example, for C++ the correct script is lang/sh_cpp.js, assuming that language-specific scripts are stored in the lang/ directory.
```
<head>
...
<script type="text/javascript" src="sh_main.js"></script>
<script type="text/javascript" src="lang/sh_cpp.js"></script>
...
</head>
```
Also in the head element, include a link to one of the style sheets. You can use the default style sheet (sh_style.css) or one of the style sheets in the css/ directory.
```
<head>
...
<link type="text/css" rel="stylesheet" href="css/sh_nedit.css">
...
</head>
```
Call the function sh_highlightDocument in the onload handler of the document's body element:
```
<body onload="sh_highlightDocument();">
```

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.