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
- Place zcode.phpΔ in your pmwiki/cookbook directory.
- 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, heretar ...
. 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:) |
|
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
orlines=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:) |
|
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, documents, and more in wiki pages (Stable)
- Beautifier Perform syntax highlighting for source code displayed on wiki pages
- CodeMirror An enhanced page editor for PmWiki (Stable)
- 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.