Syntax Highlighting Plugin

cpp screenshot
Highlight source code fragments for many languages

Introduction

The Syntax Highlighting Plugin is used to emphasize the rendering of your wiki text according to several languages. It currently uses enscript to render its output.

Supported languages

Recent versions of enscript support highlighting of the following languages:

ada, asm, awk, bash, c, changelog, cpp, csh, delphi, diff, diffs, diffu, dylan, eiffel, elisp, forth, fortran, fortran_pp, haskell, html, icon, idl, inf, java, javascript, ksh, lua, m4, mail, makefile, matlab, nroff, oberon2, objc, outline, oz, pascal, perl, php, postscript, pyrex, python, rfc, ruby, scheme, sh, skill, smalltalk, sml, sql, states, synopsys, tcl, tcsh, tex, vba, verilog, vhdl, vrml, wmlscript, zsh

You need to installed and enabled the SyntaxHighlightingPlugin to see the actual languages that are available.

Additional languages can be added, see genscript documentation.

Syntax Rules

To use this plugin, use the following syntax:

<sticky>
%CODE{ lang="cpp" num="10" numstep="2" }% 
...code...
%ENDCODE%
</sticky>

The <sticky> tags are required to prevent TWiki's WYSIWYG editor from removing line breaks inside the code block.

In addition, %SYNTAXHIGHLIGHTING{supported}% returns the list of currently supported languages as indicated above.

CODE Parameters

Parameter Description Default
"..." or
lang="..."
Source language. Supported languages: ada, asm, awk, bash, changelog, cpp, csh, c, delphi, diffs, diff, diffu, dylan, eiffel, elisp, Name:, forth, fortran_pp, fortran, haskell, html, icon, idl, inf, javascript, java, ksh, lua, m4, mail, makefile, matlab, nroff, oberon2, objc, outline, oz, pascal, perl, php, postscript, pyrex, python, rfc, ruby, scheme, sh, skill, Smalltalk, sml, sql, states, synopsys, tcl, tcsh, tex, vba, verilog, vhdl, vrml, wmlscript, zsh (none, required)
num="..." Show line numbers next to the source code. An integer indicates the start number. Also "on" and "off" "off"
step="..." Increment line numbers with the given step. Negative numbers will decrement. "1"
style="..." Style of box around the source code light gray box
numstyle="..." Style of line number column light brown box

Note: The default can be set in configure

Examples

The following text:

 
<sticky>
%CODE{"c++"}%
#include <iostream>
int main()
{
  // Hello world example
  std::cout << "Hello, world." << std::endl;
}
%ENDCODE%
</sticky>

gives (if installed):

#include 
int main()
{
  // Hello world example
  std::cout << "Hello, world." << std::endl;
}

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

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

gives (if installed):

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

Plugin Installation & Configuration

Note: You do not need to install anything on the browser to use this extension. The following instructions are for the administrator who installs the extension on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip SyntaxHighlightingPlugin.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section if needed.
    • Test if the installation was successful using the examples provided.

  • Configure settings in Extensions section:
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{EnscriptPath} # path to enscript script
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{DefaultLang} # Default language
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{Numbering} # Default for line numbering, 'off' or 'on'
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{Step} # Default step of numbering
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{Style} # Style of pre tag containing the source code
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{NumStyle} # Style of numbering column
    • $TWiki::cfg{Plugins}{SyntaxHighlightingPlugin}{Debug} # Debug setting

  • Change of Syntax: Content of an older version of this plugin with the following syntax needs to be updated:
    %begin sh%
    ...code...
    %end%
    This has been changed to be more consistent with other twiki variables. There is a script included which will replace the old syntax with the new one. To use it, copy it from the tools directory and into your data directory. When you run it, it will look through your webs and replace the syntax. Note that its not the best script in the world, so always test it on a copy of your data first!

  • Plugin Files:
    data/TWiki/SyntaxHighlightingPlugin.txt Plugin topic
    data/TWiki/VarCODE.txt Variable documentation topic
    pub/TWiki/SyntaxHighlightingPlugin/cpp-screenshot.png  
    pub/TWiki/SyntaxHighlightingPlugin/cpp-screenshot-300.png  
    lib/TWiki/Plugins/SyntaxHighlightingPlugin.pm Perl module
    lib/TWiki/Plugins/SyntaxHighlightingPlugin/Config.spec  
    tools/SyntaxHighlightingPlugin_covert.pl  

Plugin Info

Plugin Author: TWiki:Main.AndrewRJones
Previous Authors: TWiki:Main.NicolasTisserand, TWiki:Main.NicolasBurrus, Perceval Anichini
Copyright: © 2002-2014 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2014-03-26
2014-03-26: TWikibug:Item7470: SyntaxHighlightingPlugin may fail to recognize enscript supporting languages
2013-12-11: TWikibug:Item7399: Auto-detect supported languages -- TWiki:Main.PeterThoeny
2013-04-04: TWikibug:Item7211: Add Scala support -- TWiki:Main.HideyoImazu
2013-02-14: TWikibug:Item7091: Show source code of undefined or unsupported language, but warn user; use configure settings for defaults; rename numstep parameter to step & make numstep undocumented; add VarCODE variable documentation -- TWiki:Main.PeterThoeny
2013-02-13: TWikibug:Item7091: Add style and numstyle parameters -- TWiki:Main.PeterThoeny
2013-02-13: TWikibug:Item7123: Use TWISTY in installation instructions and change history
2012-11-15: TWikibug:Item7035: Number step support -- TWiki:Main.YaojunFei
2011-05-14: TWikibug:Item6701: Small fix in Config.spec -- TWiki:Main.PeterThoeny
2010-10-23: TWikibug:Item6530: Doc improvements - TWiki:Main.PeterThoeny, TWiki:Main.AndreasKeil
2008-09-11: TWikibug:Item5995: Rewritten to work on TWiki 4.2
2002-07-12: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
Dependencies: enscript >= 1.6.3, CPAN:IPC::Run
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SyntaxHighlightingPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SyntaxHighlightingPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SyntaxHighlightingPluginAppraisal

Related Topics: VarCODE, TWikiPreferences, TWikiPlugins

Topic revision: r1 - 2014-03-26 - TWikiContributor
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.SyntaxHighlightingPlugin.