Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-) Softpanorama Search

Perl Wiki as System Administrators Tool

One important aspect of system administration that is sometimes overlooked is keeping users and collegues informed. Most users like to know when there is new functionality available or when resources are down or not available. Not only does it make administrators happier to be kept informed, but it also can make your life easier as well.

There is a growing trend to combine wiki technology with blogging capability to provide better collaboration and communication solutions for system administrators.   JotSpot, SocialText and Wetpaint are first attempts in this direction. In addition, several of the existing content managing systems are beginning to add wiki and blog functions to their product roadmap. Actually you don't need to be fancy and a simple wiki probably provides 80% of needed functionality.   But pure wiki functionality is not enough.

• You need capabilities of content management system (tracking changes, authors, etc) l For example Wikipedia (based on MediaWiki) has most features typical for the content management system. 
• You need capability of blog (combining posts into multiple pages based of tags). Combination of wiki and blog technology solve the problem of topics: many notes belong to multiple topics and wiki alone has no capability to combine posts based on the topic.

Typically they use simplified, very primitive markup language and not HTML. Although this is a peripheral issue a lot of coding efforts are sunk into reinventing the bicycle.  At some point the markup language becomes a problem rather then solution so wiki that accept html are preferable to those which do not (it is possible to convert to wiki formatting language from HTML with some loss of formatting).  That's actually a problem with Wikipedia.

The balance of author control/democracy in wikies is slated toward democracy and thus has some negative side effects like vandalism and "lowest common denominator" problem. Despite those significant problem so far this proved to be a workable solution where abuse does not derail most projects. The most famous Wiki is probably Wikipedia.

Most small modifiable Perl Wiki projects in Freshmeat are abandonware.  In essence Wiki is a poor man content management system and most small content management systems can be used along or instead. See Comparison of content management systems - Wikipedia, the free encyclopedia

Old News ;-)

[Jan 30, 2007] freshmeat.net Project details for Salonify

Salonify is a Perl script which displays images that you have organized in a directory hierarchy. The Web user can choose to see photos as thumbnails or in small, medium, or full-size format; rotate the images; modify the captions; move from folder to folder or image to image easily; and customize the layout. The administrator can also take away any of these abilities from the user if they want. By default, the captioning is totally democratic (or wiki-like)--anyone visiting your site can change the captions. You can also lock this down. Salonify generates nearly w3c-compliant HTML (getting closer all the time) and renders quite well in all tested browsers, including w3m-img, lynx, Mozilla, Opera, Netscape, Internet Explorer, etc.. It uses JavaScript when available but does not depend on it, and makes special allowances for bugs in certain browsers.

[Aug 31, 2006]Linux.com Personal wikis Three small, simple alternatives By: Scott Nesbitt

Wikis aren't just great tools for sharing information and collaborating on projects. They also make excellent personal information managers. With a personal wiki, all of your to-do lists, notes, and appointments are at your fingertips in form that's easy to use and maintain.

The problem with most wikis, such as MediaWiki (the engine that powers Wikipedia) is that they take a lot of effort to set up and maintain. You have to deal with not only the wiki software itself but also the Web server and database that underlie the wiki. All of that is overkill for anyone who wants a wiki for strictly personal use.

But there are several applications available to someone who wants to get a wiki working quickly as a desktop tool. They don't require much, if any, configuration.

DoxWiki

DoxWiki makes it easy for you to get a wiki up and running quickly. When installed on your computer, DoxWiki weighs in at just over 200KB.

The heart of DoxWiki is a a simple Web server that's written in Perl. To get going, all you have to do is start the Web server at the command line; it doesn't seem to like being launched from a desktop shortcut. Then, open the wiki's main page in your browser by typing http://localhost:8080 in the address bar.

Instead of saving content to a database, DoxWiki saves the individual files that make up the wiki on your hard drive. The files are small, so it would take quite a lot of them to put a dent in your drive's capacity.

Creating wiki pages is simple. On the main page (called the Wiki Root), you type a name for the new page in one of the fields, and then click the Go button. From there, you add content.

Wikis use a markup language based on common keyboard symbols that format text, links (both to other wiki pages and Web sites), and elements on a page. If you don't know wiki markup, DoxWiki doesn't leave you hanging. It comes with a lengthy guide to the markup and how to use it.

DoxWiki also has a couple of other useful features: a nifty export filter and a search engine.

You can save individual pages as HTML, which you can later post to the Web, print, or send via email. In fact, I wrote the first draft of this article in DoxWiki, exported it to HTML, and completed the final draft in a text editor.

DoxWiki's search engine is rudimentary, but it gets the job done, which is useful when your wiki grows to encompass a large number of pages.

One aspect of DoxWiki that I don't like is the default look of the pages. They're not ugly, but they're bland. While you can add a custom logo to your wiki pages (mine's a frog), I couldn't figure out how to modify the look and feel of the wiki pages.

Going small and simple

If you need a portable and easy-to-use wiki, then you can't get any simpler than Wiki on a Stick and TiddlyWiki. Both Wiki on a Stick and TiddlyWiki are designed to be used on your desktop or to be carried on a USB thumb drive. They're simply HTML files that use CSS and JavaScript to provide formatting and the ability to add pages to your wiki. Well, you're not exactly adding pages as you would in a traditional wiki. Instead, the new content is just appended to the HTML file, and hidden until you click the link to jump to the content.

According to its developer, Wiki on a Stick "can be used as a personal notepad, calendar, repository for software documentation, and many other things." The beauty of Wiki on a Stick is that it is simple. The interface is uncluttered, almost bland. It consists of a heading, a navigation menu, an area for text, and a set of icons. You can easily create and edit pages by clicking one of the icons. When a new version of Wiki on a Stick comes out, you can quickly import the contents of your current wiki to the new version.

Adding and editing content is a breeze. Wiki on a Stick supports a variant of the standard wiki markup -- for example, you enter a + instead of a * to create a bullet. Whenever you edit content, a list of the supported markup appears at the bottom of the page. If you've never used a wiki before, then it might take a bit of time to adapt. If not, then you shouldn't have any trouble learning the formatting codes.

You can edit a Wiki on a Stick with Firefox, Mozilla, and Internet Explorer. While you can browse a Wiki on a Stick with Opera, you won't be able to edit it. Using Konqueror is out of the question, unfortunately. You can also edit the CSS from within the wiki to change its look and feel. If you plan to put the wiki on the Web as a static page, you can configure it so that the edit icon is hidden.

TiddlyWiki

TiddlyWiki is flashier than Wiki on a Stick. It follows the same principles as that application, but does so with a little more pizazz. For example, when you click a link to jump to some wiki content, an in-your-face JavaScript transition brings that content to the top of the page. You can turn that animation off if it bugs you. TiddlyWiki also has a simple built-in search engine that does the job.

TiddlyWiki divides content into two types: Tiddlers and Journals. Tiddlers are general wiki entries -- ideas, notes, to-do lists, or whatever else you want them to be. Journals, on the other hand, are notes that are specific to a day. While I was experimenting with TiddlyWiki, I used Journals to track specific tasks that I needed to do on a particular day, and used one as a personal diary.

You can configure several options in TiddlyWiki. You can set it up to do automatic saves and to create backups. You can also enable regular expression and case-sensitive searches, as well as generate an RSS feed. The latter is useful if you plan to post your TiddlyWiki on the Web. Unlike Wiki on a Stick, though, you can't change the look and feel of TiddlyWiki from the interface. You either have to edit the TiddlyWiki code, or create some sort of custom theme. The TiddlyWiki Web site leads you through that process.

TiddlyWiki has spawned a number of variants. These include GTD TiddlyWiki (aimed at those who follow the Getting Things Done method of personal productivity) and QwikWeb (which is meant to be deployed on a Web site). So, if TiddlyWiki doesn't quite suit your needs, you might be able to find a variant that does.

Unlike Wiki on a Stick, you can view a TiddlyWiki with just about any desktop Web browser, and on the Nokia 770 Internet Tablet. You can edit the content of a TiddlyWiki on a wider range of browser than that supported by Wiki on a Stick: Firefox, Internet Explorer, Safari, and Camino among them. On top of that, you can extend TiddlyWiki with several plugins. See the TiddlyWiki Web site for more information.

Conclusion

Wikis are great tools for capturing and sharing personal information. For personal use, you don't need to worry about maintaining a Web server or database. You can start using these personal wikis almost immediately, without getting your hands dirty configuring and maintaining the supporting software.

The Fishbowl In Defense of Wiki Markup

They re-invented the bicycle and did it badly. Compare with Why Doesnt Wiki Do Html Most objections are completly bogus...

I found this scathing denunciation of wiki-markup via Mark Pilgrims’ b-links. Seeing as I’ve spent the last few months writing a product that uses Wiki markup as its basis, I thought I might come to the markup’s defense.

Thanks to a worldwide effort that could have built the Great Wall of China at least once over, there is a single system for text markup [HTML + XML] that is regular, full-featured, and mature.

Micro Persuasion eBay to Launch Blogs, Wikis and Search Tags

Auction giant eBay is preparing to integrate blog and wiki publishing tools into its selling platform, according to a report on Auctionbytes. eBay Blogs will enable sellers to more efficiently market their products. eBay Wikis meanwhile collect fact-based articles written and maintained by eBay Community members. Both tools will be launched at the eBay Live conference in Las Vegas June 13 - 15.

Working off the Auctionbytes story, I dug a little deeper and found more details including a tag/search platform. The eBay Blog help pages here and the wiki information pages here. In addition, as you can see from the screenshot below and the links on the help pages, Skype integration is coming soon too.

WikiBlogIntegration - AndrewSW Pages One simple way of integrating wikis and blogs

Blogs and Wikis can be integrated easily if:

• the blog supports post by e-mail and
• the wiki supports subscribe by e-mail to changes of any page.

I appear to have gotten this to work with B2 and MoinMoin. But I had to hack MoinMoin quite a bit to get the mail in a reasonable format whereby I'd actually want it blogged.

I now also have a hack to B2 that automatically inserts links to wiki pages (with wiki names) that exist, but only if not in between angle brackets - I don't want to have links inside of links as nested anchors haven't been allowed for a long time in HTML land.

WikyBlog - A Wiki - Blog Hybrid

wikis-the-insiders-guide

Wiki Wednesdays
SocialText picked up and implemented the idea of Wiki Wednesdays.  On the first Wednesday of each month there is usually a meeting held in a few locations in the USA and Canada, and one or two locations in Europe.  People interested in the wiki technology and approach get together to share their experiences and ideas, or make contacts to get help from the experts. You can find out about the latest and recent events here.

Using Wikis and Blogs to Ease Administration By Ti Leggett

2006-02-27 | Linux Journal

This tutorial on TWiki and WordPress shows how wikis and blogs can be useful for system administration and documentation. System administration can be like sailing a ship. You must keep your engines running smoothly, keep your crew and the harbors notified and up to date and also maintain your Captain's log. You must keep your eye on the horizon for what is coming next. Two technologies have emerged over the past few years that could help keep you on course, wikis and blogs.
 

Maintaining Good Documentation

I find that one of the most difficult aspects of system administration is keeping documentation accurate and up to date. Documenting how you fixed a pesky problem today will help you remember how to fix it months later when it occurs again. If you ever have worked with others, you realize how critical good documentation is. Even if you are the only system administrator, you still will reap the benefits of good documentation, even more so if another sysadmin is ever brought on board.

Some goals of a good documentation system should be:

• Make it easy for you and your coworkers to find relevant information.
• Make it easy for new employees to come up to speed quickly.
• Make it easy to create, edit and retire documentation.
• Keep revisions of changes and who made them.
• Limit who sees or edits the documentation with an authentication system.

Unfortunately, keeping your documentation up to date can be a full-time job in itself. Documenting, though not a very glamorous task, certainly will pay off in the long run.

Why a Wiki?

This is where a wiki comes in. From Wikipedia: "a wiki is a type of Web site that allows users to add and edit content and is especially suited for constructive collaborative authoring."

What this means is a wiki allows you to keep and edit your documentation in a central location. You can access and edit that documentation regardless of the platform you are using. All you need is a Web browser. Some wikis have the ability to keep track of each revision of a changed document, so you can revert to a previous version if some errant changes are made to a document. The only obstacle a new user must overcome is learning the particular markup language of your wiki, and sometimes even this is not completely necessary.

One of a wiki's features is also one of its drawbacks. Wikis are pretty free flowing, and although this allows you to concentrate on getting the documentation written quickly, it can make organization of your wiki rapidly spiral out of control. Thought needs to be put into how the wiki is organized, so that topics do not get stranded or lost. I have found that making the front page a table of contents of all the topics is very handy. However you decide to organize your wiki, make sure it is well understood by everyone else. In fact, a good first document might be the policy describing the organization of the wiki!

TWiki

There are several open-source wikis available, such as MediaWiki and MoinMoin, each with its own philosophy on markup and layout, but here we concentrate on TWiki. Some of TWiki's benefits are:

• A notion of webs that allows the wiki administrator to segregate areas of collaboration into their own areas, each with its own set of authorization rules and topics.
• A modular plugin and skin system that allows you to customize easily.
• A well-established base of users and developers.
• Revision control based on RCS.
• It is Perl-based and mod_perl or FastCGI can be used.
• Authentication is handled outside the wiki by mechanisms such as Apache htpasswd.

The most current stable release at this time is Cairo, or TWiki20040904. It was released, as the name suggests, on September 4, 2004, and it has been proven to be very stable. However, it does lack some of the features of the current beta release, Dakar, that I find to be very useful. The Dakar release we use here is TWikiRelease2005x12x17x7873beta.

Installing TWiki is relatively easy, but still needs work. I hope, as the beta progresses, we will see improvements in ease of installation and upgrading along with clearer documentation.

First, you must create the directory where you want to install TWiki, say /var/www/wiki. Next, untar the TWiki distribution in that directory. Then you must make sure that the user with rights to run CGI scripts (usually apache or www-data), owns all of the files and is able to write to all files:

# install -d -o apache /var/www/wiki
# cd /var/www/wiki
# tar zxf /path/to/TWikiRelease2005x12x17x7873beta.tgz
# cp bin/LocalLib.cfg.txt bin/LocalLib.cfg
# vi bin/LocalLib.cfg lib/LocalSite.cfg
# chown -R apache *
# chmod -R u+w *

Now copy bin/LocalLib.cfg.txt to bin/LocalLib.cfg, and edit it. You need to edit the $twikiLibPath variable to point to the absolute path of your TWiki lib directory, /var/www/wiki/lib in our case. You also must create lib/LocalSite.cfg to reflect your specific site information. Here is a sample of what might go into LocalSite.cfg:

# This is LocalSite.cfg. It contains all the setups for your local
# TWiki site.
$cfg{DefaultUrlHost} = "http://www.example.com";
$cfg{ScriptUrlPath} = "/wiki/bin";
$cfg{PubUrlPath} = "/wiki/pub";
$cfg{DataDir} = "/var/www/wiki/data";
$cfg{PubDir} = "/var/www/wiki/pub";
$cfg{TemplateDir} = "/var/www/wiki/templates";
$TWiki::cfg{LocalesDir} = '/var/www/wiki/locale';

Here is a sample section for your Apache configuration file that allows this wiki to run:

ScriptAlias /wiki/bin/ "/var/www/wiki/bin/"
Alias /wiki "/var/www/localhost/wiki"
<Directory "/var/www/wiki/bin">
    Options +ExecCGI -Indexes
    SetHandler cgi-script
    AllowOverride All
    Allow from all
</Directory>
<Directory "/var/www/wiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
</Directory>
<Directory "/var/www/wiki/data">
    deny from all
</Directory>
<Directory "/var/www/wiki/lib">
    deny from all
</Directory>
<Directory "/var/www/wiki/templates">
    deny from all
</Directory>
 

TWiki comes with a configure script that you run to set up TWiki. This script is used not only on initial install but also when you want to enable plugins later. At this point, you are ready to configure TWiki, so point your browser to your TWiki configure script, http://www.example.com/wiki/bin/configure. You might be particularly interested in the Security section, but we will visit this shortly. Until you have registered your first user, you should leave all settings as they are. If the configure script gives any warnings or errors, you should fix those first and re-run the script. Once you click Next, you are prompted to enter a password. This password is used whenever the configure script is run in the future to help ensure no improper access.

Once you have completed the configuration successfully, it is time to enter the wiki. Point your browser to http://www.example.com/wiki/bin/view, and you are presented with the Main web. In the middle of the page is a link for registration. Register yourself as a user. Be sure to provide a valid e-mail address as the software uses it to validate your account. Once you have verified your user account, you need to add yourself to the TWikiAdminGroup. Return to the Main web and click on the Groups link at the left, and then choose the TWikiAdminGroup. Edit this page, and change the GROUP variable to include your new user name:

   Set GROUP = %MAINWEB%.TiLeggett
   Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup

The three blank spaces at the beginning of each of those lines are critical.

These two lines add your user to the TWikiAdminGroup and allow only members of the TWikiAdminGroup to modify the group. We are now ready to enable authentication for our wiki, so go back to http://www.example.com/wiki/bin/configure. Several options provided under the Security section are useful. You should make sure the options {UseClientSessions} and {Sessions}{UseIPMatching} are enabled. Also set the {LoginManager} option to TWiki::Client::TemplateLogin and {PasswordManager} to TWiki::Users::HtPasswdUser. If your server supports it, you should set {HtPasswd}{Encoding} to sha1. Save your changes and return to the wiki. If you are not logged in automatically, there is a link at the top left of the page that allows you to do so.

Now that you have authentication working, you may want to tighten down your wiki so that unauthorized people do not turn your documentation repository into an illicit data repository. TWiki has a pretty sophisticated authorization system that is tiered from the site-wide preferences all the way down to a specific topic. Before locking down the Main web, a few more tasks need to be done. Once only certain users can change the Main web, registering new users will fail. That is because part of the user registration process involves creating a topic for that user under the Main web. Dakar has a user, TWikiRegistrationAgent, that is used to do this. From the Main web, use the Jump box at the top left to jump to the WebPreferences topic. Edit the topic to include the following four lines and save your changes:

Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBCHANGE = %MAINWEB%.TWikiAdminGroup,
 -->;%MAINWEB%.TWikiRegistrationAgent 

This allows only members of the TWikiAdminGroup to make changes or rename the Main web or update the Main web's preferences. It also allows the TWikiRegistrationAgent user to create new users' home topics when new users register. I have included a patch that you must apply to lib/TWiki/UI/Register.pm as well. The patch follows, but you can also download the patch from the LJ FTP site (see the on-line Resources):

--- lib/TWiki/UI/Register.pm.orig       2006-01-04 01:34:48.968947681 -0600
+++ lib/TWiki/UI/Register.pm    2006-01-04 01:35:48.999652157 -0600
@@ -828,11 +828,12 @@
 
     my $userName = $data->{remoteUser} || $data->{WikiName};
     my $user = $session->{users}->findUser( $userName );
+    my $agent = $session->{users}->findUser( $twikiRegistrationAgent );
     $text = $session->expandVariablesOnTopicCreation( $text, $user );
 
     $meta->put( 'TOPICPARENT', { 'name' => $TWiki::cfg{UsersTopicName}} );
 
-    $session->{store}->saveTopic($user, $data->{webName},
+    $session->{store}->saveTopic($agent, $data->{webName},
                                  $data->{WikiName}, $text, $meta );
     return $log;
 }

Otherwise, new users' home directories will fail to be created and new user registration will fail. Once you have verified that the Main web is locked down, you should do the same for the TWiki and Sandbox webs.

When you are done configuring TWiki, you should secure the files' permissions:

# find /var/www/wiki/ -type d -exec chmod 0755 {} ';'
# find /var/www/wiki/ -type f -exec chmod 0400 {} ';'
# find /var/www/wiki/pub/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/data/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/lib/LocalSite.cfg -exec chmod 0600 {} ';'
# find /var/www/wiki/bin/ -type f -exec chmod 0700 {} ';'
# chown -R apache /var/www/wiki/*

As I mentioned before, TWiki has a plugin system that you can use. Many plugins are available from the TWiki Web site. Be sure the plugins you choose have been updated for Dakar before you use them.
 

NewsForge Putting MediaWiki to use in an organization

Imagine how useful it would be to have an online knowledge base that can easily be updated created by key people within your organization. That's the promise of a wiki -- a Web application that "allows users to easily add, remove, or otherwise edit all content, very quickly and easily," as Wikipedia, perhaps the best-known wiki, puts it. Why not bring the benefits of a wiki to your organization?

If you're sold on the concept, the first thing you need to do is to pick the software that you're going to use for your wiki. If you want hunt around to find out what's out there, a good place to start is Wikipedia's wiki software wiki. If you say, "I'll use whatever Wikipedia is using," that'll be MediaWiki.

MediaWiki installation is easy -- either follow the instructions on MediaWiki's site or read "The open source wiki behind Wikipedia." Install MediaWiki on a server that can be seen by everyone in your organization. You'll then be able to access it from a Web browser by typing in something like http://servername/wiki.

With a brand new wiki there's absolutely no security or control built into it. Anyone that can access the Web page will be able to add pages, comments, and discussions. We're going to stop that. First add a new user account -- you'll need to be able to log on once you've disabled anonymous access. Next, find the LocalSettings.php file in your wiki directory. Add the following lines:

$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['*']['edit'] = false;
$wgShowIPinHeader = false;

With that done, anyone on the network will be able to view the wiki, but only someone with an account will be able to create or edit pages.

You may also want to enhance the wiki pages by adding PHP functionality. To do this, add a function into the includes/Setup.php file:

function ParsePHPTag($Content)
{
 global $wgOut;
 $wgOut->enableClientCache(false);
 ob_start();
 eval($Content);
 $Result = ob_get_contents();
 ob_end_clean();
  return($Result);
}
$wgParser->setHook('php','ParsePHPTag');

Then, if you want to use PHP in any of your wiki pages, don't use the normal <?PHP ... ?> tags; instead use <PHP> ... </PHP>.

Now you can even access data in a MySQL database by adding code like this to a wiki page:

<PHP>

$db = mysql_connect("localhost", "userid", "userpassword");
mysql_select_db("cstellar",$db);

$result = mysql_query("SELECT COUNT(*) stars FROM chyg85",$db);

printf("Records: %s\n", mysql_result($result,0,"stars"));
</PHP>

In this example, all I'm doing is connecting to a database and counting the number of records in a table. Obviously you'd have to use your own database and user details.

MediaWiki is based on PHP, and so as well as being able to use any PHP functionality within a page, you can actually build your own extensions to MediaWiki. If you're interested in doing that, have a look at MediaWiki's documentation on extending wiki markup.

While you're setting parameters, look at your php.ini file. In php.ini, the line session.gc_maxlifetime sets the length of time (in seconds) that a PHP session is allowed to exist, like this:

session.gc_maxlifetime = 1440

This means that if you're editing the wiki then you must click on the "Save page" button at least once every 24 minutes or risk losing your work. You can increase the time to a value that will suit you better -- say to one hour, or 3600 seconds.

At this point you may be saying, "There's nothing here that I can't do with a text editor, an ordinary Web server, and giving group access to the Web files." True -- so let's see where the wiki comes into its own. Try editing the Main page, save the changes, and then click on the History tab. You'll see that MediaWiki tracks who made all changes and when. You can compare the differences between different versions. In one fell swoop you've got yourself a document management system as well as a potential in-house knowledge base.

"Aha!" I hear you say, "if this is just operating in a browser then how can I do spell check or word counts? What about formating?" If you use Firefox as your browser, you can add Firefox extensions to implement those functions. If you're using Firefox 1.5.x, install Spellbound dev and restart Firefox. When you then try editing one of your wiki pages, you'll find that misspelled words are underlined in red. Right-clicking in any editing areas (text boxes, for example) will allow you to display the spell check front end. Once there then it's just like spell checking in any other application.

It's just as easy to get a word count going, this time use roachfiend.com's Word Count. Again, don't forget to restart Firefox after installing the extension. However, the word count doesn't work within the text editing areas. to get around that problem, click MediaWiki's "Show Preview" button tp see your work displayed as a normal Web page. Now you can then select any area of the text, right-click on it, and you'll see that "Word Count" function is available. Click on it to see the number of words in a message box.

Finally you can install a WYSYWIG HTML editor called Xinha Here! Both the spell check and word count extensions also work in the Xinha window.

With MediaWiki set up, you're ready to create your knowledge base; I can't help you there, it's all up to you. MediaWiki and the Firefox extensions have enhanced the way that I do my day-to-day work, and I'm sure that they can revolutionize the flow of information and knowledge around your organization.

[June 21, 2006] Assorted findings:

• QuikWiki A Perl CGI Wiki. Author: thx1132 Added: 28-Jul-2003 Updated:29-May-2004 License: Artistic LicenseVersion:1.5
• pvWikiSystem A Perl implementation of the Wiki system. Author: Philo Vivero GNU General Public License (GPL) Added:17-Aug-2000Updated: 30-Jan-2001
• CmicWiki A Perl enhanced wiki. Added:02-Jun-2004Updated:19-Jul-2004 License: GNU General Public License (GPL)Version:10p5

• Zim A desktop wiki and outliner. Author: Jaap Karssenberg Added:21-Sep-2005Updated:17-Apr-2006Rating:8.34/10.00Vitality:0.06%Popularity:1.13%License: Perl LicenseVersion:0.15

•  OpenGuides A collaborative city guide package. Author: The OpenGuides Project Added:12-Oct-2003 Updated: 23-Apr-2006 Rating:(not rated) Vitality:0.34%Popularity:0.87%License: Perl LicenseVersion:0.54

• WebKNotes Web-based knowledge notes database written in Perl.  Author: Don Mahurin  Added: 25-Feb-1999 Updated:18-Sep-2002 Vitality:0.02%Popularity:0.61%License: Artistic LicenseVersion:1.0.1
• ewok A full-featured Web content management system. Author: Gavin Carr Added:03-Sep-2002 Updated:19-Nov-2003Rating:8.36/10.00Vitality:0.00%Popularity:1.14%License: GNU General Public License (GPL)Version:0.5.0
• Salonify A customizable and easy Web-based image gallery system.  Author: Adam Kessel

[Feb 27, 2006] Using Wikis and Blogs to Ease Administration Linux Journal Using Wikis and Blogs to Ease Administration By Ti Leggett on Mon, 2006-02-27 02:00. SysAdmin

This tutorial on TWiki and WordPress shows how wikis and blogs can be useful for system administration and documentation. System administration can be like sailing a ship. You must keep your engines running smoothly, keep your crew and the harbors notified and up to date and also maintain your Captain's log. You must keep your eye on the horizon for what is coming next. Two technologies have emerged over the past few years that could help keep you on course, wikis and blogs.

Maintaining Good Documentation

I find that one of the most difficult aspects of system administration is keeping documentation accurate and up to date. Documenting how you fixed a pesky problem today will help you remember how to fix it months later when it occurs again. If you ever have worked with others, you realize how critical good documentation is. Even if you are the only system administrator, you still will reap the benefits of good documentation, even more so if another sysadmin is ever brought on board.

Some goals of a good documentation system should be:

• Make it easy for you and your coworkers to find relevant information.

• Make it easy for new employees to come up to speed quickly.

• Make it easy to create, edit and retire documentation.

• Keep revisions of changes and who made them.

• Limit who sees or edits the documentation with an authentication system.

Unfortunately, keeping your documentation up to date can be a full-time job in itself. Documenting, though not a very glamorous task, certainly will pay off in the long run.

Why a Wiki?

This is where a wiki comes in. From Wikipedia: "a wiki is a type of Web site that allows users to add and edit content and is especially suited for constructive collaborative authoring."

What this means is a wiki allows you to keep and edit your documentation in a central location. You can access and edit that documentation regardless of the platform you are using. All you need is a Web browser. Some wikis have the ability to keep track of each revision of a changed document, so you can revert to a previous version if some errant changes are made to a document. The only obstacle a new user must overcome is learning the particular markup language of your wiki, and sometimes even this is not completely necessary.

One of a wiki's features is also one of its drawbacks. Wikis are pretty free flowing, and although this allows you to concentrate on getting the documentation written quickly, it can make organization of your wiki rapidly spiral out of control. Thought needs to be put into how the wiki is organized, so that topics do not get stranded or lost. I have found that making the front page a table of contents of all the topics is very handy. However you decide to organize your wiki, make sure it is well understood by everyone else. In fact, a good first document might be the policy describing the organization of the wiki!

TWiki

There are several open-source wikis available, such as MediaWiki [see Reuven M. Lerner's article on page 62 for more information on MediaWiki] and MoinMoin, each with its own philosophy on markup and layout, but here we concentrate on TWiki. Some of TWiki's benefits are:

• A notion of webs that allows the wiki administrator to segregate areas of collaboration into their own areas, each with its own set of authorization rules and topics.

• A modular plugin and skin system that allows you to customize easily.

• A well-established base of users and developers.

• Revision control based on RCS.

• It is Perl-based and mod_perl or FastCGI can be used.

• Authentication is handled outside the wiki by mechanisms such as Apache htpasswd.

The most current stable release at this time is Cairo, or TWiki20040904. It was released, as the name suggests, on September 4, 2004, and it has been proven to be very stable. However, it does lack some of the features of the current beta release, Dakar, that I find to be very useful. The Dakar release we use here is TWikiRelease2005x12x17x7873beta.

Installing TWiki is relatively easy, but still needs work. I hope, as the beta progresses, we will see improvements in ease of installation and upgrading along with clearer documentation.

First, you must create the directory where you want to install TWiki, say /var/www/wiki. Next, untar the TWiki distribution in that directory. Then you must make sure that the user with rights to run CGI scripts (usually apache or www-data), owns all of the files and is able to write to all files:

# install -d -o apache /var/www/wiki
# cd /var/www/wiki
# tar zxf /path/to/TWikiRelease2005x12x17x7873beta.tgz
# cp bin/LocalLib.cfg.txt bin/LocalLib.cfg
# vi bin/LocalLib.cfg lib/LocalSite.cfg
# chown -R apache *
# chmod -R u+w *

Now copy bin/LocalLib.cfg.txt to bin/LocalLib.cfg, and edit it. You need to edit the $twikiLibPath variable to point to the absolute path of your TWiki lib directory, /var/www/wiki/lib in our case. You also must create lib/LocalSite.cfg to reflect your specific site information. Here is a sample of what might go into LocalSite.cfg:

# This is LocalSite.cfg. It contains all the setups for your local
# TWiki site.
$cfg{DefaultUrlHost} = "http://www.example.com";
$cfg{ScriptUrlPath} = "/wiki/bin";
$cfg{PubUrlPath} = "/wiki/pub";
$cfg{DataDir} = "/var/www/wiki/data";
$cfg{PubDir} = "/var/www/wiki/pub";
$cfg{TemplateDir} = "/var/www/wiki/templates";
$TWiki::cfg{LocalesDir} = '/var/www/wiki/locale';

Here is a sample section for your Apache configuration file that allows this wiki to run:

ScriptAlias /wiki/bin/ "/var/www/wiki/bin/"
Alias /wiki "/var/www/localhost/wiki"
<Directory "/var/www/wiki/bin">
    Options +ExecCGI -Indexes
    SetHandler cgi-script
    AllowOverride All
    Allow from all
</Directory>
<Directory "/var/www/wiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
</Directory>
<Directory "/var/www/wiki/data">
    deny from all
</Directory>
<Directory "/var/www/wiki/lib">
    deny from all
</Directory>
<Directory "/var/www/wiki/templates">
    deny from all
</Directory>
 

TWiki comes with a configure script that you run to set up TWiki. This script is used not only on initial install but also when you want to enable plugins later. At this point, you are ready to configure TWiki, so point your browser to your TWiki configure script, http://www.example.com/wiki/bin/configure. You might be particularly interested in the Security section, but we will visit this shortly. Until you have registered your first user, you should leave all settings as they are. If the configure script gives any warnings or errors, you should fix those first and re-run the script. Once you click Next, you are prompted to enter a password. This password is used whenever the configure script is run in the future to help ensure no improper access.

Once you have completed the configuration successfully, it is time to enter the wiki. Point your browser to http://www.example.com/wiki/bin/view, and you are presented with the Main web. In the middle of the page is a link for registration. Register yourself as a user. Be sure to provide a valid e-mail address as the software uses it to validate your account. Once you have verified your user account, you need to add yourself to the TWikiAdminGroup. Return to the Main web and click on the Groups link at the left, and then choose the TWikiAdminGroup. Edit this page, and change the GROUP variable to include your new user name:

   Set GROUP = %MAINWEB%.TiLeggett
   Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup

The three blank spaces at the beginning of each of those lines are critical.

These two lines add your user to the TWikiAdminGroup and allow only members of the TWikiAdminGroup to modify the group. We are now ready to enable authentication for our wiki, so go back to http://www.example.com/wiki/bin/configure. Several options provided under the Security section are useful. You should make sure the options {UseClientSessions} and {Sessions}{UseIPMatching} are enabled. Also set the {LoginManager} option to TWiki::Client::TemplateLogin and {PasswordManager} to TWiki::Users::HtPasswdUser. If your server supports it, you should set {HtPasswd}{Encoding} to sha1. Save your changes and return to the wiki. If you are not logged in automatically, there is a link at the top left of the page that allows you to do so.

Now that you have authentication working, you may want to tighten down your wiki so that unauthorized people do not turn your documentation repository into an illicit data repository. TWiki has a pretty sophisticated authorization system that is tiered from the site-wide preferences all the way down to a specific topic. Before locking down the Main web, a few more tasks need to be done. Once only certain users can change the Main web, registering new users will fail. That is because part of the user registration process involves creating a topic for that user under the Main web. Dakar has a user, TWikiRegistrationAgent, that is used to do this. From the Main web, use the Jump box at the top left to jump to the WebPreferences topic. Edit the topic to include the following four lines and save your changes:

Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBCHANGE = %MAINWEB%.TWikiAdminGroup,
 -->;%MAINWEB%.TWikiRegistrationAgent 

This allows only members of the TWikiAdminGroup to make changes or rename the Main web or update the Main web's preferences. It also allows the TWikiRegistrationAgent user to create new users' home topics when new users register. I have included a patch that you must apply to lib/TWiki/UI/Register.pm as well. The patch follows, but you can also download the patch from the LJ FTP site (see the on-line Resources):

--- lib/TWiki/UI/Register.pm.orig       2006-01-04 01:34:48.968947681 -0600
+++ lib/TWiki/UI/Register.pm    2006-01-04 01:35:48.999652157 -0600
@@ -828,11 +828,12 @@
 
     my $userName = $data->{remoteUser} || $data->{WikiName};
     my $user = $session->{users}->findUser( $userName );
+    my $agent = $session->{users}->findUser( $twikiRegistrationAgent );
     $text = $session->expandVariablesOnTopicCreation( $text, $user );
 
     $meta->put( 'TOPICPARENT', { 'name' => $TWiki::cfg{UsersTopicName}} );
 
-    $session->{store}->saveTopic($user, $data->{webName},
+    $session->{store}->saveTopic($agent, $data->{webName},
                                  $data->{WikiName}, $text, $meta );
     return $log;
 }

Otherwise, new users' home directories will fail to be created and new user registration will fail. Once you have verified that the Main web is locked down, you should do the same for the TWiki and Sandbox webs.

When you are done configuring TWiki, you should secure the files' permissions:

# find /var/www/wiki/ -type d -exec chmod 0755 {} ';'
# find /var/www/wiki/ -type f -exec chmod 0400 {} ';'
# find /var/www/wiki/pub/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/data/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/lib/LocalSite.cfg -exec chmod 0600 {} ';'
# find /var/www/wiki/bin/ -type f -exec chmod 0700 {} ';'
# chown -R apache /var/www/wiki/*
As I mentioned before, TWiki has a plugin system that you can use. Many 
							plugins are available from the TWiki Web site. Be 
							sure the plugins you choose have been updated for 
							Dakar before you use them.

Keeping Your Users in the Know

One important aspect of system administration that is sometimes overlooked is keeping users informed. Most users like to know when there is new functionality available or when resources are down or not available. Not only does it make users happier to be kept informed, but it also can make your life easier as well. The last thing you want to do when the central file server is down is reply to users' questions about why they cannot get to their files. If you have trained your users to look at a central location for status of the infrastructure first, all you have to do after notification of a problem is post to this central place that there is a problem. Mailing lists also are good for this, but what if the mail server is down? Some people, for instance your boss or VP of the company, might like to know what the status is of things as they happen. These updates might not be suitable to send out to everyone daily via e-mail. You could create yet another mailing list for these notifications, but you also might consider a blog.

If you are not familiar with a blog, let us refer back to Wikipedia: "a blog is a Web site in which journal entries are posted on a regular basis and displayed in reverse chronological order."

The notion of a blog has been around for centuries in the form of diaries, but blogs recently have had an explosion on the Internet. Many times a blog is started as someone's personal journal or as a way to report news, but blogs can be extremely useful for the sysadmin.

Blogs can help a sysadmin give users an up-to-the-minute status of what they are doing and what the state of the infrastructure is. If you faithfully update your blog, you easily can look back on what you have accomplished so you can make your case for that raise you have been hoping for. It also will help you keep track of what your coworkers are doing. And, with many blog software packages providing RSS feeds, users can subscribe to the blog and be notified when there are new posts.

... ... ...

Wrapping Up

I hope that after this whirlwind tour of wikis and blogs you have come to see how they can be beneficial to help your shop run a smoother ship and provide your users with all the information they might want. Just as there are many different sails to keep your ship sailing, there are many different wiki and blog software packages out there. The right package for you is the one that keeps your users happy and you productive.

Resources for this article: www.linuxjournal.com/article/8832.

Ti Leggett (ti@daleggetts.com) is a full-time system administrator. When he's not working, he might be found playing his Gibson B-25 or doing some home improvements or wood working.

freshmeat.net Project details for ReciPants

ReciPants is a Web-based recipe manager that supports Postgres, MySQL, and Oracle databases. It features searching, categories, exporting, scaling, emailing recipes, password reminders, secure user cookies, internationalization, and fully customizable templated output.

ONLamp.com Which Open Source Wiki Works For You

Kwiki

The Kwiki motto is a "A Quickie Wiki that's not Tricky." Installing it is pretty straightforward for a site you admin: just install the Perl package (from CPAN or elsewhere), and then type kwiki-install in a CGI-served directory to create an instance. Installing Kwiki on a server you are not an admin of is more complicated but doable.

I found the Kwiki markup not powerful. Some things are impossible with it, such as hyperlinking an arbitrary piece of text to an email address (mail fooish). I also could not find how to link a Wiki page with a text link different from the Wiki page name (like this link to LinkedWikiWikiPage). There is also no support for attachments, HTML markup as an alternative to the Wiki markup, etc. It is disappointing.

Kwiki can use either RCS or Subversion for version control. (Those who wish to use Subversion should check out the corrected Kwiki version as the CPAN Kwiki does not work with the up-to-date Subversion.) Kwiki is easily customizable and has several Kwiki enhancements available. Generally, however, they are less powerful than TWiki's.

All in all, Kwiki is easy to install and customize, but its formatting rules are lacking.

... ... ...

UseModWiki

UseModWiki is a Wiki engine written in Perl. Anecdotally, Wikipedia used this first before re-implementing their current engine. Other sites also use UseModWiki.

UseModWiki is very simple to set up and upgrade. It has a rich syntax, and allows for arbitrary characters in page names. It also supports using some HTML tags instead of the WikiWiki markup. It has other nice features, including search, a list of recent changes, and page history.

For simple Wikis, UseModWiki is a very good choice. I recommend choosing between it and PmWiki based on the feature list of both Wikis.

Recommended Links

---

In case of broken links please try to use Google search. If you find the page please notify us about new location

• List of wiki software - Wikipedia, the free encyclopedia
  • CorneliOS, a webOS, includes a wiki software that's also the engine for Galaxiki.
  • Noösphere, the engine for PlanetMath.
  • PodWiki is a wiki which supports multiple markup languages, primarily Perl POD.
  • Socialtext is an enterprise wiki and weblog partially derived from open source Kwiki. It is available as a hosted service, a hardware appliance and now as open source from Sourceforge.
  • TWiki is a structured wiki, typically used to run a project development space, a document management system, a knowledge base, or any other groupware tool. Also available as a VMware appliance.
  • UseModWiki (Clifford Adams, 2000) is a clone of AtisWiki.
    • Oddmuse is a fork of UseModWiki.
    • PurpleWiki is major rewrite of UseModWiki that implements Purple Numbers and Transclusion.
  • WikiWikiWeb (Ward Cunningham, 1994)
• Wiki Engines
  • AtisWiki -- Perl-based, configurable backends (files, CVS) and Look-and-Feel.
  • CgiWiki -- a Perl toolkit for building wikis.
  • CmicWiki -- UseMod wiki based with patches http://cmicwiki.freesurf.fr
  • ChiqChaq -- Easy to localize and appropriate for non-technical users.
  • ClusterWiki -- multiple wikis run from one library, published in TheWikiWay.
  • CvWiki -- WikiBase-based, more functional than AtisWiki, but lacking a GPL.
  • DolphinWikiWeb -- ObjectArts' GPL Perl-based Wiki (supports templates, is used for many sites)
  • FaqOmatic (GPL)
  • IkiWiki -- wiki compiler, VersionControlled, plugin architecture
  • JosWiki -- Perl-based (replaced by the TwikiClone engine)
  • KeheiWiki -- Templates, messaging, virtual subdirs, editor delegation, no DB required, extendable without hacking base source
  • KwikiKwiki -- filesystem based, very easy to install, well structured wiki.
  • LeufNetWiki
  • Lexi -- no more need for WikiWords or special markup for them http://www.wyae.de/software/lexi/
  • MiniWiki -- http://www.nyetwork.org/wiki/MiniWiki
  • noosphere -- http://planetx.cc.vt.edu/AsteroidMeta//No%c3%b6sphere not really a wiki - but very close in the collaborative process and interlinked nature
  • n4u http://n4u.ath.cx wiki-like thing inspired by BashWiki. It generates static html files so that the visitor directly read *.html files instead of running CGI.
  • OddMuseWiki -- based on UseModWiki, also Perl-based, easy to install, easy to use, different well-balanced features, well documented
  • PeriPeri -- A SemanticWiki with a semi-lattice NameSpace and more. Produces valid HTML 4.01 Strict/CSS
  • PhearWiki -- http://jirc.hick.org/wiki
  • PodWiki -- http://www.daemon.de/podwiki/ (demo: http://www.podwiki.org/), easy to install ready-to-run wiki engine which uses perl POD (http://perlpod.com/) as its markup and also supports natural writing markup. RCS version control, filesystem (rcs+DBM) based and mod_perl compliant and GPLed Opensource.
  • ProWikiSoftware -- http://prowiki.org, Perl, GPL, tons of features, pages and subwikis can be configured using inheritance
  • PurpleWiki -- http://purplewiki.blueoxen.net/cgi-bin/wiki.pl?PurpleWiki derived from Usemod introduces Fine-grained addressability via purple numbers, Transclusions, and blog integration
  • QuickiWiki -- Perl-based, WardCunningham's new source with stand-alone optional servlet, published in TheWikiWay
  • QwikWiki (Qwiki) -- Perl-based, rapid searching, OpenSource
  • ScrumWiki? -- UseMod based wiki, tailored for the Scrum project management methodology. (http://scrumwiki.org/)
  • SealedWiki -- A wiki site that permits users to write-protect portions of text.
  • SlashWiki -- wiki plugin for the Perl-based Slash server.
  • SocialText -- commercial enterprise wiki and weblog http://www.socialtext.com
  • SowjetPlus -- Inspired by wiki as well as Indesign and Quarkxpress, GPL
  • SpinnerWiki -- Descendent of DolphinWikiWeb with some additional features and a few features removed. GPL.
  • StrikiWiki -- A wiki with templates, based on original wiki code base
  • TinyWiki -- Hackable, small, good feature set. From 36 lines, CVS backend, Free.
  • TthWiki -- based on UseModWiki, additional support for LaTeX enhanced wiki pages
  • TwiciWiki -- A small, simple wiki written mostly for the hell of it
  • TwikiClone (TWiki) -- Perl-based, mature and full featured system, including revision control via RCS, targeting the corporate intranet world -- now with plugins, I18N, ... (V, (RCS), N, I, H, F, R, P(?), A, DB=none)
  • UseModWiki -- Perl-based, easy to install, easy to use, well-balanced features
  • WalaWiki -- Includes an "add text" box at the bottom of every page. Very clean code and very easy to install (less than 2 min).
  • WalWiki? -- Japanese popular wiki, based on YukiWiki. http://digit.que.ne.jp/work/
  • WebWeb -- Might be a victim of leaping featureitis
  • WebWebTwo -- WebWebX, a Derivative of WebWeb
  • YetAnotherWikiName -- YAWN, the self-sitemapping wiki
  • YukiWiki -- Japanese standard wiki. http://www.hyuki.com/yukiwiki/
  • Wifty -- written in Jifty, which in turn is written in Perl. http://jifty.org/ . Artistic License or GPL.
   
• QuikWiki QuikWiki is a Perl CGI Wiki that supports normal Wiki functions like browsing, creating, and editing Web pages. Additionally, QuikWiki supports inline image display, text markup, RCS revisions, and page templates.
• pvWikiSystem The Wiki system is a quick way of creating websites. It tries to make the concept of the document root and hyperlinks obsolete. In practice, often a wiki page has a lot of HTML embedded, but it was originally envisioned to make plaintext into prettified HTML with automatic hyperlinking.
• CmicWiki Based on UseMod wiki, CmicWiki has a lot of features and several fixed skins. Features include signatures, date, clickable images, numbered titles, page write protection, upload module, and a full French interface and documentation. Planned are useful JavaScripit editing features.
• WebKNotes WebKNotes is a Web-based knowledge/notes database written in Perl using a plain dir/file (text, HTML, Wiki) hierarchy as a database for notes and subtopics. Features include uploading, searching, user authentication, editing of existing notes, various views, CSS themes, and mod_perl support.
• ewok   A full-featured Web content management system.
• OpenGuides OpenGuides is a wiki-like package for maintaining a collaborative city guide. It is written in Perl and runs as a CGI program, and uses either the MySQL, PostgreSQL, or SQLite database. It offers features over a "normal" wiki such as metadata management and a "find nearby things" function. The look and feel is highly customizable thanks to use of the Template Toolkit.

Kwiki

The Kwiki motto is a "A Quickie Wiki that's not Tricky." Installing it is pretty straightforward for a site you admin: just install the Perl package (from CPAN or elsewhere), and then type kwiki-install in a CGI-served directory to create an instance. Installing Kwiki on a server you are not an admin of is more complicated but doable.

I found the Kwiki markup not powerful. Some things are impossible with it, such as hyperlinking an arbitrary piece of text to an email address (mail fooish). I also could not find how to link a Wiki page with a text link different from the Wiki page name (like this link to LinkedWikiWikiPage). There is also no support for attachments, HTML markup as an alternative to the Wiki markup, etc. It is disappointing.

Kwiki can use either RCS or Subversion for version control. (Those who wish to use Subversion should check out the corrected Kwiki version as the CPAN Kwiki does not work with the up-to-date Subversion.) Kwiki is easily customizable and has several Kwiki enhancements available. Generally, however, they are less powerful than TWiki's.

All in all, Kwiki is easy to install and customize, but its formatting rules are lacking.

... ... ...

UseModWiki

UseModWiki is a Wiki engine written in Perl. Anecdotally, Wikipedia used this first before re-implementing their current engine. Other sites also use UseModWiki.

UseModWiki is very simple to set up and upgrade. It has a rich syntax, and allows for arbitrary characters in page names. It also supports using some HTML tags instead of the WikiWiki markup. It has other nice features, including search, a list of recent changes, and page history.

For simple Wikis, UseModWiki is a very good choice. I recommend choosing between it and PmWiki based on the feature list of both Wikis.

Twiki

TWiki - Enterprise Collaboration Platform TWiki is a cgi-bin script written in Perl. It reads a text file, hyperlinks it and converts it to HTML on the fly. TWiki is GPLed software. The Perl CGI source code, templates and documentation is available for free.

Etc

About: deplate is a tool for converting documents written in an unobtrusive, wiki-like markup to LaTeX, DocBook, HTML, or "HTML slides". It supports embedded LaTeX code, footnotes, citations, bibliographies, automatic generation of an index, etc. In contrast to many wiki engines, it is made for "offline" use as a document preparation tool. In this respect it is similar to tools like aft or txt2tags. It aims to be modular and easily extensible. It is the accompanying converter for the Vim viki plugin.

Changes: Two bugs that prevented it from running on an OS with case-sensitive file names or with the Win32 exe have been fixed. There are minor amendments.

Jon Howell is a graduate student working with David Kotz at Dartmouth College. His research is on single-system-image operating environments that span adminstrative domains. He also enjoys robotics, web glue, and kernel tweaking.

What is the best way to maintain a Frequently Asked Questions list? Traditional FAQs are maintained by hand and often become outdated as the maintainer loses interest in the task. Mailing list archives can be helpful, but are often too disorganized. When I found myself answering the same FAQs about Linux for PowerPC and MkLinux last year, I faced this very problem. I am far too lazy to commit to maintaining a FAQ, but the mailing list archives were not significantly reducing the load of redundant questions.

Solution Design

The FAQ-O-Matic is a Web-editable FAQ designed to offer a middle ground. Because the general public can edit it, it is less likely to become neglected and stale like a manually maintained FAQ. Because changes are submitted where the FAQ is read, one can be rather lazy and still contribute to the FAQ. No one person has the responsibility of maintaining the entire document.

Because a FAQ-O-Matic is topically and hierarchically organized, browsing solutions is easier than it is in mailing list archives. Queries on mailing list archives can return matches for old, outdated information and miss newer answers. The topical organization of a FAQ-O-Matic helps avoid this problem as well.

A search function makes FAQ-O-Matic as accessible as a mailing list archive. Another function lists recently changed items, so users can check back for changes if they did not find a satisfying answer the first time they looked. There is a command to show entire categories in one HTML file, to facilitate printing or export of the FAQ.

How It Works in Practice

I launched the first FAQ-O-Matic by seeding it with about 60 or 70 answers gleaned from recent list postings. Although this opposed my laziness philosophy, I knew that I would not be responsible for keeping the answers up to date. Then I began advertising it by answering questions with URLs to the FAQ-O-Matic.

One problem with the initial implementation was that answers were identified by their location in the topic hierarchy. So if you sent out a URL to a FAQ-O-Matic answer and the database was subsequently reorganized, that URL would go sour.

I initially thought allowing people to submit questions without answers would help define the structure of the FAQ by reserving spaces for answers when they became available. Instead, people who were too lazy to search would post poorly considered questions in inappropriate categories.

The submission page asked users to leave an email address with their comment, but people often forgot or inserted text between previous text and its attribution. Furthermore, although the server uses RCS to protect against wholesale vandalism, there was no way to trace subtle, intentional corruption of the database.

The FAQ-O-Matic allowed the entry of HTML tags, so users could supply links and formatting information for their answers. However, other than links, HTML was rarely used to good effect. Instead, it often made for inconsistent appearance as people appended to existing answers and as HTML tags fought with the formatting generated by the CGI script. Furthermore, code segments pasted into the FAQ-O-Matic would mysteriously lose < and & symbols.

Finally, I found that I had to put in a certain amount of effort moving answers around to keep them organized as new answers showed up. This was compounded by the difficulty of performing this sort of administration on the first implementation of FAQ-O-Matic.

Version 2

Over the summer, I rewrote the FAQ-O-Matic to address these problems. First, each answer is now assigned a permanent ID number. This solves the sour URL problem and also provides a facility for "see also" links inside the FAQ.

I posted a policy disallowing questions without answers, which trivially solved the second problem.

The new version has an authentication scheme that verifies email addresses by sending a secret validation code to the given address. Thus each submission is attributed to a real email address, and intentional corruption, once noticed, can be traced and rolled back.

FAQ-O-Matic 2 no longer allows HTML tags; they are displayed as entities (&lt;). This prevents code from becoming corrupted and enforces a uniform (if bland) appearance. Links are supported heuristically by detecting things that look like links (http://...) and generating HTML links on the fly. Internal links are supported with a special URL that begins "faqomatic:"

Version 2 also has support for reorganizing answers and categories from the Web interface. This facility might allow a Web user to moderate a section of the FAQ and care for its organization. Moderators can request that they receive mail whenever any answer in their area is changed, minimizing the effort associated with the moderation task.

The 1998 LinuxPPC CD was announced in January, prompting an estimated 4,500 people to visit the FAQ-O-Matic on <www.dartmouth.edu> in one day. Because every request required service by a Perl CGI, the memory pressure overloaded the server, and the FAQ-O-Matic had to be throttled. In response to that event, version 2.6 adds a server-side HTML cache, so that people who are only reading the FAQ receive HTML directly from the Web server, without the cost of invoking the CGI.

Other Uses

Because FAQ-O-Matic has an authentication scheme, it made sense to give it flexible authorization as well. The FAQ can be configured to be very open, not even requiring mail-back email secrets, to encourage the shy, lazy, or anonymous contributor at the expense of accuracy of attributions.

Alternatively, it can be set to allow only assigned moderators to modify the FAQ. In this arrangement, it is suitable for use as a help desk database: only help desk operators can modify the database, but it is available for all to read.

Numbers

The Linux on PowerPC FAQ-O-Matic has been available for 15 months. In that time, about 75,000 different people (IP addresses) have seen it, and it has received 1,500 submissions. On average, visitors access it about ten times. A few dozen people claim to be running their own FAQ-O-Matics, some for internal projects, others for Internet-accessible sites.

Conclusion

The FAQ-O-Matic has turned out to be a successful system for documenting the Linux on PowerPC projects. It is more organized than a mailing list archive, but avoids going stale as traditional FAQs often do. It allows a division of labor in maintaining both answers and the overall organization of the FAQ. And it has access control features that make it suitable for other applications. To try it out, visit the FAQ-O-Matic at <http://www.dartmouth.edu/cgi-bin/cgiwrap/jonh/faq.pl>.