# 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.