Wiko, the Wiki Compiler: Usage

Index

Modes

WiKo enables different modes of execution depending on what it founds on the working directory.

Wrapping HTML content

This is the simplest mode of usage. WiKo takes each .html file at the subdirectory 'content' and creates an homonym html files at the working directory by inserting such files into the skeleton at the point where you inserted the %(content)s tag.

This way you can fully update the look and feel of you web site just by updating the skeleton without having to edit every html file but still being an static page.

Generating HTML from wiki files

WiKo also takes any .wiki file in the working directory and will reformat it to an .html file also using the skeleton. In the example files you can take a look at the syntax we are using which is very similar to the one on Wikimedia and Moin-Moin wiki.

Just take a quick look at this Sample.wiki which has most syntax elements. It renders into this html file.

Generating PDF (LaTeX) from wiki files

WiKo can also generate PDF through LaTeX. LaTeX document skeletons are a bit different from html ones:

An example of a working directory:

Then WiKo will execute pdflatex and bibtex for the LaTeX skeleton.

Generating Blogs

Blog entries can be defined by adding files into the blog subdirectory of the working directory. WiKo analyzes such files and generates:

It requires some page variables to be defined in each entry. See the sample for details.

The blog mode is currently under heavy development. We would like to evolve it in two directions:

Generating download zones

A download zone is a folder with a set of files you want to list and download. WiKo generate directory listings which integrates on the web page look and feel.

You should create a file named downloadZones.wiko on the working directory just like that: 

{
	'dirs' : [
		("WiKo files", "download/"),
	],
	'blacklist' : [
		"index.html",
		"style.css",
		"img",
	],
	'skeletonFile' : "scheleton.html"
 }

dirs is a list of python tuples containing titles and paths for the download zones. The blacklist contains the files which should be ignored when generating the file index. And, skeletonFile is the html skeleton to be used with such pages. Be carefull as if you use the same skeleton, relative paths used for some links, images and styles, might be wrong.

Other features

Page dependent code on the skeleton

By using the wiki format you can also use variables to be inserted on the skeleton. You should introduce a line like this in the .wiki file. 

@variableName: value to use

and then using the tag %(variableName)s wherever you want to use it on the skeleton.

Inserting an html table of content

By inserting in a wiki content file the %(toc)s tag you can get in the html ouput a table of content which links to the headings of each section. Just like this manual.

Refering bibliography

The wiki format allows referencing BibTeX entries with the @cite directive. In the LaTeX mode, that has a direct mapping to the \cite command. In the HTML mode, a link is created to a web page called bibliography.bib.html which is an aggregation of every .bib file it founds in the working directory. The @cite directive points to the proper entry.

Access to the wiki source code

If you want to place a link to the wiki source in the skeleton use the %(wikiSource)s tag to get its url.

Using WiKo with version control system

WiKo increase its potential when you use it in combination of a version control system such as subversion. Subversion allows to write your WiKo based project collaborativelly. Project members have their own copy of the project in their own computer. They can modify it locally, confirm the changes remotelly to a central repository, and update other's changes. It also provides means for tracing changes and merging versions.

Just an advice, in order to avoid conflicts, put under the version control just those files that are not generated.

Revision and last modification

Subversion allows you to include on the file information on the revision number and the last modification date and author. 

svn propset svn:keywords "Revision Date Author" aFile.wiki

then you can insert in the wiki file text like this: 

$Revision$
$Date$
$Author$

And subversion will rewrite it on update as: 

$Revision: 242$
$Date: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002)$
$Author: vokimon$

A nice way of using it is placing such tags in @ variables so that you can place them in a fixed location in the skeleton.

Automatic update on commit

If you are using subversion, it is very convenient having the web updated automatically on every subversion commit. You will require:

Given that:

You should issue the following commands on your server: 

cd /var/www/
ssh-keygen       # and then, return, return, return, return...
ssh-copy-id svnuser@mysvnserver.com
svn co svn+ssh://svnuser@mysvnserver.com/home/svn/myproject/web myweb
(crontab -l ; echo '5,15,25,35,45,55 * * * * (cd /var/www/myweb && svn up && ./wiko) 2>&1 | cat > /var/www/myweb/err') | crontab -