%META:TOPICINFO{author="ThomasFreudenberg" date="1164337859" format="1.1" reprev="1.7" version="1.7"}%
%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 types of source code languages.

It currently uses =enscript= to render its output. enscript could handle and render a lot of languages. For a detailed information please read the manual of enscript. You can add your personal code templates by extending the enscript styles. As default there are files like style_xyz.st (e.g. styles_emacs.st). Make a copy and rewrite the output formatting. You can use this later on as the style parameter when calling <nop>SyntaxHighlightingPlugin.

To make it easy for people who are using TWiki:Plugins.BeautifierPlugin or TWiki:Plugins.SourceHighlightPlugin there is an option set so that this plugin could also handle %<nop>CODE{}% blocks.

Normally enscript will support at least following languages : %TWISTY{showlink="show list" hidelink="hide list" showimgleft="%ICONURLPATH{toggleopen-small}%" 
hideimgleft="%ICONURLPATH{toggleclose-small}%"}%

   * ada
   * asm
   * awk
   * bash
   * c
   * cpp
   * changelog
   * 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
   * zsh
%ENDTWISTY%

---+++ Syntax Rules

To enable syntax highlighting on some text, just type :

<verbatim>
%SYNTAX{ [syntax=]"syntax type" numbered="bool|start with line number" numstep="inc line number" color="bool" style="enscript style"}% 
    some text belonging to the source code
%ENDSYNTAX%
</verbatim>


%TABLE{ sort="off" tableborder="0" cellpadding="1" cellspacing="1" headerbg="#D5CCB1" headercolor="#666666" databg="#FAF0D4, #F3DFA8" headerrows="2" footerrows="1" }%
| *SyntaxHighlightingPlugin Parameter* |||
| *Param* | *Value* | *Description* |
| [syntax=]"syntax type | cpp | look at "enscript --help-highlight" for a list from enscript %BR% param identifier syntax= is optional |
| numbered | on, off, true, false, yes, no %BR% 1000 | will attach an extra source line number %BR% a given number will also be the first line number |
| numstep | 10, 100, -50 | increment next line number with the given step counter %BR% negative will decrement |
| color | on, off, true, false, yes, no | use color mode to highlight the given text |
| style | emacs, msvc | template to format and color your text %BR% you can easily create your own styles for enscript |


If running this plugin in EXTENDED_MODE it is compatible to TWiki:Plugins.Beautifierplugin, TWiki:Plugins.SourceHighlightPlugin:

<verbatim>
%CODE{ "syntax type" }% 
    some text belonging to the source code
%ENDCODE%
</verbatim>

The additional option parameters are also available in this mode.

----+++ Example

The following text :

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

gives :

%SYNTAX{ syntax="cpp" }%
#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 1000 step 10 with this text:

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

which outputs:

%SYNTAX{ syntax="sh" numbered="1000" numstep="10" }%
#!/bin/sh
list_syntax=`enscript --help-highlight | grep 'Name:' | cut -d ' ' -f 2`
for l in $list_syntax; 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>DEFAULTPLUGIN_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 types of source code languages.

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

   * Extended Mode to be compatible to other plugins
      * Set EXTENDED_MODE = 1

   * Enscript settings
      * Set ENSCRIPT_COLOR = 1
      * Set ENSCRIPT_STYLE = msvc

   * Format settings
      <verbatim>
      * Set FORMAT_LINENUMBERS = <font color="#555555">%05d</font>&#9;
      * Set FORMAT_PREPEND = <table width="100%" border="0" cellpadding="" cellspacing="0"><tr><td bgcolor="#FFFFFF"><pre><font color="#000000">
      * Set FORMAT_APPEND = </font></pre></td></tr></table>
      </verbatim>

---+++ 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 you only have to take care, that your local enscript will support them.

---+++ Things to do

   * Plugin should use <nop>lib/TWiki/Sandbox.pm sysCommand than IPC:Open2


---+++ Plugin Info

|  Plugin Author: | TWiki:Main.ThomasFreudenberg |
|  Previous Authors: | TWiki:Main.NicolasTisserand, TWiki:Main.NicolasBurrus, TWiki:PercevalAnichini |
|  Plugin Version: | 24 Nov 2006 |
|  Change History: | 24 Nov 2006: completly rewritten |
|  CPAN Dependencies: | IPC:Open2 |
|  Other Dependencies: | GNU enscript 1.6.3 |
|  Perl Version: | 5.0 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
|  Appraisal: | TWiki:Plugins/%TOPIC%Appraisal |

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

-- [[TWiki:Main.ThomasFreudenberg]] - 24 Nov 2006
