<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
<html>
|
|
<head>
|
|
<title>SHJS - Documentation</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<link rel="stylesheet" type="text/css" href="../css/sh_nedit.min.css">
|
|
<script type="text/javascript" src="../sh_main.min.js"></script>
|
|
<script type="text/javascript" src="../lang/sh_html.min.js"></script>
|
|
<script type="text/javascript" src="../lang/sh_sh.min.js"></script>
|
|
</head>
|
|
|
|
<body onload="sh_highlightDocument();">
|
|
|
|
<div id="heading"><h1 id="documentation">SHJS - Documentation</h1></div>
|
|
|
|
<div id="main">
|
|
|
|
<p class="first">
|
|
To highlight source code in an HTML document using SHJS, perform the
|
|
following steps:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Place each source code snippet in a <code>pre</code> element. (Currently SHJS
|
|
cannot highlight code which is not in a <code>pre</code> element.) The
|
|
<code>pre</code> element must be in the class
|
|
<code>sh_<var>LANGUAGE</var></code>, where <var>LANGUAGE</var> specifies the
|
|
programming language in which the source code is written. For example, for C++
|
|
the correct class is <code>sh_cpp</code>.
|
|
|
|
<pre class="sh_html">
|
|
<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>
|
|
</pre>
|
|
|
|
The following table shows the correct class to use for each language:
|
|
|
|
<table id="classes">
|
|
<tr>
|
|
<th>Language</th>
|
|
<th>HTML class</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Bison</td>
|
|
<td><code>sh_bison</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>C</td>
|
|
<td><code>sh_c</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>C++</td>
|
|
<td><code>sh_cpp</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>C#</td>
|
|
<td><code>sh_csharp</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>ChangeLog</td>
|
|
<td><code>sh_changelog</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>CSS</td>
|
|
<td><code>sh_css</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Desktop files</td>
|
|
<td><code>sh_desktop</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Diff</td>
|
|
<td><code>sh_diff</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Flex</td>
|
|
<td><code>sh_flex</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>GLSL</td>
|
|
<td><code>sh_glsl</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Haxe</td>
|
|
<td><code>sh_haxe</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>HTML</td>
|
|
<td><code>sh_html</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Java</td>
|
|
<td><code>sh_java</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Java properties files</td>
|
|
<td><code>sh_properties</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>JavaScript</td>
|
|
<td><code>sh_javascript</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>JavaScript with DOM</td>
|
|
<td><code>sh_javascript_dom</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>LaTeX</td>
|
|
<td><code>sh_latex</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>LDAP files</td>
|
|
<td><code>sh_ldap</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Log files</td>
|
|
<td><code>sh_log</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>LSM (Linux Software Map) files</td>
|
|
<td><code>sh_lsm</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>M4</td>
|
|
<td><code>sh_m4</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Makefile</td>
|
|
<td><code>sh_makefile</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Objective Caml</td>
|
|
<td><code>sh_caml</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Oracle SQL</td>
|
|
<td><code>sh_oracle</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Pascal</td>
|
|
<td><code>sh_pascal</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Perl</td>
|
|
<td><code>sh_perl</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>PHP</td>
|
|
<td><code>sh_php</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Prolog</td>
|
|
<td><code>sh_prolog</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Python</td>
|
|
<td><code>sh_python</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>RPM spec files</td>
|
|
<td><code>sh_spec</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Ruby</td>
|
|
<td><code>sh_ruby</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>S-Lang</td>
|
|
<td><code>sh_slang</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Scala</td>
|
|
<td><code>sh_scala</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Shell</td>
|
|
<td><code>sh_sh</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL</td>
|
|
<td><code>sh_sql</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Standard ML</td>
|
|
<td><code>sh_sml</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Tcl</td>
|
|
<td><code>sh_tcl</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>XML</td>
|
|
<td><code>sh_xml</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Xorg configuration files</td>
|
|
<td><code>sh_xorg</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<li>
|
|
In the <code>head</code> element of your document, include the
|
|
<code>sh_main.js</code> 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
|
|
<code>lang/sh_cpp.js</code>, assuming that language-specific scripts are stored
|
|
in the <code>lang/</code> directory.
|
|
|
|
<pre class="sh_html">
|
|
<head>
|
|
...
|
|
<script type="text/javascript" src="sh_main.js"></script>
|
|
<script type="text/javascript" src="lang/sh_cpp.js"></script>
|
|
...
|
|
</head>
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
Also in the <code>head</code> element, include a link to one of the style sheets.
|
|
You can use the default style sheet (<code>sh_style.css</code>) or one of the
|
|
style sheets in the <code>css/</code> directory.
|
|
|
|
<pre class="sh_html">
|
|
<head>
|
|
...
|
|
<link type="text/css" rel="stylesheet" href="css/sh_nedit.css">
|
|
...
|
|
</head>
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
Call the function <code>sh_highlightDocument</code> in the <code>onload</code>
|
|
handler of the document's <code>body</code> element:
|
|
|
|
<pre class="sh_html">
|
|
<body onload="sh_highlightDocument();">
|
|
</pre>
|
|
</ul>
|
|
|
|
<p>
|
|
Note: All SHJS CSS classes, JavaScript functions and file names begin
|
|
with the prefix <code>sh_</code> to avoid conflicts with other names in your
|
|
HTML document.
|
|
</p>
|
|
|
|
<h2>Automatic loading of language scripts (new in version 0.5)</h2>
|
|
|
|
<p>
|
|
As of version 0.5, you can instruct SHJS to load language-specific scripts
|
|
automatically, so that they do not require <code><script></code> tags. To
|
|
do this, call <code>sh_highlightDocument</code> with two arguments,
|
|
<var>PREFIX</var> and <var>SUFFIX</var>. For every <code><pre></code> tag
|
|
with class <var>CLASS</var>, SHJS will automatically load a language-specific
|
|
script from the URL formed by concatenating <var>PREFIX</var>, <var>CLASS</var>,
|
|
and <var>SUFFIX</var>.
|
|
</p>
|
|
|
|
<p>
|
|
For example, for the following HTML document, SHJS will automatically load the
|
|
language file located at the URL <code>lang/sh_java.js</code>.
|
|
</p>
|
|
|
|
<pre class="sh_html">
|
|
<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>
|
|
</pre>
|
|
|
|
<p>
|
|
In the next document, SHJS will load the language file
|
|
<code>sh_cpp.min.js</code> from the current directory:
|
|
</p>
|
|
|
|
<pre class="sh_html">
|
|
<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>
|
|
</pre>
|
|
|
|
<p>
|
|
Note that the language-specific scripts must be located on the same host
|
|
as the HTML document from which they are loaded.
|
|
</p>
|
|
|
|
<h2>Adding support for new languages</h2>
|
|
|
|
<p>
|
|
SHJS comes with definitions for highlighting
|
|
<a href="#classes">more than 30 different languages</a>.
|
|
If your favorite language is not among them, you can create a new
|
|
language definition.
|
|
</p>
|
|
|
|
<p>
|
|
SHJS uses the same file format for defining languages as
|
|
<a href="http://www.gnu.org/software/src-highlite/">GNU Source-Highlight</a>.
|
|
This format is defined in the
|
|
<a href="http://www.gnu.org/software/src-highlite/source-highlight.html#Language-Definitions">source-highlight manual</a>.
|
|
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 <code>span</code> element; its <code>class</code>
|
|
attribute will be the name of the construct with a <code>sh_</code> prefix
|
|
(e.g., <code>sh_keyword</code>). These <code>span</code> elements are then
|
|
highlighted by the document's style sheet. (Note that a construct with the
|
|
name <code>url</code> is somewhat magical: SHJS will turn it into
|
|
an HTML hyperlink.)
|
|
</p>
|
|
|
|
<p>
|
|
Almost any language definition that works for source-highlight will also work
|
|
for SHJS. However,source-highlight uses
|
|
<a href="http://www.boost.org/libs/regex/doc/syntax.html">Boost regular expressions</a>,
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Once you have defined the language, you must convert it to the JavaScript format
|
|
used by SHJS. You will require the <code>sh2js.pl</code> script from a <a
|
|
href="download.html">source distribution</a> of SHJS. The <code>sh2js.pl</code>
|
|
script is written in Perl and requires the <code>Parse::RecDescent</code>
|
|
module.
|
|
</p>
|
|
|
|
<p>
|
|
Suppose your new language definition is contained in the file
|
|
<code>foo.lang</code>. Then the following command will generate the
|
|
JavaScript file needed by SHJS:
|
|
</p>
|
|
|
|
<pre class="sh_sh">
|
|
perl sh2js.pl foo.lang > sh_foo.js
|
|
</pre>
|
|
|
|
<p>
|
|
You can then reference the <code>sh_foo.js</code> file in your HTML document.
|
|
You should place source code snippets in a <code>pre</code> element with
|
|
<code>class="sh_foo"</code>.
|
|
</p>
|
|
|
|
<h2>Creating new themes</h2>
|
|
|
|
<p>
|
|
The easiest way to create a new highlighting theme is to customize the <code><a
|
|
href="../sh_style.css">sh_style.css</a></code> file in the top-level directory
|
|
of the SHJS distribution.
|
|
</p>
|
|
|
|
<address>
|
|
Copyright © 2007, 2008 <a href="mailto:gnombat@users.sourceforge.net">gnombat@users.sourceforge.net</a>
|
|
<a href="http://www.gnu.org/licenses/gpl.html"><img src="gplv3-88x31.png" width="88" height="31" alt="GPL Logo"></a>
|
|
<a href="http://sourceforge.net"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=186094&type=1" width="88" height="31" alt="SourceForge.net Logo" /></a>
|
|
</address>
|
|
|
|
</div>
|
|
|
|
<div id="navigation">
|
|
<a href="../">Home</a> |
|
|
<a href="news.html">News</a> |
|
|
Documentation |
|
|
<a href="browsers.html">Browsers</a> |
|
|
<a href="download.html">Download</a> |
|
|
<a href="http://sourceforge.net/tracker/?group_id=186094">Bugs</a> |
|
|
<a href="gplv3.html">License</a> |
|
|
<a href="links.html">Links</a>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|