Recent Changes - Search:

Cookbook

PmWiki

pmwiki.org

SourceBlock

Summary: Source code syntax highlighter for PmWiki 2.x using GeSHi
Version: 2014-09-08
Status: Stable
Prerequisites: pmwiki-2.1 and GeSHi (tested with v1.0.8.11)
Optional: Linked Resource Extras recipe for external files handling
License: MIT
Maintainer: Dfaure
Categories: Layout PHP55
Discussion: SourceBlock-Talk
Users: +7 (View / Edit)

Question answered by this recipe

I tried the (abandoned) Beautifier recipe to perform syntax highlighting for my source code but still wasn't very satisfied... What's next?

Description

Here you'll find SourceBlock: a script recipe dedicated to syntax highlighting, which offers more features:

  • Numbered lines on some source code.
  • Ordered lists item number preserved when mixed with source code excerpts.
  • Extra highlighting to point-out specific source lines.
  • Page layout preserved with auto/forced word wrapping of source code lines.
  • Language neutral mode without errors when the language is not specified or not recognized.
  • Link to view/download individual source code excerpts.

Notes and Comments

SourceBlock is based on GeSHi, an actively developed source code highlighting script, already used in several other wiki systems.

Installation

  1. Download and copy sourceblock.phpΔ to the cookbook/ directory.
  2. Download and unpack GeSHi distribution to a newly created cookbook/geshi directory.
    1. GeSHo development and downloads have moved to https://github.com/GeSHi/geshi-1.0
    2. Although the 1.0 branch still works with recipe, the workability of the 1.1 branch is untested
  3. Enable the recipe in your local/config.php file with:
    include_once("$FarmD/cookbook/sourceblock.php");

Markup

Once installed, it adds markup of the form:

(:source PARAMETERS... :) [@
source code
@]

and:

(:source PARAMETERS... :)
source code
(:sourceend:)

with the following optional PARAMETERS:

  • lang=LANGUAGE to select one of the supported highlighters,
  • linenum{=LINE_NUMBER} to enable line numbers and optionally specify styling alternative,
  • linestart=START_NUMBER to specify the initial line number.
  • tabwidth=TAB_WIDTH to set the number of spaces to use for tab replacement(*).
  • header=TEXT and footer=TEXT to surround the source code(*).
  • highlight='LINE_NUMBER1, LINE_NUMBER2,...' to specify the line numbers to point-out (separators are spaces, comma and semicolon).
  • -trim to disable the automatic trimming of source.
  • -link to disable the automatic generation of documentation links(*).
  • -getcode, +getcode to disable or enable the "Get Code" view/download code link (see below).
  • id=ID, class=CLASS to overload default styles definitions.
(*)Only meaningful with lang=LANGUAGE defined.

SourceBlock configures GeSHi to use <div> and style sheets then word wrapping is less problematic.

In order to be a full alternative to CodeBlock, SourceBlock provides following extra markup to generate <pre>(formatted) sections (with optional wrapping):

(:code wrap=OUTPUT_WIDTH :) [@
source code
@]

and:

(:code wrap=OUTPUT_WIDTH :)
source code
(:codeend:)

Both markups don't need to start a new line, and may be appended to list elements without altering their order.

The extra "Get Code" link provides a direct access to the unformatted code. The markup also handle the related parameters:

  • filename=<name> to provide a relevant name to the block.
  • -inline to force browsers to download the block content (ie. sole available behavior in Internet Explorer).

Blocks appearance is controlled via style sheets parts overrideable in config.php. Defaults style are given as recipe samples in the sandbox below.

An additional:

(:source langs:)

markup form is available to list all the languages supported by the GeSHi installation.

Optional external file handling

The recipe script detects any previous installation of the Linked Resource Extras recipe and if so, provide the two more markup directive to render external files:

(:source FILE_RESOURCE PARAMETERS... :)

and:

(:code FILE_RESOURCE PARAMETERS... :)

The markup parameters have the same meaning. Please refer to Linked Resource Extras recipe page for more details on the FILE_RESOURCE specification itself.

SandBox

(:source lang=css header="$HTMLStylesFmt['sourceblock'] = '" footer="';":)
[=
.sourceblocklink {
  text-align: right;
  font-size: smaller;
}
.sourceblocktext {
  padding: 0.5em;
  border: 1px solid #808080;
  color: #000000;
  background-color: #F1F0ED;
}
.sourceblocktext div {
  font-family: monospace;
  font-size: small;
  line-height: 1;
  height: 1%;
}

.sourceblocktext div.head,
.sourceblocktext div.foot {
  font: italic medium serif;
  padding: 0.5em;
}=]
$HTMLStylesFmt['sourceblock'] = '
.sourceblocklink {
  text-align: right;
  font-size: smaller;
}
.sourceblocktext {
  padding: 0.5em;
  border: 1px solid #808080;
  color: #000000;
  background-color: #F1F0ED;
}
.sourceblocktext div {
  font-family: monospace;
  font-size: small;
  line-height: 1;
  height: 1%;
}

.sourceblocktext div.head,
.sourceblocktext div.foot {
  font: italic medium serif;
  padding: 0.5em;
}
';
(:source lang=css header="$HTMLStylesFmt['codeblock'] = '" footer="';":)
.codeblocklink {
  text-align: right;
  font-size: smaller;
}
.codeblocktext {
  text-align: left;
  padding: 0.5em;
  border: 1px solid #808080;
  color: #000000;
  background-color: #F1F0ED;
}
.codeblocktext pre {
  font-family: monospace;
  font-size: small;
  line-height: 1;
}
(:sourcend:)
$HTMLStylesFmt['codeblock'] = '
.codeblocklink {
  text-align: right;
  font-size: smaller;
}
.codeblocktext {
  text-align: left;
  padding: 0.5em;
  border: 1px solid #808080;
  color: #000000;
  background-color: #F1F0ED;
}
.codeblocktext pre {
  font-family: monospace;
  font-size: small;
  line-height: 1;
}
';
(:source lang=bash:)
#!/bin/sh

# petit script qui genere la cle et le certificat d'un site https
DIR=/etc/apache-ssl/ssl-cert
# nom du certif/du site
NAME=$1
SSL=`which openssl`

# check if dir is OK
if [ ! -d $DIR ]; then
        echo "Dir $DIR not found, building it."
        mkdir -p $DIR
fi
(:sourcend:)
#!/bin/sh

# petit script qui genere la cle et le certificat d'un site https
DIR=/etc/apache-ssl/ssl-cert
# nom du certif/du site
NAME=$1
SSL=`which openssl`

# check if dir is OK
if [ ! -d $DIR ]; then
        echo "Dir $DIR not found, building it."
        mkdir -p $DIR
fi
(:source lang=sql linenum tabwidth=4 :)
-- Find all Boards and the schools they Govern
-- Include the status of the school

SELECT sch.orgname AS 'SchoolName', 
	bot.orgName AS 'BoardName', 
	sch.[OrgEventStatusCode] AS Status
FROM organisation AS sch,
	orgGroup AS og ,
	organisation AS bot
WHERE bot.BusinessEntityID = og.OrgBusinessEntityID	-- get the org that is
the OWNER
AND og.MemberBusinessEntityID = sch.BusinessEntityID	-- get the org that
is the MEMBER
AND og.OrgGroupEndDate is NULL		-- NOT an ended group membership
AND og.orgRoleGroupCode = 'GOVERN'	-- Group for school boards
AND og.OrgRoleCode = 'SCHBRD'		-- Role for school board members
ORDER BY BoardName
(:sourcend:)
  1. -- Find all Boards and the schools they Govern
  2. -- Include the status of the school
  3.  
  4. SELECT sch.orgname AS 'SchoolName',
  5.     bot.orgName AS 'BoardName',
  6.     sch.[OrgEventStatusCode] AS STATUS
  7. FROM organisation AS sch,
  8.     orgGroup AS og ,
  9.     organisation AS bot
  10. WHERE bot.BusinessEntityID = og.OrgBusinessEntityID -- get the org that is the OWNER
  11. AND og.MemberBusinessEntityID = sch.BusinessEntityID    -- get the org that is the MEMBER
  12. AND og.OrgGroupEndDate IS NULL      -- NOT an ended group membership
  13. AND og.orgRoleGroupCode = 'GOVERN'  -- Group for school boards
  14. AND og.OrgRoleCode = 'SCHBRD'       -- Role for school board members
  15. ORDER BY BoardName
# blupp blupp blupp\\
(:source lang=php:)
<? echo "here's some code"; ?>
(:sourcend:)

# blipp blipp
  1. blupp blupp blupp
    <? echo "here's some code"; ?>
  2. blipp blipp
(:source lang=xml:)
<skos:Concept rdfs:label="root"
xmlns:skos="http://www.w3.org/2004/02/skos/core"
  xmlns:my="http://www.ontologies.thomson.com/MyVocabulary" 
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema" tr:index="1">
</skos:Concept>
(:sourcend:)
<skos:Concept rdfs:label="root" xmlns:skos="http://www.w3.org/2004/02/skos/core"
 xmlns:my="http://www.ontologies.thomson.com/MyVocabulary"
 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema" tr:index="1">
</skos:Concept>

Release Notes

2014-09-08
Fixed stupid bug
2014-08-26
Updated recipe for PHP 5.5
2012-07-06
Fixed bug in style handling (multiple blocks on the same page).
2012-07-05
Integrated suggested modifications (trimming reduced to line-breaks, sorted languages list).
2009-01-27
Fixed multiple blocks of code with different languages on the same page bug. Fixed 'linenum=...' option and introduced 'linestart=...'.
2008-09-16
Fixed the '-getcode' option handling for the (:source:) markup.
2008-06-12
Fixed bugs introduced by previous style features and some code cleanup.
2008-06-11
Added the 'id=...' and class=... style related options. Reduced PHP notice messages. Fixed bug in option handling.
2008-01-02
Added (:source langs:) markup to list supported languages.
2007-12-05
Fixed XHTML validation issue.
2007-10-18
Fixed external file handling (was limited to Attachments).
2007-09-13
Fixed trimming bug. Added ';' as highlighting line separator
2007-09-10
Added the '-getcode' option. Renamed the confusing '-attach' to '-inline' option.
2007-05-07
Added forgotten <:vspace> fix.
2007-04-30
Code cleanup. Added a fix to "Get Code" feature. Added support for external files.
2006-10-25
Added RecipeInfo data.
2006-09-07
Code cleanup. Added highlight feature.
2006-03-07
Fixed IE css glitch. Updated licensing terms.
2006-02-28
Heavily revamped to allow view/download of individual source code excerpts.
2005-09-04
Fixed <:vspace> oddities with 2.0.0 and above.
2005-06-15
Fixed bug eating last line when using source without lang attribute.
2005-04-01
Fixed bug preventing different languages on the same page.
2005-03-29
Synced with 2.0.beta27 markup directive syntax.

See Also

Beautifier, Linked Resource Extras.

Contributors

Comments

See discussion at SourceBlock-Talk

User notes +7: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.

Edit - History - Print - Recent Changes - Search
Page last modified on September 08, 2014, at 09:08 AM