[H-GEN] Cool stuff: ikiwiki and sputnik

[Anthony Towns]

Hey all,

Every now and then I think to myself, "Self, wouldn't it be nice if there
was something a news show/paper/whatever that actually talked about the
good news that was going on rather than focussing on disasters and abuse
and politics and strife with occassional puppies and kittens thrown
in just to keep you on your toes." Sadly, thinking to myself doesn't
seem to have had much result, so I thought I might see about randomly
posting some interesting stuff here, that others might enjoy and maybe
take up themselves.

So anyway, ikiwiki and sputnik! They're both minimalist wikis; minimalist
in the Unix-y sense of relying on other programs/components to add
various features rather than in the sense of not having features.

I think ikiwiki came first, certainly I heard of it first, and it's
Joey Hess's take on what would happen if you had wikis get compiled
from "source" rather than dynamically rendered anytime anyone requests
anything. His source is thus a bunch of text files in markdown, which
are parsed into HTML using pre-written markdown to HTML translators
[0] along with special handling of double-bracketted wiki links (so
[[FooBar]] goes to the FooBar page on the wiki). Other special handling
lets you do all sorts of things like include content from other pages
so you don't have to write the same stuff multiple times [1], or add
comments to a page [2], run polls [3], or colourise code samples [4],
or include graphs directly on a page [5], or a zillion other things. You
can use it as a blog [6], or as a bug tracking system [7]. And since it
fundamentally just compiles things from a bunch of text files, you can
use your favourite editor and version control system [8] to keep it up to
date. (And if you favourite editor is the text entry box in your web
browser, that's fine too [9])

 [0] http://daringfireball.net/projects/markdown/
 [1] http://ikiwiki.info/ikiwiki/directive/inline/
 [2] http://ikiwiki.info/plugins/comments/
 [3] http://ikiwiki.info/ikiwiki/directive/poll/
 [4] http://ikiwiki.info/plugins/contrib/highlightcode/ 
 [5] http://ikiwiki.info/ikiwiki/directive/graph/
 [6] http://kitenet.net/~joey/screencasts/ikiwiki_blog/
 [7] http://ikiwiki.info/bugs/
 [8] http://ikiwiki.info/rcs/
 [9] http://ikiwiki.info/cgi/

The downside of ikiwiki is it's written in perl by people who like the
aesthetics of perl -- which is to say, installations generally end up
looking very Web 1.0. Sadly, I'm a bit superficial on that score, and
so went in search of something that was similarly lightweight but also
a bit prettier. sputnik was what I found.

It's written in lua. Apparently is the language of choice for embedding
into games, though personally I'm more familiar with it from window
managers like ion (which I've used, and liked) and awesome (which I
haven't used, but seems to be the new new thing). As far as I can tell,
it's yet another dynamically interpreted procedural language, something
like python without all the standard libraries (which is apparently what
makes it easy to include in games, where implementing large standard
libraries would be annoying and irrelevant).

Anyway, is a little bit more heavyweight than ikiwiki -- while it still
stores each page as just a text file on disk (and again uses markdown as
its default markup text), it surrounds the markdown with a few little
bits of lua to encode the pagetitle, and any abnormal behaviours the
page might have. Abnormal behaviours are things like "this page actually
stores the salted/hashed passwords for the users of the wiki" or "this
page is actually a bug/ticket, so limit how it's edited", etc. But that
doesn't make things too much more complex, and like ikiwiki it lets you
do version control of its pages more or less however you like (using git
and having an sqlite database for all the versions of all the pages are
the main alternatives [10]).

One of the cool things about sputnik is it applies cool hackery into
making it look pretty too. Rather than just saying "edit the CSS if you
want to change the look and feel", it gives a simpler option by letting
you change the default colour scheme by just picking a single point on the
colour wheel: it'll then automatically calculate complementary/contrasting
colours, and use those to distinguish different parts of the UI [11].

Interestingly (to me, anyway) it's also the wiki used for python-markdown
[12] -- even though lua's markdown and python markdown are different in
a variety of ways.

 [10] http://spu.tnik.org/en/Storage
 [11] http://spu.tnik.org/en/Color_Schemes
 [12] http://www.freewisdom.org/projects/python-markdown/

Anyway, the reason I've been looking into this stuff is I've been wanting
to find a pleasant way to make my code feel a bit more "professional", by
which I mean "something that doesn't just work, but looks respectable",
not "hacked up just in time to meet a customer deadline and hopefully
never seen by anyone ever again". And I've been thinking that having it
appear in a pretty wiki-ish environment, surrounded by literate-style
design commentary, and nicely marked up might be an effective way of
going about it.

After a bit of hax0ring (most notably to make sputnik use python-markdown
instead of lua's markdown) I came up with:

    http://junkcode.erisian.com.au/

It's named as per Tridge's junkcode, of course:

    http://www.samba.org/junkcode/

In particular, I can dump markdown text into a page (with code indented
by four spaces as usual for markdown) [13], have it come up nicely displayed
with syntax colouring [14] by default, automatically extract the code [15]
so that I can directly execute it, be reasonably confident any changes
are tracked by version control [16], and even follow any changes I make
(or potentially anyone else makes) by RSS [17].

 [13] http://junkcode.erisian.com.au/rm-arch-qual.raw_content
 [14] http://junkcode.erisian.com.au/rm-arch-qual
 [15] http://junkcode.erisian.com.au/rm-arch-qual.tangle_raw
 [16] http://junkcode.erisian.com.au/rm-arch-qual.history
 [17] http://junkcode.erisian.com.au/rm-arch-qual.rss

Anyway, I thought that was kinda nifty and interesting!

Cheers,
aj

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 163 bytes
Desc: Digital signature
URL: <http://lists.humbug.org.au/pipermail/general/attachments/20090818/723e89cb/attachment.sig>