340 lines
7.3 KiB
Plaintext
340 lines
7.3 KiB
Plaintext
.TH WIKIFS 4
|
|
.SH NAME
|
|
wikifs, wikipost \- wiki file system
|
|
.SH SYNOPSIS
|
|
.B wikifs
|
|
[
|
|
.B -DM
|
|
]
|
|
[
|
|
.B -a
|
|
.I announce
|
|
]...
|
|
[
|
|
.B -m
|
|
.I mtpt
|
|
]
|
|
[
|
|
.B -p
|
|
.I perm
|
|
]
|
|
[
|
|
.B -s
|
|
.I service
|
|
]
|
|
.I dir
|
|
.PP
|
|
.B ip/httpd/wikipost
|
|
.RB [ -b
|
|
.IR inbuf ]
|
|
.RB [ -d
|
|
.IR domain ]
|
|
.RB [ -r
|
|
.IR remoteip ]
|
|
.RB [ -w
|
|
.IR webroot ]
|
|
.RB [ -N
|
|
.IR netdir ]
|
|
.I method version uri
|
|
.RI [ search ]
|
|
.SH DESCRIPTION
|
|
A
|
|
.I wiki
|
|
is a web server that facilitates easy editing of the pages it contains.
|
|
.I Wikifs
|
|
presents a wiki in two forms: as web pages to be served
|
|
via
|
|
.IR httpd (8)
|
|
and as text files to be viewed via the
|
|
.IR acme (1)
|
|
wiki client
|
|
(see
|
|
.BR /acme/wiki/guide ).
|
|
.PP
|
|
.I Wikifs
|
|
presents a file system interface to the wiki data stored
|
|
in
|
|
.IR dir .
|
|
By default,
|
|
.I wikifs
|
|
mounts itself at
|
|
.BR /mnt/wiki ;
|
|
the
|
|
.B -m
|
|
flag specifies a different mount point,
|
|
and the
|
|
.B -M
|
|
flag causes
|
|
.I wikifs
|
|
not to mount at all.
|
|
.I Wikifs
|
|
also announces 9P network services on the addresses
|
|
given as arguments to
|
|
.B -a
|
|
options.
|
|
If the
|
|
.B -s
|
|
option is given,
|
|
.I wikifs
|
|
will post a service file descriptor in
|
|
.BI /srv/ service
|
|
with permission
|
|
.I perm
|
|
(default 600).
|
|
The
|
|
.B -D
|
|
flag causes a transcript of the 9P conversation
|
|
to be written to standard error.
|
|
.PP
|
|
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 editing, 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.
|
|
.PP
|
|
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:
|
|
.TP
|
|
.B D
|
|
The date this page was written, in decimal seconds since the epoch.
|
|
.TP
|
|
.B A
|
|
The author of this version of the page. Typically the rest of the line
|
|
takes the form
|
|
.I name
|
|
.IR ip-address .
|
|
.TP
|
|
.B X
|
|
This page's contents were submitted but rejected due to a
|
|
conflicting write.
|
|
.PD
|
|
.PP
|
|
After the metadata comes the actual page contents; each line of
|
|
page contents is prefixed with a
|
|
.B #
|
|
character.
|
|
.PP
|
|
The directory
|
|
.IB dir /d
|
|
contains all the wiki data. Typically it is world-writable
|
|
so that
|
|
.I wikifs
|
|
can run as none.
|
|
Each page on the wiki has a unique sequence number
|
|
.IR n ;
|
|
for each page, the
|
|
.B d
|
|
directory contains three files
|
|
.IR n ,
|
|
.IB n .hist \fR,
|
|
and
|
|
.BI L .n \fR.
|
|
The file
|
|
.I n
|
|
holds the current version of the page: the first line of
|
|
.I n
|
|
is the page title, followed by page metadata and contents as described above.
|
|
The append-only file
|
|
.IB n .hist
|
|
holds the history of the page.
|
|
The first line of
|
|
.IB n .hist
|
|
is the title of the page.
|
|
The rest of the file is the metadata and contents of every
|
|
version of the page that has been submitted to the wiki.
|
|
.BI L .n
|
|
is a lock file for the page: it must be
|
|
held while reading or writing
|
|
.I n
|
|
and
|
|
.IB n .hist \fR.
|
|
The lock files allow multiple instances of
|
|
.I wikifs
|
|
to coexist peacefully.
|
|
Finally, the
|
|
.B map
|
|
file (with associated lock
|
|
.BR L.map )
|
|
provides a mapping from
|
|
sequence numbers to
|
|
to page titles.
|
|
Each map line is a decimal
|
|
.IR n ,
|
|
a single space,
|
|
and then the title.
|
|
Since titles are presented as names by
|
|
.IR wikifs ,
|
|
they cannot contain slashes.
|
|
.PP
|
|
.I Wikifs
|
|
presents a three-level file system.
|
|
The top level contains per-page directories
|
|
named by the page titles with spaces turned
|
|
into underscores.
|
|
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
|
|
.B 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 written 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
|
|
.B new
|
|
to obtain the canonical title for the page, as presented
|
|
by the file system.
|
|
.PP
|
|
The page directories contain subdirectories representing
|
|
the history of the page, named
|
|
by the decimal time stamp corresponding to each version.
|
|
In addition to these history directories,
|
|
the page directories contain the following files:
|
|
.TP
|
|
.B current
|
|
The current raw data file for the page.
|
|
.TP
|
|
.B 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 default:
|
|
differences between versions appear in black.
|
|
.TP
|
|
.B edit.html
|
|
A web form for editing the the current version of the page.
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B history.txt
|
|
A textual formatting of the history. Each time stamp is prefixed with
|
|
the name of the directory corresponding to that version.
|
|
.TP
|
|
.B index.html
|
|
An HTML formatting of the current version of the page.
|
|
.TP
|
|
.B index.txt
|
|
A textual formatting of the current version of the page.
|
|
.TP
|
|
.B werror.html
|
|
An HTML error page to be returned by
|
|
.I wikipost
|
|
on conflicting writes.
|
|
.PD
|
|
.LP
|
|
The HTML files are generated from the templates with the same names
|
|
in
|
|
.IR dir ,
|
|
except that
|
|
.B index.html
|
|
and
|
|
.B index.txt
|
|
are generated from the templates
|
|
.B page.html
|
|
and
|
|
.BR page.txt .
|
|
.PP
|
|
The history directories
|
|
are similar to the page directories but only contain
|
|
.BR current ,
|
|
.BR index.html ,
|
|
and
|
|
.BR index.txt .
|
|
This
|
|
.B index.html
|
|
and
|
|
.B index.txt
|
|
are generated from the templates
|
|
.B oldpage.html
|
|
and
|
|
.BR oldpage.txt .
|
|
.PP
|
|
The
|
|
.IR httpd (8)
|
|
helper program
|
|
.I wikipost
|
|
is used to process editing requests posted
|
|
to the web server by users.
|
|
It expects the posted form to contain these
|
|
(usually hidden) fields:
|
|
.BR TITLE ,
|
|
the title of the page;
|
|
.BR VERSION ,
|
|
the time stamp of the page that is being edited;
|
|
.BR service ,
|
|
the service name associated with this wiki
|
|
.RI ( wikipost
|
|
looks for
|
|
.BI /srv/wiki. service \fR);
|
|
and
|
|
.BR base ,
|
|
the base for wiki URLs in the response.
|
|
.PP
|
|
After mounting the wiki,
|
|
.I wikipost
|
|
writes a page update request to
|
|
.B /mnt/wiki/new
|
|
and then returns the contents of one HTML
|
|
file in
|
|
.BR /mnt/wiki/ title \fR.
|
|
If the write succeeds,
|
|
.I wikipost
|
|
returns
|
|
.BR index.html .
|
|
if the write fails due to a conflicting write,
|
|
.I wikipost
|
|
returns
|
|
.BR werror.html .
|
|
.SH EXAMPLE
|
|
The Plan 9 wiki at Bell Labs is started by running:
|
|
.EX
|
|
.ta +4n
|
|
wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/lib/wiki
|
|
.EE
|
|
.PP
|
|
The wiki is mounted for
|
|
.IR httpd (8)
|
|
by an entry in
|
|
.BR /lib/namespace.httpd :
|
|
.EX
|
|
.ta +4n
|
|
# wiki
|
|
mount -b #s/wiki.plan9 /usr/web/wiki/plan9
|
|
.EE
|
|
Notice that the wiki service was explicitly posted with
|
|
mode 666 so that
|
|
.I httpd
|
|
(running as none)
|
|
would be able to mount it.
|
|
.PP
|
|
In the Plan 9 distribution, the directory
|
|
.B /sys/lib/wiki
|
|
contains sample files similar to those used
|
|
to start the current Plan 9 wiki.
|
|
.SH SOURCE
|
|
.B /sys/src/cmd/wikifs
|
|
.br
|
|
.B /sys/src/cmd/ip/httpd/wikipost.c
|
|
.SH SEE ALSO
|
|
The original wiki,
|
|
.B http://c2.com/cgi/wiki?WikiWikiWeb
|
|
.br
|
|
.B /acme/wiki/guide
|