ZCode

Summary: Extract and highlight source code files from 7z, TAR, ZIP, or RAR archives
Version: 20170812a
Prerequisites: PmWiki 2.2.56, `7z`, `tar`, `unzip`, or `unrar`
Status: Experimental
Maintainer: Petko
License: GPLv3+
Users: +1 (view / edit)
Discussion: ZCode-Talk?

Questions answered by this recipe

When discussing PmWiki core development (PITS), how can we integrate source code from the core into wiki pages?

Description

This recipe provides a way to display in a wiki page source code extracts from TAR, 7z, ZIP, RAR or other archives.

The archives are all in a directory like here. The recipe allows to easily embed into the wiki page a slice of any file from any archive from that directory.

The recipe was written to help discussions about the PmWiki core on the PITS: PmWiki Issue Tracking System but can be used for other projects.

This does not require a subversion-to-html system or a browsecvs/websvn server, just the archives with the releases.

Installation

  1. Place zcode.phpΔ in your pmwiki/cookbook directory.
  2. Add to config.php the following snippet (read below about configuration):
    $ZCode['Archives'] = '/home/pmwiki/www/pub/pmwiki/pmwiki-%s.zip';
    $ZCode['DefaultVersion'] = 'latest-svn';
    include_once("$FarmD/cookbook/zcode.php");
    

Configuration

The following variables can be defined in config.php or Group.php:

  • $ZCode['Archives'] = 'archives/file-%s.tgz'; # the path to the source code archives, "%s" will be replaced with the version.
  • $ZCode['DefaultVersion'] = 'latest'; # the default version if not specified in the wiki page.
  • $ZCode['VersionChars'] = '-\\w.'; # the regex characters allowed in a version string.
  • $ZCode['FilenameChars'] = '-\\w.\\/'; # the regex characters allowed in a file path.
  • $ZCode['FilenameExts'] = 'php|tmpl|txt|css|htaccess|js'; # the file extensions that can be printed in the page, case insensitive (obviously, binary files like pictures shouldn't be included here).
  • $ZCode['SingleLinePad'] = 4; # how many lines to display above and below a single selected line.
  • $ZCode['ExtCommands']['tar|tgz|tar\\.gz'] = 'tar -f "%s" --wildcards --get "*%s" --to-stdout'; # The supported extensions for archives, case insensitive, here *.tar, *.tgz or *.tar.gz, and the system command that will print a single file from that archive to stdout, here tar .... The first "%s" will be replaced with the archive path, the second "%s" will be replaced with the file-to-extract path within the archive.
  • $ZCode['Langs']['tmpl'] = 'html'; # file extension => language for highlighting, if not defined here, the file extension will be used to guess the language.

Internationalization

The following strings can be translated in an XLPage:

  "No such file:" => "",
  "Unsupported archive:" => "",
  "Unsupported file name:" => "",
  "Command <code>%s</code> returned error code '%s'." => "",
  "Unsupported line format:" => "",

Usage

In the wiki page, you can use the markup:

(:zcode version=latest file=pub/skins/pmwiki/pmwiki.css lines=25..29 lang=css:)
/* These primarily adjust the size and spacing of heading elements,
** most browsers have atrocious defaults for these. */
h1, h2, h3, h4, h5, h6 { margin-top:1.0em; margin-bottom:0.6em; }
h1, h2, h3, h6 { font-weight:normal; }
h4, h5 { font-weight:bold; }

The parameters are as follows:

  • version=2.2.87 (optional) the version part of the archive name, defined in $ZCode['Archives']. If not set, $ZCode['DefaultVersion'] will be assumed.
  • line=33 or lines=20..30 (optional) to only show selected lines from the file. If not set, the full file will be printed. If a single line is set, the context of that line, with the 4 lines before and after it, will be printed. If 2 line numbers are provided, the lines from the source file between those numbers (included) will be printed.
  • file=pmwiki.php (required) the file to be extracted and shown. You can either set the full path (within the archive) to the file or just the file name (if there is only one file with that name in the archive).
  • lang=html (optional) the syntax highlighting language (if unset, will try to guess it).

There is a shortcut version for the above markup, version:file.ext@lines where version: and @lines are optional:

(:zcode 2.2.102:pmwiki.php@439..442:)
function SDVA(&$var,$val)
  { foreach($val as $k=>$v) if (!isset($var[$k])) $var[$k]=$v; }
function IsEnabled(&$var,$f=0)
  { return (isset($var)) ? $var : $f; }

Notes

  • If the last line of the displayed file or slice is empty, it may not appear numbered in the page.
  • Currently file names with no extension, eg README, can not be shown in the wiki page.

To do / some day / maybe

  • A way to emphasize/focus (yellowish background?) certain lines.
  • An actual svn-to-html export would be nice.
  • Diffs between versions.

Change log / Release notes

  • 20170812a: add lang=, 7z and RAR archives, remove ZipExts, TarExts, UnzipCommand, UntarCommand (all replaced with $ZCode['ExtCommands']).
  • 20170812: first public release, ready to be tested.

See also

Cookbook /
Ape  Embed videos, maps and more in wiki pages (Stable)
Beautifier  Perform syntax highlighting for source code displayed on wiki pages
CodeMirror  An enhanced page editor for PmWiki (Release Candidate)
Gists  Markup to allow easy embedding of syntax-highlighted github gists (active)
PITS  The PmWiki Issue Tracking System (Beta)
PmPygment  Display code highlighting using Python pygment (Stable)
Precode  General utility block markup for displaying codes with syntax highlighting (Active/Stable)
SourceBlock  Source code syntax highlighter for PmWiki 2.x using GeSHi (Stable)
Syntaxlove  Syntax highlighting with good look and cool JavaScript-effects

Contributors

  • This recipe for PmWiki integration, with file extracting, slicing and line numbers, was written and maintained by Petko.
  • highlight.js by Ivan Sagalaev highlights the code embedded in the HTML page.

Comments

See discussion at ZCode-Talk?

User notes +1: 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.