来写 ikiwiki 的试用报告

大家都知道，无聊的人特点之一是见到好玩的东西就找来玩一玩，[ikiwiki](http://ikiwiki.kitenet.net) 就是新近发现的有趣东西，把我的兴趣：[Subversion](http://subversion.tigris.org), [Markdown](http://daringfireball.net/projects/markdown), wiki 的概念整合到了一起，算是 wiki 程序里边思路比较另类的，本来看到要装一堆 Perl Module，不愿意去折腾，但 [hlb](http://hlb.yichi.org/blog) 说等我的试用报告 (笑)，就试着装了装看，发现真的很好玩，值得推荐，所以把装的时候遇到的问题流水帐地记下来，或许对你有用。

说了这么多，那 ikiwiki 究竟是什么呢？它其实是一套 Perl 程序，虽然是用作 wiki，但和一般的 CGI/mod_perl 的 wiki 程序不一样的是，它把所有的 wiki 数据文件用 Subversion 来管理，这样文件的历史记录、备份和并行控制就可以直接把 Subversion 的功能搬来用，这是 ikiwiki 最大的特点。

此外，ikiwiki 有趣的地方还在于它使用了 Markdown 的语法来作标记，相比常用的 [wikitext](http://en.wikipedia.org/wiki/Wikitext)，我觉得 Markdown 实在是人性化得多的标记方式。在 Markdown 的基础上，ikiwiki 做的两个额外的处理就是 wiki 的链接 (CamelCase 或者手动指定) 和[子页面](http://ikiwiki.kitenet.net/subpage.html)的创建。

ikiwiki 还有些好玩的功能，比如当作 [blog](http://ikiwiki.kitenet.net/blog.html) 来用、支持[反向链接](http://ikiwiki.kitenet.net/backlinks.html) 等等，你可以在它的 [features](http://ikiwiki.kitenet.net/features.html) 页面中看到，不过我这里是还没有尝试过啦。

哦，顺便提一句，ikiwiki 的作者 [Joey Hess](http://kitenet.net/~joey/) 是一位 [Debian](http://www.debian.org) Hacker，也是 [alien](http://kitenet.net/~joey/code/alien.html), [debconf](http://kitenet.net/~joey/code/debconf.html) 的作者。

下面开始讲实际的东西。

[安装](http://ikiwiki.kitenet.net/install.html)
—-

我测试的环境是 Arch Linux 2.6.16, Perl 5.8.8, lighttpd 1.4.11, subversion 1.3.1。

首先，ikiwiki 需要以下这些 Perl Module：

1. CGI::Session
2. CGI::FormBuilder
3. HTML::Template
4. Mail::Sendmail
5. Time::Duration
6. Date::Parse
7. HTML::Scrubber

我的经验是，还需要 HTML::Parser，此外，Markdown 可以使用 Text::Markdown 这个 Module。

用 cpan 装完以后，就可以[下载](http://ikiwiki.kitenet.net/download.html)一份 tarball，解压。此时，因为我们使用的是 Text::Markdown 提供的 markdown，所以 Ikiwiki/Render.pm 需要作一点小的修改，找到 Markdown::Markdown 那一行，改为:

use Text::Markdown ‘markdown’;
$content = markdown($content);

然后执行

perl Makefile.PL
make
make install

就完成的安装。现在可以试试 ikiwiki 命令有没有反应了。

配置
—-

接下来是[配置](http://ikiwiki.kitenet.net/setup.html)过程，视你希望实现什么功能而有不同的繁琐程度。

第一步是 (先装好 Subversion) 创建给 wiki 使用的版本仓库:

svnadmin create /svn/wikirepo
svn mkdir file:///svn/wikirepo/trunk -m create

然后从这个仓库中 checkout 一份当前的版本作为 working copy，放在自己的 home directory 下边:

svn co file:///svn/wikirepo/trunk ~/wikiwc

这样你就可以用默认的模板和配置构建你的第一个 ikiwiki 了:

ikiwiki –verbose ~/wikiwc/ ~/public_html/wiki/ \
–url=http://host/~you/wiki/

`~/public_html/wiki/` 是你的 Web server 分配给你的 HTML 文档目录。完成上边这一步之后，你就可以在这个目录中找到生成的 `*.html` 文件 (别忘了 ikiwiki 是一个“wiki compiler”)，如果配置好了 web server 的 user directory 功能，就可以在 http://localhost/~username/wiki 看到你的 wiki 了。

这里简单说说 lighttpd 的这个配置，默认的 lighttpd 配置文件在 /etc/lighttpd/lighttpd.conf，首先，在 `server.modules` 变量中打开 `”mod_userdir”` 模块，然后设置 `userdir.path`，以上面的情况为例，就应该是:

userdir.path = “public_html”

当然，输出的目录也不一定要是你的 home directory，只要你的 web server 和你都能访问到的地方都可以啦。

接下来就可以做真正有趣的定制工作了，默认用来创建 wiki 的文件在 `/usr/share/ikiwiki/basewiki/`，你可以从里面复制一份到 `~/wikiwc/` 作为自己的版本，比如:

cp /usr/share/ikiwiki/basewiki/index.mdwn ~/wikiwc # 复制首页 (Markdown 标记的)
svn add ~/wikiwc/index.mdwn # 加入 svn
$EDITOR ~/wikiwc/index.mdwn # 修改首页文件内容
svn commit ~/wikiwc/index.mdwn -m customised # commit 到 svn repo 中

你发现 Subversion 在这里派上用场了，凡是编辑 wiki 文件其实都在 Subversion 中维护着，这样 Subversion 就能够跟踪每步更改了。

可是我们现在的方式还很原始耶，不能在浏览器中直接编辑 (也许某些人就喜欢这样)，每次要打长长的一串命令，于是，一个叫做“配置文件”的东西出来拯救我们了。

先把 ikiwiki 源文件目录下的 doc/ikiwiki.setup 复制一份到你喜欢的地方。然后开始修改这个文件。里面像 wikiname, adminemail 这样的看名字就知道是什么意思。下面是各项的简短说明，详细的可以看 [Usage](http://ikiwiki.kitenet.net/usage.html)。

* srcdir: 你放 index.mdwn 文件的那个目录
* destdir: 你输出 html 的那个目录
* url: wiki 的 URL
* cgiurl: 用于自动更新 wiki 的 cgi 程序的路径，这个程序是 ikiwiki 自动生成的，看下面的解释
* svnrepo 和 svnpath: 和前面创建的 repo 符合，在我这里是 /svn/wikirepo 和 trunk

接下来就是最重要的两个设置，为了实现在线编辑，ikiwiki 可以自动生成一个 (编译好的) C CGI 程序，这个程序的位置就在 cgi wrapper 部分指定，你需要设置为一个你的 web server 可以访问得到，而且又能作为 CGI 程序执行的地方，比如我放在 `~/public_html/wiki/ikiwiki.cgi`，那么 lighttpd 对应的配置是：

1. 打开 mod_cgi
2. 在 `cgi.assign` 的设置中，加入 `”.cgi” => “”` (为空表示不使用其他程序解释，直接执行)

同时，这里设置的位置也必须和前面的 cgiurl 属性对应，如果根据我前面的这个设置，对应的 cgiurl 就是 `http://localhost/~username/wiki/ikiwiki.cgi`。

问题在于，只是编辑了还不行，编辑后的结果得生成静态的 HTML 我们才能读啊，CGI 不负责这一步，它是通过一个 svn post-commit 的 hook 程序实现的，这个程序，同样是一个编译好的 C 程序，由 ikiwiki 自动生成，放在哪里应该是无所谓的，不过我这里是放在 `/svn/wikirepo/hooks/post-commit`。

这样就算是设置完毕了，执行 `ikiwiki –setup 配置文件路径/配置文件名` 可以生成上面提到的两个程序。

小结
—-

其实小结就是要说些坏话… 目前 ikiwiki 还没开始对 UTF-8 的支持，如果你是直接用编辑器来编辑文件的话，那不会有问题，可是如果希望通过 CGI 来在线编辑，它就搞不定了，在它的 TODO List 中也提到了目前[对付](http://ikiwiki.kitenet.net/todo/utf8.html)的方法，如果要全面解决，还是得期待 2.0 啦。

另外，ikiwiki 这样虽然很好玩，尤其是作为个人信息管理的工具，但恐怕还是不能胜任大型的 wiki，像 wikipedia 这样，同时有成百上千人在编辑，编辑后都要 svn commit… 哦，我不敢想象了。

发现一件有趣的事情，如果按照 ikiwiki 网站上给出的[图片](http://ikiwiki.kitenet.net/logo/ikiwiki.png)把第二个 k 反向，这又是一个反着读也一样的名字 🙂