term% cat index.txt WIKIFS(4) Kernel Interfaces Manual WIKIFS(4)
NAME
wikifs, wikipost - wiki file system
SYNOPSIS
wikifs [ -DM ] [ -a announce ]... [ -m mtpt ] [ -p perm ] [ -s service
] dir
ip/httpd/wikipost [-b inbuf] [-d domain] [-r remoteip] [-w webroot] [-N
netdir] method version uri [search]
DESCRIPTION
A wiki is a web server that facilitates easy editing of the pages it
contains. Wikifs presents a wiki in two forms: as web pages to be
served via httpd(8) and as text files to be viewed via the acme(1) wiki
client (see /acme/wiki/guide).
Wikifs presents a file system interface to the wiki data stored in dir.
By default, wikifs mounts itself at /mnt/wiki; the -m flag specifies a
different mount point, and the -M flag causes wikifs not to mount at
all. Wikifs also announces 9P network services on the addresses given
as arguments to -a options. If the -s option is given, wikifs will
post a service file descriptor in /srv/service with permission perm
(default 600). The -D flag causes a transcript of the 9P conversation
to be written to standard error.
The wiki holds both the current pages and also all versions of all
pages that have ever existed. All pages have time stamps associated
with them. When a user wants to edit a page, he reads the current page
from the wiki, noting the time stamp on the page. When a user writes
changes to a page, he includes the time stamp of the page he started
with. If the page has been updated by someone else while he was edit‐
ing, the write will fail. This is called a ``conflicting write.'' The
submission is still saved in the history, so that the user can compare
the page he submitted with the changes that were made while he was
editing.
Each version of each page is described by a text file containing one or
more metadata lines followed by the page contents. The metadata lines
begin with a capital letter specifying the type of data. Currently the
metadata types are:
D The date this page was written, in decimal seconds since the
epoch.
A The author of this version of the page. Typically the rest of
the line takes the form name ip-address.
X This page's contents were submitted but rejected due to a con‐
flicting write.
After the metadata comes the actual page contents; each line of page
contents is prefixed with a # character.
The directory dir/d contains all the wiki data. Typically it is world-
writable so that wikifs can run as none. Each page on the wiki has a
unique sequence number n; for each page, the d directory contains three
files n, n.hist, and L.n. The file n holds the current version of the
page: the first line of n is the page title, followed by page metadata
and contents as described above. The append-only file n.hist holds the
history of the page. The first line of n.hist is the title of the
page. The rest of the file is the metadata and contents of every ver‐
sion of the page that has been submitted to the wiki. L.n is a lock
file for the page: it must be held while reading or writing n and
n.hist. The lock files allow multiple instances of wikifs to coexist
peacefully. Finally, the map file (with associated lock L.map) pro‐
vides a mapping from sequence numbers to page titles. Each map line is
a decimal n, a single space, and then the title. Since titles are pre‐
sented as names by wikifs, they cannot contain slashes.
Wikifs presents a three-level file system. The top level contains per-
page directories named by the page titles with spaces turned into un‐
derscores. Each page also has a number associated with it (see the
discussion of the wiki data files below). The number corresponding to
a page may also be used to access it, although directory listings will
always present the title. The new file is used to add new or revised
pages to the wiki: writes to the file should be in the usual textual
format: a title line, metadata lines, and page contents. Once all the
contents have been written, a final zero-length message should be writ‐
ten to mark the end of the page. This last write will return an error
if a conflicting write has occurred. After writing the file, the
client may read from new to obtain the canonical title for the page, as
presented by the file system.
The page directories contain subdirectories representing the history of
the page, named by the decimal time stamp corresponding to each ver‐
sion. In addition to these history directories, the page directories
contain the following files:
current
The current raw data file for the page.
diff.html
A web page listing the contents of every version of the page
that has ever appeared on the wiki. The text is grey by de‐
fault: differences between versions appear in black.
edit.html
A web form for editing the current version of the page.
history.html
A web page listing the time stamps of the historical versions of
the page. Each time stamp links to a page showing just that
version.
history.txt
A textual formatting of the history. Each time stamp is pre‐
fixed with the name of the directory corresponding to that ver‐
sion.
index.html
An HTML formatting of the current version of the page.
index.txt
A textual formatting of the current version of the page.
werror.html
An HTML error page to be returned by wikipost on conflicting
writes.
The HTML files are generated from the templates with the same names in
dir, except that index.html and index.txt are generated from the tem‐
plates page.html and page.txt.
The history directories are similar to the page directories but only
contain current, index.html, and index.txt. This index.html and in‐
dex.txt are generated from the templates oldpage.html and oldpage.txt.
The httpd(8) helper program wikipost is used to process editing re‐
quests posted to the web server by users. It expects the posted form
to contain these (usually hidden) fields: TITLE, the title of the page;
VERSION, the time stamp of the page that is being edited; service, the
service name associated with this wiki (wikipost looks for
/srv/wiki.service); and base, the base for wiki URLs in the response.
After mounting the wiki, wikipost writes a page update request to
/mnt/wiki/new and then returns the contents of one HTML file in
/mnt/wiki/title. If the write succeeds, wikipost returns index.html.
if the write fails due to a conflicting write, wikipost returns wer‐
ror.html.
EXAMPLE
The Plan 9 wiki at Bell Labs is started by running:
wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/lib/wiki
The wiki is mounted for httpd(8) by an entry in /lib/namespace.httpd:
# wiki
mount -b #s/wiki.plan9 /usr/web/wiki/plan9
Notice that the wiki service was explicitly posted with mode 666 so
that httpd (running as none) would be able to mount it.
In the Plan 9 distribution, the directory /sys/lib/wiki contains sample
files similar to those used to start the current Plan 9 wiki.
SOURCE
/sys/src/cmd/wikifs
/sys/src/cmd/ip/httpd/wikipost.c
SEE ALSO
The original wiki, http://c2.com/cgi/wiki?WikiWikiWeb
/acme/wiki/guide
WIKIFS(4)