SyntaxHighlightingPlugin < TWiki

---+!! Syntax Highlighting Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/SyntaxHighlightingPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/SyntaxHighlightingPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.

   * Set SHORTDESCRIPTION = Highlight source code fragments for many languages
-->
<sticky>
<div class="twikiTocFloat">
%TOC{title="Page contents"}%
</div>
<div style="float:right; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
<a href="%PUBURLPATH%/%WEB%/%TOPIC%/cpp-screenshot.png"><img src="%PUBURLPATH%/%WEB%/%TOPIC%/cpp-screenshot-300.png" alt="cpp screenshot" title="CPP example (click to enlarge)" width="300" height="287" border="0" /></a>
</div></sticky>
%SHORTDESCRIPTION%

---++ 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

%IF{
 "context SyntaxHighlightingPluginEnabled"
 then="The currently installed =enscript= supports highlighting of the following languages:

$percntSYNTAXHIGHLIGHTING{supported}$percnt"
 else="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 [[http://www.markkurossi.com/genscript/index.html][genscript documentation]].

---++ Syntax Rules

To use this plugin, use the following syntax:

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

The =&lt;sticky&gt;= tags are required to prevent TWiki's WYSIWYG editor from removing line breaks inside the code block.

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

---+++ CODE Parameters

%INCLUDE{ "VarCODE" section="parameters" }%

__Note:__ The default can be set in configure

---++ Examples

The following text:

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

gives (if installed):

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

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

<verbatim>
<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>
</verbatim>

gives (if installed):

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

---++ Plugin Installation & Configuration

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the extension home on twiki.org (see below).
      * Unzip ==%TOPIC%.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 [[%SCRIPTURL{configure}%][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:
     %BR% =%<nop>begin sh%=
     %BR% =...code...=
     %BR% =%<nop>end%=
     %BR% 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== |  |


   * Additional languages can be added, see [[http://www.markkurossi.com/genscript/index.html][genscript documentation]].

%ENDTWISTY%

---++ Plugin Info

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.AndrewRJones |
|  Previous Authors: | TWiki:Main.NicolasTisserand, TWiki:Main.NicolasBurrus, Perceval Anichini |
|  Copyright: | &copy; 2002-2016 Peter Thoeny, [[http://twiki.org/][TWiki.org]] %BR% &copy; 2002-2016 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2016-01-22 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2019-12-04: | TWikibug:Item7873: unescaped braces in regex are escaped. |
|  2016-01-22: | TWikibug:Item7708: Switch to GPL 3; copyright update to 2016 |
|  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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  Dependencies: | enscript >= 1.6.3, CPAN:IPC::Run |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarCODE, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
This topic: TWiki > TWikiPreferences > SyntaxHighlightingPlugin
Topic revision: r1 - 2019-12-04 - TWikiContributor
Copyright © 1999-2025 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.