Syntax Highlighting

From UMBEL Wiki
Jump to: navigation, search

This wiki allows syntax highlighting using Geshi and a module extension for Mediawiki. You can specify more than 120 supported languages in using the highlighter.

The system also works well for export (check out this page via this URL):


Basic Usage

To use the system, you need to bracket your code example with these tags:

  <source lang="lang"> 
    * code is placed here
    * default "lang" is "php"; will be used if no "lang" entered
  </source>

Following are some examples:

Export and External Style Sheet

The code generated by the highlighter embeds a dynamic style sheet. To use the same code without Geshi in an external application, you must add new classes and colors to your external style sheet.

Depending on the language you are highlighting, you may get different classes listed.

For pages on which you are using highlighting, do a View Source and look for something like this generated table (this example is for 'PHP'):

<style type="text/css">/*<![CDATA[*/
.source-php {line-height: normal;}
.source-php li, .source-php pre {
	line-height: normal; border: 0px none white;
}
/**
* GeSHi Dynamically Generated Stylesheet
* --------------------------------------
* Dynamically generated stylesheet for php
* CSS class: source-php, CSS id:
* GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
* --------------------------------------
*/
.source-php .de1, .source-php .de2 {font-family: monospace; font-weight: normal; font-style: normal; margin:0; padding:0; background:inherit;}
.source-php  {font-family: monospace;}
.source-php .imp {font-weight: bold; color: red;}
.source-php li, .source-php li.li1 {font-weight: normal;}
.source-php li.li2 {font-weight: bold;}
.source-php .kw1 {color: #b1b100;}
.source-php .kw2 {color: #000000; font-weight: bold;}
.source-php .kw3 {color: #990000;}
.source-php .co1 {color: #666666; font-style: italic;}
.source-php .co2 {color: #666666; font-style: italic;}
.source-php .co3 {color: #0000cc; font-style: italic;}
.source-php .coMULTI {color: #666666; font-style: italic;}
.source-php .es0 {color: #000099; font-weight: bold;}
.source-php .br0 {color: #009900;}
.source-php .sy0 {color: #339933;}
.source-php .st0 {color: #0000ff;}
.source-php .nu0 {color: #cc66cc;}
.source-php .me1 {color: #004000;}
.source-php .me2 {color: #004000;}
.source-php .re0 {color: #000088;}
.source-php .ln-xtra, .source-php li.ln-xtra, .source-php div.ln-xtra {background-color: #ffc;}
.source-php span.xtra { display:block; }

/*]]>*/
</style>

Make sure you have a color assignment for each of the classes so listed in your external style sheet.

Use Examples

pre Tag

The following material is in a pre tag. We are using PHP as the default. SOURCE DOES NOT WORK !!!!:

<source>

<?php
function syntaxHighlightingRenderHtml($input, $argv){
	/**
	 * Pass in the globals defined above for use in the function.
	 */
	global $BEAUT_PATH, $LOCAL_SERVER_ROOT, $OUTPUT_HIGHLIGHT_AS;
	/**
	 * Require the two main files for the beautifier.
	 */
	require_once ($BEAUT_PATH."Beautifier/Core.php");

/**
* If a specific language is requested load the relevant file and create the highlighter
*/
$myhfile = null;
if($argv["language"] && file_exists($BEAUT_PATH."HFile/HFile_".$argv["language"].".php") ){
require_once ($BEAUT_PATH."HFile/HFile_".$argv["language"].".php");

if (FALSE === eval("\$myhfile = new HFile_".$argv["language"]."();") ) {
$output .= "Error:1 Could not instantiate HFile_".$argv["language"]."()<br />";
}


</source>

PHP

Here is the PHP example:

<?php
/**
* MediaWiki Extension for Code Syntax Highlighting with the [ http://www.beautifier.org | Beautifier Syntax Highlighting Engine].
*
* Parses any content defined within the <nowiki><highlightSyntax></highlightSyntax></nowiki> tag
* with the [ http://www.beautifier.org | Beautifier Syntax Highlighting Engine] and
* returns the HTML output.
* @author Lucas Hrabovsky <lucas@amie.st>
* @copyright &copy; 2006 Amie Inc.
* @package MediaWiki
* @subpackage Extensions
* @filesource
*/
/**
* ----------------------------------------
* Configuration Vars.
* ----------------------------------------
* @string BEAUT_PATH The root path to your Beatuifier installation.
* @string LOCAL_SERVER_ROOT The root path to use when opening files on the local server for highlighting.
* @string OUTPUT_HIGHLIGHT_AS Whether to output the HTML as CSS friendly or not.  enum('CSS','HTML')
*/
$BEAUT_PATH = "/path/to/your/beautifier/installation/";
$LOCAL_SERVER_ROOT = "/pathtoyour/public_html/or/www/directory/";
$OUTPUT_HIGHLIGHT_AS = "HTML";
/**
* Add the syntax highlighting extension to the wgExtensionFunctions array.
*/
$wgExtensionFunctions[] = "syntaxHighlightingExtension";
/**
* Register the syntaxHighlightingExtension with the Wiki Parser and associate
* the highlightSyntax tag with the syntaxHighlightingRenderHtml function.
*/
function syntaxHighlightingExtension(){
	global $wgParser;
	$wgParser->setHook("HIGHLIGHTSYNTAX","syntaxHighlightingRenderHtml");
}
/**
* The callback function for converting the input text to HTML output.
*/
function syntaxHighlightingRenderHtml($input, $argv){
	/**
	 * Pass in the globals defined above for use in the function.
	 */
	global $BEAUT_PATH, $LOCAL_SERVER_ROOT, $OUTPUT_HIGHLIGHT_AS;
	/**
	 * Require the two main files for the beautifier.
	 */
	require_once ($BEAUT_PATH."Beautifier/Core.php");
 
/**
* If a specific language is requested load the relevant file and create the highlighter
*/
$myhfile = null;
if($argv["language"] && file_exists($BEAUT_PATH."HFile/HFile_".$argv["language"].".php") ){
require_once ($BEAUT_PATH."HFile/HFile_".$argv["language"].".php");
 
if (FALSE === eval("\$myhfile = new HFile_".$argv["language"]."();") ) {
$output .= "Error:1 Could not instantiate HFile_".$argv["language"]."()<br />";
}
 
}
 
/**
* Otherwise use php as a default
*/
else
{
require_once ($BEAUT_PATH."HFile/HFile_php3.php");
$myhfile = new HFile_php3();
}
 
/**
* Set up the highlight object based on whether
* you want the output as CSS freindly or straight HTML.
*/
if($OUTPUT_HIGHLIGHT_AS=="CSS"){
	require_once ($BEAUT_PATH."Output/Output_css.php");
	$outputter = new Output_css();
}
else {
	require_once ($BEAUT_PATH."Output/Output_HTML.php");
	$outputter = new Output_Html();
}
 
$highlighter = new Core($myhfile, $outputter);
 
	/**
	 * The meat and potatoes...
	 */
 
	/**
	 * If the serverFile argument is passed in the tag, load the local file into the highlighter parser.
	 */
	if($argv["serverFile"]){
		$output .= "<div style=\"font-weight: bold;\"><pre>\n";
		$output .= $highlighter->highlight_text($highlighter->load_file($serverRoot.$argv["serverFile"]));
		$output .= "</pre></div>";
		return $output;
	/**
	 * If its a remote file, open it up and parse the returned contents.
	 */
	} else if($argv["remoteFile"]){
		$openFileName = $argv["remoteFile"];
		$fp = fopen($openFileName, "r");
		if(!$fp){
			$output = "Error: Syntax Highlighter could not open the file ".$openFileName."<br />";
		} else {
			$fileContents = fread($fp, 8096);
			fclose($fp);
			$output .= "<div style=\"font-weight: bold;\"><h1>Code from <a href=\"".$argv["remoteFile"]."\">".$argv["remoteFile"]."</a></h1><pre>\n";
			$output .= $highlighter->highlight_text($fileContents);
			$output .= "</pre></div>";
		}
		return $output;
	/**
	 * Else we just want to highlight the code within the syntaxHighlight tags.
	 */
	} else {
		$output .= "<div style=\"font-weight: bold;\"><pre>\n";
		$output .= $highlighter->highlight_text($input);
		$output .= "</pre></div>";
		return $output;
	}
}

HTML

Here is the HTML example:

<html>
  <head>
    <meta content="text/html; charset=iso-8859-1" http-equiv="content-type">
    <title>
      Auth Registrar: Access
    </title>
  </head>
  <body>
    <h1 id="firstHeading" class="firstHeading">
      Auth Registrar: Access
    </h1>
    <h3 id="siteSub">
      From DocWiki
    </h3><!-- start content -->
    <p>
      The <b>Auth Registrar: Access Web service</b> is used to register
      (create, update and delete) an <i>access</i> for a given IP address, to a
      specific dataset and all the registered Web services endpoints registered
      to the WSF (Web Services Framework) with given <a href=
      "http://docwiki.citizen-dan.org/index.php/CRUD_Concept" title=
      "CRUD Concept">CRUD</a> (Create, Read, Update and Delete) permissions in
      the WSF.
    </p>
    <p>
      Developers communicate with the Auth Registrar: Access Web service using
      the HTTP POST method. You may request any content type (*/*).
    </p>
    <div class="boxGreenDotted">
      <b>No content is returned by the Web service endpoint if the endpoint
      successfully executed the query. Only a "200 OK" message will be returned
      in the header.</b>
    </div><br>
    <h3>
      <span class="mw-headline">Usage</span>
    </h3>
    <p>
      This Web service is intended to be used by content management systems,
      developers or administrators to manage access to WSF (Web Service
      Framework) resources (users, datasets, Web services endpoints).
    </p><br>
    <h3>
      <span class="mw-headline">Web Service Endpoint Information</span>
    </h3>
    <p>
      This section describes all you permissions you need in the WSF (Web
      Service Framework) to send a query to this Web service endpoint, and it
      describes how to access it.
    </p>
    <p>
      To access this Web service endpoint you need the proper CRUD (Create,
      Read, Update and Delete) permissions on a specific graph (dataset) of the
      WSF. Without the proper permissions on this graph you won't be able to
      send any queries to the endpoint.
    </p>
    <div class="ws-box">
      Needed registered CRUD permission:
      <ul>
        <li>Create: True
        </li>
        <li>Read: True
        </li>
        <li>Update: False
        </li>
        <li>Delete: False
        </li>
      </ul>
      <p>
        As shown on the graph URI:
      </p>
      <ul>
        <li>http://[...]/wsf/
        </li>
      </ul>
    </div>
    <p>
      Here is the information needed to communicate with this Web service's
      endpoint. Descriptions of the parameters are included below.
    </p>
    <p>
      <i>Note: if a parameter has a default value, the requester can omit it
      and the default value will be used. Also, some baseline Web services may
      not offer other values than the default.</i>
    </p>
    <div class="ws-box">
      HTTP Method:
      <ul>
        <li>POST
        </li>
      </ul>
      <p>
        Possible "Accept:" HTTP header field value:
      </p>
      <ul>
        <li>*/*
        </li>
      </ul>
      <p>
        URI:
      </p>
      <ul>
        <li>
        http://<b>[...]</b>/ws/auth/registrar/access/&nbsp;?crud=<b>param1</b>&amp;ws_uris=<b>param2</b>&amp;dataset=<b>param3</b>&amp;action=<b>param4</b>&amp;
        target_access_uri=<b>param5</b>&amp;registered_ip=<b>param6</b>
        </li>
      </ul>
      <p>
        URI dynamic parameters description:
      </p>
      <p>
        <b>Note:</b> All parameters have to be <a href=
        "http://en.wikipedia.org/wiki/Percent-encoding" class="external text"
        title="http://en.wikipedia.org/wiki/Percent-encoding" rel=
        "nofollow">URL-encoded</a>
      </p>
      <ul>
        <li>
          <b>param1.</b> A quadruple with a value "True" or "False" defined as
          &lt;Create;Read;Update;Delete&gt;. Each value is separated by the ";"
          character. an example of such a quadruple is:
          "crud=True;True;False;False", meaning: Create = True, Read = True,
          Update = False and Delete = False
        </li>
        <li>
          <b>param2.</b> A list of ";" separated Web services URI accessible by
          this <i>access</i> definition
        </li>
        <li>
          <b>param3.</b> URI of the target dataset of this <i>access</i>
          description
        </li>
        <li>
          <b>param4.</b> One of:
        </li>
      </ul>
      <ul>
        <li>
          <ul>
            <li>"<b>create <i>(default)</i></b>": Create a new <i>access</i>
            description
            </li>
            <li>"<b>delete_target</b>": Delete a target <i>access</i>
            description for a specific IP address and a specific dataset
            </li>
            <li>"<b>delete_all</b>": Delete all <i>access</i> descriptions for
            a target dataset
            </li>
            <li>"<b>update</b>": Update an existing <i>access</i> description
            </li>
          </ul>
        </li>
      </ul>
      <ul>
        <li>
          <b>param5.</b> Target URI of the <i>access</i> resource to update.
          Only used when <i>param4 = update</i>
        </li>
        <li>
          <b>param6.</b> Target IP address registered in the WSF
        </li>
      </ul>
    </div>Query Answer from the Endpoint
    <p>
      If the query is successfully performed by the endpoint (i.e., the
      <i>access</i> resource has been properly created, updated or deleted),
      the endpoint will return the HTTP status message "200 OK" with an empty
      body. If an error occured, one of the HTTP status messages with the
      description of the error message in the body of the HTTP query will be
      returned.
    </p><br>
    <h3>
      <span class="mw-headline">HTTP Status Codes</span>
    </h3>
    <p>
      Here are the possible HTTP status (error) codes returned by this Web
      service endpoint.
    </p>
    <p>
      On error code and the specific error, a different message description can
      be issued (meaning a different error has been returned).
    </p>
    <div class="ws-box">
      <ul>
        <li>
          <b>Code:</b> 200
          <ul>
            <li>
              <b>Message:</b> OK
            </li>
          </ul>
        </li>
        <li>
          <b>Code:</b> 400
          <ul>
            <li>
              <b>Message:</b> Bad Request
            </li>
            <li>
              <b>Message description:</b> Answer from the endpoint
            </li>
            <li>
              <b>Message description:</b> Action type undefined
            </li>
            <li>
              <b>Message description:</b> No IP to register
            </li>
            <li>
              <b>Message description:</b> No crud access defined
            </li>
            <li>
              <b>Message description:</b> No web service URI(s) defined
            </li>
            <li>
              <b>Message description:</b> No dataset defined
            </li>
            <li>
              <b>Message description:</b> No target Access URI defined for
              update
            </li>
            <li>
              <b>Message description:</b> No requester IP available
            </li>
            <li>
              <b>Message description:</b> No target dataset
            </li>
            <li>
              <b>Message description:</b> No Web service URI available
            </li>
            <li>
              <b>Message description:</b> Target Web service <i>XYZ</i> not
              registered to this Web Services Framework
            </li>
            <li>
              <b>Message description:</b> No access defined for this requester
              IP <i>XYZ</i>, dataset (<i>XYZ</i>) and Web service (<i>XYZ</i>)
            </li>
            <li>
              <b>Message description:</b> The target Web service (<i>XYZ</i>)
              needs create access and the requested user (<i>XYZ</i>) doesn't
              have this access for that dataset (<i>XYZ</i>)
            </li>
            <li>
              <b>Message description:</b> The target Web service (<i>XYZ</i>)
              needs read access and the requested user (<i>XYZ</i>) doesn't
              have this access for that dataset (<i>XYZ</i>)
            </li>
            <li>
              <b>Message description:</b> The target Web service (<i>XYZ</i>)
              needs update access and the requested user (<i>XYZ</i>) doesn't
              have this access for that dataset (<i>XYZ</i>)
            </li>
            <li>
              <b>Message description:</b> The target Web service (<i>XYZ</i>)
              needs delete access and the requested user (<i>XYZ</i>) doesn't
              have this access for that dataset (<i>XYZ</i>)
            </li>
          </ul>
        </li>
      </ul>
      <ul>
        <li>
          <b>Code:</b> 406
          <ul>
            <li>
              <b>Message:</b> Not Acceptable
            </li>
            <li>
              <b>Message description:</b> Unacceptable mime type requested
            </li>
          </ul>
        </li>
      </ul>
      <ul>
        <li>
          <b>Code:</b> 500
          <ul>
            <li>
              <b>Message:</b> Internal Error
            </li>
          </ul>
        </li>
      </ul>
    </div>
  </body>
</html>