Revision [3163]
This is an old revision of WikkaGeshiIntegration made by JavaWoman on 2004-12-14 17:26:35.
Integration of GeSHI into Wikka
The intention is to bundle GeSHi with Wikka as of version 1.1.6.0, and it can be seen here now in a beta implementation. While it "works", I'd like a more rigorous and at the same time more flexible integration than what we have now. I'll outline how I've done the integration (into my version of Wikka 1.1.5.3) on this page.Goals
My integration method derives from the following goals:- use the latest version: that is (now) 1.0.4, released soon after 1.0.3 which was a buggy build: for instance some documentation and the CSS-generator are missing in 1.0.3;
- allow a WikiAdmin to use an already-existing implementation of GeSHi (possibly modified) instead of the modified one;
- allow a WikiAdmin to do some general configuration of GeSHi behavior via the Wikka config file, avoiding having to hack the code that implements the GeSHi interface;
- allow a WikiAdmin to upgrade GESHI or add new language files, and have them automatically recognized;
- allow an end user to "turn on" line numbering (if WikiAdmin has enabled this) and set a starting line number (note: the result will not be compliant with XHTML strict, but Wikka claims on XHTML transitional, and it's compliant with that).
Implementation steps
Implementation of the integration consists of the following steps:- latest GeSHi version (>= 1.0.4)
- extension of the configuration file
- adaptation of the routine in the wakka formatter that handles a code block
- method in wikka.php that forms the actual interface to GeSHi
- adaptation of the Format() method in wikka.php
- some additional rules in the wikka stylesheet
1. Latest GeSHi version
Download the latest version from http://qbnz.com/highlighter/ and use this to replace the one now in Wikka 1.1.6.0beta. (However, see also WikkaCodeStructure!)2. Extension of the configuration file
In order to accomplish the goal of automatic recognition of syntax highlighter files, we need to let the program look in the directory where these are stored, instead of hard-coding the (now) available languages. This means we need to define the path where these files are stored in the configuration file; for even more flexibility, we follow the same approach for the built-in Wikka code highlighters. And to allow a WikkaAdmin to use an already-installed package, the path to the package itself needs to be defined as well.Add the following to /wikka.config.php:
// formatter and code hilighting paths
'wikka_formatter' => 'formatters', # (location of Wikka formatter - REQUIRED)
'wikka_lang_path' => 'formatters', # (location of Wikka code highlighters - REQUIRED)
'geshi_path' => 'geshi', # (location of GeSHi package)
'geshi_lang_path' => 'geshi/geshi', # (location of GeSHi language hilighting files)
'wikka_formatter' => 'formatters', # (location of Wikka formatter - REQUIRED)
'wikka_lang_path' => 'formatters', # (location of Wikka code highlighters - REQUIRED)
'geshi_path' => 'geshi', # (location of GeSHi package)
'geshi_lang_path' => 'geshi/geshi', # (location of GeSHi language hilighting files)
The paths should not end in a slash.
Note that these paths are relative - and only serve as an example; it's also possible to define absolute paths, which would be required anyway if elements of Wikka or GeSHi were to be located outside the webserver's docroot.
In order to accomplish the goal of configurability without having to hack the wikka code, the following configuration parameters should also be added to /wikka.config.php:
// code hilighting with GeSHi
'geshi_header' => 'div', # 'div' (default) or 'pre' to surround code block
'geshi_line_numbers' => '1', # disable line numbers (0), or enable normal (1) or fancy line numbers (2)
'geshi_tab_width' => '4', # set tab width
'geshi_header' => 'div', # 'div' (default) or 'pre' to surround code block
'geshi_line_numbers' => '1', # disable line numbers (0), or enable normal (1) or fancy line numbers (2)
'geshi_tab_width' => '4', # set tab width
3. Wakka code block formatter
This is where we do most of the work in order to make the GeShi implementation as flexible as possible, and accomplish our goals of being able to "drop in" new language files, both for GeSHi and Wikka, as well as allow the end user to use line numbering if enabled by the WikiAdmin.In /formatters/wakka.php repleace this (in the 1.1.5.3 version!):
// code text
else if (preg_match("/^\%\%(.*)\%\%$/s", $thing, $matches))
{
// check if a language has been specified
$code = $matches[1];
$language = "";
if (preg_match("/^\((.+?)\)(.*)$/s", $code, $matches))
{
list(, $language, $code) = $matches;
}
switch ($language)
{
case "php":
$formatter = "php";
break;
case "ini":
$formatter = "ini";
break;
case "email":
$formatter = "email";
break;
default:
$formatter = "code";
}
$output = "<div class=\"code\">\n";
$output .= $wakka->Format(trim($code), $formatter);
$output .= "</div>\n";
return $output;
}
else if (preg_match("/^\%\%(.*)\%\%$/s", $thing, $matches))
{
// check if a language has been specified
$code = $matches[1];
$language = "";
if (preg_match("/^\((.+?)\)(.*)$/s", $code, $matches))
{
list(, $language, $code) = $matches;
}
switch ($language)
{
case "php":
$formatter = "php";
break;
case "ini":
$formatter = "ini";
break;
case "email":
$formatter = "email";
break;
default:
$formatter = "code";
}
$output = "<div class=\"code\">\n";
$output .= $wakka->Format(trim($code), $formatter);
$output .= "</div>\n";
return $output;
}
by this:
// code text
else if (preg_match("/^\%\%(.*?)\%\%$/s", $thing, $matches)) # % is not a meta character: escaping with \ is not necessary
{
/*
* Note: this routine is rewritten such that (new) language formatters
* will automatically be found, whether they are GeSHi language config files
* or "internal" Wikka formatters.
* Path to GeSHi language files and Wikka formatters MUST be defined in config.
* For line numbering (GeSHi only) a starting line can be specified after the language
* code, separated by a ; e.g., (php;27).....
* Specifying >= 1 turns on line numbering if this is enabled in the configuration.
*/
$code = $matches[1];
$geshi_hi_path = isset($wakka->config['geshi_lang_path']) ? $wakka->config['geshi_lang_path'] : '/:/';
$wikka_hi_path = isset($wakka->config['wikka_lang_path']) ? $wakka->config['wikka_lang_path'] : '/:/';
// check if a language (and starting line) has been specified
$language = '';
if (preg_match("/^\((.+?)(;([0-9]+))??\)(.*)$/s", $code, $matches))
{
list(, $language, , $start, $code) = $matches;
}
// get rid of newlines at start and end (and preceding/following whitespace)
// Note: unlike trim(), this preserves any tabs at the start of the first "real" line
$code = preg_replace('/^\s*\n+|\n+\s*$/','',$code);
// check if we have a GeSHi hilighter for this language
if (isset($wakka->config['geshi_path']) && file_exists($geshi_hi_path.'/'.$language.'.php'))
{
// use GeSHi for hilighting
$output = $wakka->GeSHi_Highlight($code, $language, $start);
}
// check if we have an internal Wikka hilighter
elseif (file_exists($wikka_hi_path.'/'.$language.'.php') && 'wakka' != $language)
{
// use internal Wikka hilighter
$output = "<div class=\"code\">\n";
$output .= $wakka->Format($code, $language);
$output .= "</div>\n";
}
// no formatter found: default code block
else
{
$output = "<div class=\"code\">\n";
$output .= $wakka->Format($code, 'code');
$output .= "</div>\n";
}
return $output;
}
else if (preg_match("/^\%\%(.*?)\%\%$/s", $thing, $matches)) # % is not a meta character: escaping with \ is not necessary
{
/*
* Note: this routine is rewritten such that (new) language formatters
* will automatically be found, whether they are GeSHi language config files
* or "internal" Wikka formatters.
* Path to GeSHi language files and Wikka formatters MUST be defined in config.
* For line numbering (GeSHi only) a starting line can be specified after the language
* code, separated by a ; e.g., (php;27).....
* Specifying >= 1 turns on line numbering if this is enabled in the configuration.
*/
$code = $matches[1];
$geshi_hi_path = isset($wakka->config['geshi_lang_path']) ? $wakka->config['geshi_lang_path'] : '/:/';
$wikka_hi_path = isset($wakka->config['wikka_lang_path']) ? $wakka->config['wikka_lang_path'] : '/:/';
// check if a language (and starting line) has been specified
$language = '';
if (preg_match("/^\((.+?)(;([0-9]+))??\)(.*)$/s", $code, $matches))
{
list(, $language, , $start, $code) = $matches;
}
// get rid of newlines at start and end (and preceding/following whitespace)
// Note: unlike trim(), this preserves any tabs at the start of the first "real" line
$code = preg_replace('/^\s*\n+|\n+\s*$/','',$code);
// check if we have a GeSHi hilighter for this language
if (isset($wakka->config['geshi_path']) && file_exists($geshi_hi_path.'/'.$language.'.php'))
{
// use GeSHi for hilighting
$output = $wakka->GeSHi_Highlight($code, $language, $start);
}
// check if we have an internal Wikka hilighter
elseif (file_exists($wikka_hi_path.'/'.$language.'.php') && 'wakka' != $language)
{
// use internal Wikka hilighter
$output = "<div class=\"code\">\n";
$output .= $wakka->Format($code, $language);
$output .= "</div>\n";
}
// no formatter found: default code block
else
{
$output = "<div class=\"code\">\n";
$output .= $wakka->Format($code, 'code');
$output .= "</div>\n";
}
return $output;
}
