Difference: BeautifierPlugin (r2 vs. r1)

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
     element which, in turn, is encapulated within a 
    element which has two CSS class selectors, "fragment" and the language syntax identifier, which is itself encapsulated within a
    element with the CSS class selector "BeautifierPlugin" as illustrated below.
        •  
          • … beautified code fragment …
    • 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.

    For the following code fragment:
    %CODE{"cpp"}%
    #include 
    
    /**
        @brief Advance the simulation by one timeslice.
    */
    void nWorld::StepSim()
    {
        // Iterate simulation loop
        for (node = entityList.GetHead(); node != NULL && j == 53; node = node->GetSucc())
        {
            entity = (nEntity*)node->GetPtr();
            entity->Trigger(this, this->stepSize);
        }
    }
    %ENDCODE%
      
    You would get (simulated):
    #include 
    
    /**
    @brief Advance the simulation by one timeslice.
    */
    void nWorld::StepSim()
    {
            // Iterate simulation loop
            for (node = entityList.GetHead(); node != NULL; node = node->GetSucc())
            {
                    entity = (nEntity*)node->GetPtr();
                    entity->Trigger(this, this->stepSize);
            }
    }
    
    You would get (actual):
    #include 
    
    /**
    @brief Advance the simulation by one timeslice.
    */
    void nWorld::StepSim()
    {
            // Iterate simulation loop
            for (node = entityList.GetHead(); node != NULL && j == 53; node = node->GetSucc())
            {
                    entity = (nEntity*)node->GetPtr();
                    entity->Trigger(this, this->stepSize);
            }
    }

    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.

    The extension stylesheet adds the following CSS styling rules to alter the outer border from pale yellow to pale pink and to make any colorized text bold.
    div.BeautifierPlugin div.lua.fragment {
            background: #FFCCFF;
    }
    div.BeautifierPlugin div.lua.fragment font {
            font-weight: bold;
    }
    
    For the following code fragment:
    %CODE{"lua" css="%ATTACHURL%/style_extension.css"}%
    Account = {}
    Account.__index = Account
    
    function Account.create(balance)
       local acnt = {}             -- our new object
       setmetatable(acnt,Account)  -- make Account handle lookup
       acnt.balance = balance      -- initialize our object
       return acnt
    end
    
    function Account:withdraw(amount)
       self.balance = self.balance - amount
    end
    
    -- create and use an Account
    acc = Account.create(1000)
    acc:withdraw(100)
    %ENDCODE%
      
    You would get (simulated):
    Account = {}
    Account.__index = Account
    
    function Account.create(balance)
       local acnt = {}             -- our new object
       setmetatable(acnt,Account)  -- make Account handle lookup
       acnt.balance = balance      -- initialize our object
       return acnt
    end
    
    function Account:withdraw(amount)
       self.balance = self.balance - amount
    end
    
    -- create and use an Account
    acc = Account.create(1000)
    acc:withdraw(100)
    
    You would get (actual):
    Account = {}
    Account.__index = Account
    
    function Account.create(balance)
       local acnt = {}             -- our new object
       setmetatable(acnt,Account)  -- make Account handle lookup
       acnt.balance = balance      -- initialize our object
       return acnt
    end
    
    function Account:withdraw(amount)
       self.balance = self.balance - amount
    end
    
    -- create and use an Account
    acc = Account.create(1000)
    acc:withdraw(100)

    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 highighting applied.

    For the following code fragment:
    %CODE{"klingon"}%
    	Heghlu'meH QaQ jajvam
    %ENDCODE%
      
    You would get (simulated):
    bomb Language 'klingon' not supported
    	Heghlu'meH QaQ jajvam
    
    You would get (actual):
    bomb Language 'klingon' not supported
    	Heghlu'meH QaQ jajvam
    

    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.

    SettingDescriptionDefault
    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").

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

    warning Warning! This plugin and the dp.SyntaxHighlighter plugin conflict and are not compatible as they both implement the %CODE% and %ENDCODE% macros. You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server. Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install". If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

    Manual Installation

    This plugin may be installed manually by downloading the distribution package attached to the Foswiki:Extensions.BeautifierPlugin topic.
    1. Install/upgrade any packages listed in Dependencies below
    2. Download the .zip or .tgz distribution package and place it in the root directory of your Foswiki installation.
    3. Unpack the distribution package
    4. Using the Foswiki configuration utility, enable the plugin. (If using an accellerator such as mod_perl, it may be necessary to restart your server before your configuration changes will take effect.)
    5. Set any default preference values in Site, Web, and User Preference topics as desired.

    Installation Test

    #include 
    
    /**
    @brief Advance the simulation by one timeslice.
    */
    void nWorld::StepSim()
    {
            // Iterate simulation loop
            for (node = entityList.GetHead(); node != NULL && j == 53; node = node->GetSucc())
            {
                    entity = (nEntity*)node->GetPtr();
                    entity->Trigger(this, this->stepSize);
            }
    }

    Manifest

    File:Description:
    data/System/BeautifierPlugin.txt Plugin documentation topic
    data/System/VarCODE.txt Syntax summary for the CODE macro
    data/System/VarENDCODE.txt Syntax summary for the ENDCODE macro
    pub/System/BeautifierPlugin/style.css Code fragment stylesheet
    pub/System/BeautifierPlugin/style_extension.css Code fragment stylesheet extension
    lib/Foswiki/Plugins/BeautifierPlugin.pm Plugin module
    lib/Foswiki/Plugins/BeautifierPlugin/LICENSE GNU GPLv2
    lib/Foswiki/Plugins/BeautifierPlugin/ANSI.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/Context.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/Core.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/DocBook.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HTML.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/Magic.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/MagicConfig.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_bash.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_cpp.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_csharp.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_html.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_java.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_javascript.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_lua.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_makefile.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_perl.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_php3.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_plsql.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_python.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_scheme.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_tcl.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_verilog.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_vhdl.pm  
    lib/Foswiki/Plugins/BeautifierPlugin/HFile/HFile_xml.pm  

    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:
    NameVersionDescription
    CGI>=0Required, 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

    IAttachmentActionSizeDateWhoComment
    style.csscssstyle.cssmanage 0.2 K 28 Apr 2007 - 13:01ProjectContributor CSS to format code fragments
    style_extension.csscssstyle_extension.cssmanage 0.1 K 28 Apr 2007 - 13:01ProjectContributor Example of an extension to the base CSS for code fragments

    View topic | View difference side by side | History: r2 < r1 | More topic actions
     
    This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
    Ideas, requests, problems regarding ALICE? Send feedback