Beautifier Plugin

Provides the %CODE% and %ENDCODE% macros to display code fragments with formatting and syntax highlighting for improved readbility in wiki topics.

Related topics: dp.SyntaxHighlighter

Introduction

Use the %CODE% and %ENDCODE% macros to enclose fragments of code in your topic that you wish to have displayed with appropriate syntax hightlighting and formatting for better readability and presentation.

This plugin was derived from Mike Jewell's popular Beautifier: Flexible Syntax Highlighter package. The original PHP code of the Beautifier library has been ported to Perl for use with Foswiki and this plugin.

Syntax

• Syntax: %CODE% … %ENDCODE% or %CODE{…}% … %ENDCODE%
• %CODE% … %ENDCODE% encapsulates a code fragment to be displayed using the default language syntax and CSS styling
• %CODE{…}% … %ENDCODE% encapsulates a code fragment to be displayed allowing the language syntax and CSS styling to be overridden according to any parameters supplied
• Supported parameters:

  Parameter:	Description:	Default
  "language"	The language syntax identifier	"cpp"
  css="URL"	The URL of a CSS stylesheet that extends the plugin's default styling for code fragments

• Supported language syntaxes:

  Language:	Identifier:		Language:	Identifier:		Language:	Identifier:
  bash	"bash"		Lua	"lua"		Scheme	"scheme"
  C++	"cpp"		Makefile	"makefile"		TCL	"tcl"
  C#	"csharp"		Perl	"perl"		Verilog	"verilog"
  HTML	"html"		PHP3	"php3"		VHDL	"vhdl"
  Java	"java"		PL/SQL	"plsql"		XML	"xml"
  JavaScript	"javascript"		Python	"python"

  • The Beautifier package supports many, many more language syntaxes but only the languages above have been ported to Foswiki at this point. If you need support for an additional syntax, please open an Enhancement Request to request the syntax you require.
• DOM Structure: The beautified code fragment is encapsulated within a <pre> element which, in turn, is encapulated within a <div> element which has two CSS class selectors, "fragment" and the language syntax identifier, which is itself encapsulated within a <div> element with the CSS class selector "BeautifierPlugin" as illustrated below.
  • <div class="BeautifierPlugin">
    • <div class=" language fragment">
      • <pre>
        • … beautified code fragment …
      • </pre>
    • </div>
  • </div>
  • Language-specific CSS styling can be applied to the beautified code fragment using CSS selectors of the form div.BeautifierPlugin div.language.fragment
  • Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.

Examples

The following examples illustrate the basic operation of the plugin and the %CODE% and %ENDCODE% macros.

Current default settings:

• BEAUTIFIERPLUGIN_LANGUAGE is: cpp
• BEAUTIFIERPLUGIN_CSS is: null

C++ Syntax

This example illustrates the basic use of the plugin to beautify a code fragment. The default language syntax is assumed to be C++ unless otherwise specified by the %CODE% macro or the BEAUTIFIERPLUGIN_LANGUAGE preference setting.

Lua Syntax With Custom CSS Styling

This example illustrates using the Lua syntax highlighting rules and also demonstrates how to modify the styling of display elements to define additional language-specific styling of the beautified code fragment. The URL of a custom stylesheet may be specified by the css paraemter of %CODE% macro or the BEAUTIFIERPLUGIN_CSS preference setting.

Unknown Syntax

If a language syntax is specified that the plugin doesn't know how to handle, it will simply display an error message and display the code fragment without any additional formatting or highlighting applied.

Preference Settings

The default expansion of the %CODE% macro may be altered by setting Foswiki preference settings. These settings can be placed in your wiki's Site Preferences topic, your web's Web Preferences topic, your own User Preferences topic, or the topic in which the %CODE% macro is used.

Setting	Description	Default
CSS	The URL of an optional CSS stylesheet to use for styling display elements generated by the plugin
DEBUG	Enable/disable logging of debug traces to the Foswiki Debug Log	off
LANGUAGE	The default language syntax to use when beautifying a code fragment	cpp

Note: In the table above, the "BEAUTIFIERPLUGIN_" prefix has been omitted from each of the setting names for brevity. In order to make use of a setting, you must use the full name of the setting including the prefix (e.g., "BEAUTIFIERPLUGIN_CSS").

Only one extended stylesheet may be supplied for a given topic using either the css="URL" macro parameter or the BEAUTIFIERPLUGIN_CSS preference setting. The final stylesheet specified is the one that will be used. If you wish to specify multiple customizations, combine all the CSS rules into a single stylesheet.

Setting Plugin Preferences

Use TML assignment statements in the body content or the topic preferences of a topic to set the value of a plugin preference. You can copy one or more of the example assignment statements below to set the desired preference value.

   * Set BEAUTIFIERPLUGIN_CSS = %ATTACHURL%/style.css
   * Set BEAUTIFIERPLUGIN_DEBUG = off
   * Set BEAUTIFIERPLUGIN_LANGUAGE = cpp

Installation

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

Plugin Info

Author:	TWiki:Main.LingLo, Foswiki:Main.WillNorris, & Foswiki:Main.BryanThale
Copyright:	© 2010, Foswiki Contributors
License:	GPL (GNU General Public License, Version 2)
Release:	1.0
Version:	7136 (2010-04-09)
Home:	Foswiki:Extensions.BeautifierPlugin
Support:	Foswiki:Support.BeautifierPlugin
Dependencies:	Name Version Description CGI >=0 Required, CPAN:CGI
Change History:
09 Apr 2010 (1.0):	Foswikitask:Item8844 - Port to Foswiki
20 May 2007:	added JavaScript language file, removed legacy CODE_lang construct
30 Apr 2007:	warnings cleanup; no functional changes
27 Apr 2007:	automatically adds CSS for formatting code fragments
01 Jan 2006 (Dakar):	upgraded to TWiki::Func::extractNameValuePair for better parameter parsing, upgraded TWiki:Plugins.BuildContrib support
26 Jul 2003:	Syntax fixes from TWiki:Main/WillNorris
10 Feb 2003 (Beijing):	Syntax fix from TWiki:Main/JoshMore
28 Dec 2002:	Accepts mixed case language names
20 Dec 2002:	Changed syntax to allow for simpler addition of new languages
16 Oct 2002:	Added nebula nodes and links to Python scripts, but it doesn't work since the node names are usually in strings
30 Jul 2002:	Added nebula nodes and links to TCL scripts
30 Jul 2002:	Changed Beautifier::Core to use 'linkscripts'
28 Jul 2002 (Athens):	Created

Related Topics: dp.SyntaxHighlighter