%META:TOPICINFO{author="BenHouston" date="1108408251" format="1.0" version="1.1"}%
%META:TOPICPARENT{name="TWikiPreferences"}%
---++ Syntax Highlighting TWiki Plugin

The Syntax Highlighting Twiki Plugin is used to emphasize the rendering of your twiki text according to several languages.

It currently uses =enscript= to render its output.

It supports the following languages : 
	* ada
	* asm
	* awk
	* bash
	* c
	* changelog
	* c++
	* csh
	* delphi
	* diff
	* diffs
	* diffu
	* elisp
	* fortran
	* fortran_pp
	* haskell
	* html
	* idl
	* inf
	* java
	* javascript
	* ksh
	* m4
	* mail
	* makefile
	* maple
	* matlab
	* modula_2
	* nested
	* nroff
	* objc
	* outline
	* pascal
	* perl
	* postscript
	* python
	* rfc
	* scheme
	* sh
	* skill
	* sql
	* states
	* synopsys
	* tcl
	* tcsh
	* tex
	* vba
	* verilog
	* vhdl
	* vrml
	* wmlscript
	* xml (kind of - emulated as html)
	* zsh

---+++ Syntax Rules

To enable syntax highlighting on some text, just type :

<verbatim>
%SYNTAX "language" [numbered]% 

	 some text belonging to the language

%ENDSYNTAX%
</verbatim>
where language is one of the list above, and numbered an optional keyword triggering the line numbering feature.

Notice that the =%SYNTAX%= and =%ENDSYNTAX%= tags must be left alone on one single line.

----+++ Example

The following text :

<verbatim>
%SYNTAX{"c++"}% 
#include <iostream>
int main()
{
  std::cout << "Hello, world." << std::endl;
}
%ENDSYNTAX%
</verbatim>
gives :

%SYNTAX{"c++"}%
#include <iostream>
int main()
{
  std::cout << "Hello, world." << std::endl;
}
%ENDSYNTAX%

_If you do not see a nice colorized piece of code above this, you should check if the plugin is well installed._

You can also output numbered lines starting at 10 with this text:

<verbatim>
%SYNTAX{"sh" numbered:10}% 
#!/bin/sh
languages=`enscript --help-highlight | grep 'Name:' | cut -d ' ' -f 2`
for l in $languages; do
	 cat << EOF
	* $l
EOF
done
%ENDSYNTAX%
</verbatim>
which outputs:

%SYNTAX{"sh" numbered:10}%
#!/bin/sh
languages=`enscript --help-highlight | grep 'Name:' | cut -d ' ' -f 2`
for l in $languages; do
	 cat << EOF
	* $l
EOF
done
%ENDSYNTAX%

---+++ <nop>%TOPIC% Settings

Plugin settings are stored as preferences variables. To reference
a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>SYNTAXHIGHLIGHTINGPLUGIN_SHORTDESCRIPTION%==

	* One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
		* Set SHORTDESCRIPTION = This Plugin is used to emphasize the rendering of your twiki text according to several languages.

	* Debug plugin: (See output in =data/debug.txt=)
		* Set DEBUG = 0

	* Container: Allows you to determine the block container to hold the output from this plugin. Add in any valid xhtml, and include _<nop>_<nop>OUTPUT__ ([underscore][underscore]OUTPUT[underscore][underscore]) to tell the plugin where to throw the formateed output. For example, if you want your code blocks output into a div with a class of =twikiSyntaxHighlightingBlock=, you could use a CONTAINER value of &lt;div class="twikiSyntaxHighlightingBlock"&gt;__OUTPUT__&lt;/div&gt;
		* S<nop>et CONTAINER = 

	* Enscript: This plugin defaults to settings that assume enscript is on your path and that it is version 1.63. If you have a different version (especially earlier), change these settings.
		* S<nop>et ENSCRIPT_PATH = 
		* S<nop>et ENSCRIPT_VERSION = 

---+++ Plugin Installation Instructions

	* Make sure you have GNU enscript 1.6.3 or above installed.

	* Unzip the =SyntaxHighlighting.zip= package in your TWiki installation directory.

	* If the installation is correct, you should see some highlighted text in this page.

	* If you want support for additional languages (for customized or future enscript versions), you must edit the plugin file and add your languages to the languages array. _(Make sure that your =enscript= version supports the languages you add.)_

---+++ Known Bugs

---++++ Enscript oddities

<verbatim>
%SYNTAX{"sh"}% 
# youpi
%ENDSYNTAX% 
</verbatim>

gives

%SYNTAX{"sh"}% 
# youpi
%ENDSYNTAX% 

Because =enscript= strangely adds an extra line (for closing its emphasizing markers) between the matched  &lt;pre&gt; &lt;/pre&gt; to its html output.

Working around such a weird behavior is ... not planned.

---++++ WikiWords on last line

<verbatim>
%SYNTAX{"sh"}%
UnmatchedWikiword :)
MatchedWikiWord :(
%ENDSYNTAX%
</verbatim>

gives

%SYNTAX{"sh"}%
UnmatchedWikiword :)
MatchedWikiWord :(
%ENDSYNTAX%

Adding a newline at the end of input stops TWiki in his greedy matching, but this workaround is not an acceptable solution. Feel free to find another one ....
---+++ Plugin Info

|  Plugin Author: | Main.NicolasTisserand, Main.NicolasBurrus, Perceval Anichini|
|  Plugin Version: | 12 Jul 2002 |
|  Change History: | 12 Jul 2002: Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | GNU enscript 1.6.3 |
|  Perl Version: | 5.0 |
|  Plugin Home: | http://www.lrde.epita.fr/cgi-bin/twiki/view/TWiki/SyntaxHighlightingPlugin |
|  Feedback: | Main.NicolasTisserand |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins, EmptyPlugin

-- Main.NicolasTisserand - 12 Jul 2002

