• View
• Edit
• History
• Attach
• Print
• Backlinks

ZCode

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" --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

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?