Wiki Time

The World Wide Web was created to enhance scientific collaboration and foster information sharing. But for some reason, the vast majority of the Web remains read-only. Few sites let random users make changes to the content, structure, or look and feel of a Web page. On most sites you can't easily edit what's there, or upload new documents and files, or easily allow others to do the same.

The World Wide Web was created to enhance scientific collaboration and foster information sharing. But for some reason, the vast majority of the Web remains read-only. Few sites let random users make changes to the content, structure, or look and feel of a Web page. On most sites you can’t easily edit what’s there, or upload new documents and files, or easily allow others to do the same.

You might be thinking that there are many sites that allow you to participate in one form or another. Sure, you can get involved in a discussion, or vote for your favorite product in a poll; a few e-commerce sites let you vote and comment on products. But most sites provide limited interaction. In general, sites that allow you to participate in one manner or another focus primarily on discussion — often moderated discussion.

Discussion Isn’t Collaboration

Some of the notable exceptions in a predominantly read-only Web are the online news and discussion sites like Slashdot, Kuro5hin and use Perl;. Such sites are often powered by Slashcode, PHP-Nuke, PostNuke, PHPSlash, Scoop, and similar software. (In fact, we looked at PostNuke in the May and June issues of Linux Magazine. See http://www.linux-mag.com/2002-05/lamp_01.html and http://www.linux-mag.com/2002-06/lamp_01.html.)

Slashcode, PHP-Nuke, and the others share a lot of common features: threaded discussions, polls, RSS syndication, on-line journals and diaries, and so on. However, even with those features, those systems are still not collaborative. Systems like PHP-Nuke are about building communities around shared interests, and discussing topics and stories that have been pre-selected by their editors. Normal users have very little control over the content on the site, and the site framework isn’t easily changed.

More traditional bulletin boards like those hosted on BroadBand Reports (http://broadbandreports.com) and ArsTechnica (http://arstechnica.com) are another flavor of on-line community. Those communities are powered by a family of bulletin board software packages with similar features. They’re often highly optimized for power users — the ones who read a lot of discussions and contribute frequently — but again, the framework is fairly rigid.

Enter the Wiki World

If you’ve never heard of Wiki before, you may not even know how to pronounce it: “wee-kee,” like “geeky.” What is Wiki? According to the wiki.org Web site (http://wiki.org/wiki.cgi? WhatIsWiki), Wiki is…

… a piece of server software that allows users to freely create and edit Web page content using any Web browser. Wiki supports hyperlinks and has a simple text syntax for creating new pages and crosslinks between internal pages on the fly.

An important precept of Wiki technology is that any user can make changes and contributions (by default). The site goes on to say:

Like many simple concepts, “open editing” has some profound and subtle effects on Wiki usage. Allowing everyday users to create and edit any page in a Web site is exciting in that it encourages democratic use of the Web and promotes content composition by nontechnical users.

The original Wiki was created back in 1995 to help automate the process of maintaining the Portland Pattern Repository. Since then, Wiki usage has grown steadily and many Wiki clones have appeared. There are now Wikis written in PHP, Perl, Python, C, Java, and more. (A more complete history of Wiki technology is available at http://c2.com/cgi/wiki? WikiHistory.)

This month and next, we’ll spend some time looking at Wiki technology and focus specifically on TWiki. TWiki is a GPL’ed Wiki created by Peter Thoeny (Peter@Thoeny.com) of Wind River software. TWiki is written in Perl, and uses the widely-available Revision Control System (RCS) behind the scenes so that changes to each page can be recorded and “rolled-back” if necessary.

Wiki Basics

Okay, so what about Wiki makes it easy for users to collaboratively maintain a Web site?

  • Wikis greatly simplify the process of marking up and formatting documents. Rather than the large set of tags available in HTML, Wiki users use a simplified mini-language. (But many Wikis also allow you to use HTML if you prefer to do so.)

  • Pages hosted in a Wiki all have “edit” links or “edit” buttons on them. Clicking either the link or the button takes you to an editing page that contains the “source” of the previous page. You can make the changes you’d like and save them. Instant editing. It’s that easy.

  • Wikis also simplify hyperlinks. Instead of hand-coding URLs to other pages, you simply insert the URL and the Wiki links it for you. And, if you’d like to add a new page or concept to the site and link to it, just refer to it using a WikiWord and you’ll be able to create the page automatically. Once the new page is created, the WikiWord automatically becomes a hyperlink to it.

That’s right. Adding a new page to a Web site is as easy as thinking up a name for it and typing it in. Once you put some content on the new page, all references to it are automatically linked.

Wiki Security

It’s worth noting that having a “world-writable” Web site isn’t as problematic as it sounds. With a reasonably active site, the few cases of vandalism or spamming that you’re likely to see are quickly corrected. The benefits of being world-writable far outweigh the possible problems.

For example, look at the EmacsWiki (http://www.emacswiki.org/). Anyone can contribute material to the site. As a result, it’s become quite a large collection of knowledge, tips, and tricks for users of both GNU Emacs and xemacs.

However, if you want more control, many Wikis allow you to impose access controls so that only authorized users can make changes. Alternatively, you can mark certain pages as read-only to the general public.


WikiWords are the basic building blocks of pages in a Wiki. If you’re working on a page and think of an idea that deserves its own page, just name it — but name it in a special way.

Let’s say you’re writing about software necessary for running a Web site with open source tools. You realize that nobody has added a section on Apache security yet. Simply type “ApacheSecurity” (no spaces) into the document. Once you save it, you’ll notice a question mark after the term. If you click on the question mark, you’ll jump to the ApacheSecurity page where you can add content. Once you create some content for that page, the original reference to ApacheSecurity becomes a hyperlink to the document you just created.

That squishing together of two or more words is the essence of WikiWords. Of course, there are rules to follow, and each Wiki implementation may have subtle variations on WikiWords. But for TWiki, the rules are simple:

  • Start every WikiWord with one or more upper-case letters.

  • Followed by one or more lower-case letters

  • Followed by one or more uppercase letters.

  • Followed by one or more lower-case, digits, or upper-case.

To make this a bit more concrete, here are some good WikiWords: FontSizes, WebContent, ChangePassword, and TcpPort80. And some bad ones: W3pages (needs at least one upper, lower, upper sequence); Font-Size (can’t have a dash in the middle); and Port80Traffic (numbers must come after the upper, lower, upper sequence).

That’s a quick lesson in WikiWords. For more in-depth information, check the TWikiWord documentation (http:// twiki.org/cgi-bin/view/TWiki/WikiWord).

TWiki Syntax

Let’s look at the short set of rules that govern TWiki’s markup syntax. Again, remember that TWiki’s markup is intended to be simple. It’s not as expressive as HTML, but for newcomers it’s a lot easier to learn.

  • Paragraphs are separated by blank lines.

  • Bold textis marked with asterisks: *Bold text*

  • Italic text is marked with underscores: _Italic text_

  • Bold Italic is marked with double underscores: __Bold Italic__

  • Monospaced text is marked with equal signs: =Monospaced text=

  • Bold monospaced text is tagged with double equal signs: ==Double equal sign==

  • Links are created using WikiWords.

  • To create an external link, simply include the full url starting with “http://.”

As with HTML, you can have headings from level one (largest) to level six (smallest). They are denoted by a line that begins with three dashes, one or more pluses, a space, and then text. The number of pluses defines the heading level. So, to create a level two heading, you’d write —++ Level 2 is here on a line by itself. And so on.

There’s markup for producing numbered lists, basic tables, images, and more. See the WikiSyntax documentation for details (http://twiki.org/cgi-bin/view/TWiki/WikiSyntax). The TwikiShorthand page provides extensive examples of all kinds of Wiki markup (see http://twiki.org/cgi-bin/view/TWiki/TWikiShorthand).

TWiki markup takes a little getting used to, but once you’re comfortable with it, you’ll notice that it becomes second nature. Not only is it a lot easier to type than HTML, you’ll be able to accomplish quite a bit with just a small subset of the available markup.

TWiki Features

Briefly, here are some of the reasons that Wiki technology, and TWiki in particular, is becoming popular:

  • Pages can be grouped into logical units called “webs” without any special configuration on the server.

  • All pages are kept under revision control, so you can see who changed what, when a change was made, and roll-back changes when necessary.

  • TWiki has built-in full-text search with regular expressions.

  • You can upload files as “attachments” to pages.

  • TWiki has a plug-in architecture that makes it easy to add functionality. There’s a growing repository of official and unofficial plug-ins available.

And that’s only scratching the surface. See the TWiki home page for an exhaustive list of its features.


To get a copy of TWiki, visit the TWiki web site (http://twiki.org) and request one. The author likes to keep track of who is using his software. The e-mail you get in response will contain a download link like http://TWiki.org/TWiki20011201.zip.

Detailed installation instructions are available on the TWiki site, but these should work for most users.

Pick a directory into which you’d like to install TWiki and unzip the file there:

$ cd /home/apache
$ mkdir twiki
$ unzip /tmp/TWiki20011201.zip

Next, you need to configure Apache to treat the TWiki directories appropriately. The bin directory must be treated as a cgi-bin directory, meaning that the contents are executable. The pub directory must be visible to the world. However, the templates and data directories should not be accessible from the Web.

The necessary configuration in Apache’s httpd.conf file looks like this:

ScriptAlias /twiki/bin/ “/home/apache/twiki/bin/”
Alias /twiki/ “/home/apache/twiki/”
<Directory “/home/apache/twiki/bin”>
Options +ExecCGI
SetHandler cgi-script
Allow from all
<Directory “/home/apache/twiki/pub”>
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
<Directory “/home/apache/twiki/data”>
Deny from all
<Directory “/home/apache/twiki/templates”>
Deny from all

With that done, test and restart Apache if there are no problems.

$ sudo bash
# apachectl configtest
# apachectl restart

Now make sure that all of the scripts in the bin directory are executable.

$ chmod 755 bin/*

Next, make sure all of the files are owned by the same user that Apache runs as. On many systems that’s nobody. On Debian, it’s www-data.

$ sudo chown -R nobody /home/apache/twiki

Then try accessing your TWiki site’s testenv script, using the URL http://example.com/twiki/bin/testenv. It will run some routine checks and issue warnings or errors if it finds problems with your configuration. Ignore any warnings about the configuration file since we haven’t adjusted it yet.

When there are no relevant warnings, the last step is to make a few changes to the configuration file, lib/TWiki.cfg. In that file, you’ll find a section marked variables that need to be changed when installing on a new server. Check to make sure those variables are correct based on your installation. For the example we’re using, they are:

$wikiHomeUrl = “http://example.com/twiki“;
$defaultUrlHost = “http://example.com“;
$scriptUrlPath = “/twiki/bin”;
$pubUrlPath = “/twiki/pub”;
$pubDir = “/home/apache/twiki/pub”;
$templateDir = “/home/apache/twiki/templates”;
$dataDir = “/home/apahce/twiki/data”;

Then visit the testenv URL one more time to verify that TWiki has no complaints about your settings.

Finally, consider adding your site to the TWikiClones list at http://TWiki.org/cgi-bin/view/Main/TWikiClones.

Figure One: The initial TWiki home page

Figure Two: The initial TWiki webs

Figure Three: The Test web

Figure Four: TWiki edit options

Figure Five: Editing a TWiki page

Figure Six: Previewing a modified page

Figure Seven: A newly-created WikiWord page


With installation out of the way, point your browser at http://example.com/twiki and you should see a welcome page that looks like Figure One (). That’s simply the static index.html file in your twiki directory. You can customize it to say anything you’d like. It can serve as a “splash page” for users of your TWiki.

Click the “get started” link to go to a TWiki node (Figure Two, ) containing various starting points and information about your TWiki setup.

Notice the colorful table on the page. It lists the webs that are available by default. Main is where you started. The TWiki web contains TWiki documentation and tutorials. Know is a prototype for a simple on-line knowledge base. Finally, the Test web, described as “Sandbox test area with all features enabled.”, is where you should experiment with TWiki until you’re comfortable with how everything works. It can seem a bit overwhelming at first.

Notice the “changes” and “search” links in the table. The first allows you to list the recent changes for each web. Using the search link, you can look for content in just one web.

To get started, click on the Test web. You’ll see a page that looks like Figure Three () at the top. Scroll down and notice the grey bar at the bottom (Figure Four, ). Click the Edit link. You can then edit the page and save it.

The edit page should look like Figure Five (). The text editing window contains the source code for the page you just saw. While reading the text, you’ll notice the use of %VARIABLES% in several places. Rather than hard-coding meta-data like the name of the current web, TWiki exposes a set of variables that you can use in your documents.

Try inserting TestWord at the top of the text followed by a blank line. Then hit the Preview Changes button. The next page (Figure Six, ) shows what the page will look like if you choose to save it. Notice that “TestWord?” now appears near the top of the page.

Scroll to the bottom of the page and click the Save Changes button. You’ll be taken back to the page after your change is committed. The “TestWord?” should appear just as it did in the preview.

That’s it. You’ve just edited a living document on the web. If you click the Changes link in the top grey bar, you’ll be shown a list of all the recent changes in the web. The first one should be the edit you just completed.

Now, to finish the cycle, let’s create a page for “TestWord” to link to. Click on the question mark after “TestWord” and you’ll be taken to a virtually blank editing page. Practice your WikiWord and markup by entering some text:

- – - + Test Page

This is a *test page* that I’ve created
using my first WikiWord. With a bit more
practice, I’ll get the hang of this in _no
time_ at all.

Hit the Preview Change button to see what it looks like, and click Save Changes when you’re happy with the text. You’ll be taken to the newly created page for TestWord (Figure Seven). If you navigate back to the page you started from, you’ll see that the question mark after “TestWord” is gone, and the word is now a link to the page you just created. Congratulations! You just tweaked TWiki.

More to Come

That’s all there is to it. With just a few mouse clicks you can build infinitely complex sites with cross-linked terms and powerful search capabilities.

That’s our introduction to TWiki. Next month we’ll look at advanced TWiki configuration, add-in modules, and more. Stay tuned!

Jeremy Zawodny uses Open Source tools at Yahoo! by day, and is writing a MySQL book for O’Reilly & Associates by night. Reach him at: Jeremy@Zawodny.com.

Comments are closed.