sys/man/4/wikifs

   1 .TH WIKIFS 4
   2 .SH NAME
   3 wikifs, wikipost \- wiki file system
   4 .SH SYNOPSIS
   5 .B wikifs
   6 [
   7 .B -DM
   8 ]
   9 [
  10 .B -a
  11 .I announce
  12 ]...
  13 [
  14 .B -m
  15 .I mtpt
  16 ]
  17 [
  18 .B -p
  19 .I perm
  20 ]
  21 [
  22 .B -s
  23 .I service
  24 ]
  25 .I dir
  26 .PP
  27 .B ip/httpd/wikipost
  28 .RB [ -b
  29 .IR inbuf ]
  30 .RB [ -d
  31 .IR domain ]
  32 .RB [ -r
  33 .IR remoteip ]
  34 .RB [ -w
  35 .IR webroot ]
  36 .RB [ -N
  37 .IR netdir ]
  38 .I method version uri
  39 .RI [ search ]
  40 .SH DESCRIPTION
  41 A
  42 .I wiki
  43 is a web server that facilitates easy editing of the pages it contains.
  44 .I Wikifs
  45 presents a wiki in two forms: as web pages to be served
  46 via
  47 .IR httpd (8)
  48 and as text files to be viewed via the
  49 .IR acme (1)
  50 wiki client
  51 (see
  52 .BR /acme/wiki/guide ).
  53 .PP
  54 .I Wikifs
  55 presents a file system interface to the wiki data stored
  56 in
  57 .IR dir .
  58 By default,
  59 .I wikifs
  60 mounts itself at
  61 .BR /mnt/wiki ;
  62 the
  63 .B -m
  64 flag specifies a different mount point,
  65 and the
  66 .B -M
  67 flag causes
  68 .I wikifs
  69 not to mount at all.
  70 .I Wikifs
  71 also announces 9P network services on the addresses
  72 given as arguments to
  73 .B -a
  74 options.
  75 If the
  76 .B -s
  77 option is given,
  78 .I wikifs
  79 will post a service file descriptor in
  80 .BI /srv/ service
  81 with permission
  82 .I perm
  83 (default 600).
  84 The
  85 .B -D
  86 flag causes a transcript of the 9P conversation
  87 to be written to standard error.
  88 .PP
  89 The wiki holds both the current pages and also
  90 all versions of all pages that have ever existed.
  91 All pages have time stamps associated with them.
  92 When a user wants to edit a page, he reads the
  93 current page from the wiki, noting the time stamp
  94 on the page.
  95 When a user writes changes to a page, he includes the time stamp
  96 of the page he started with.  If the page has been updated
  97 by someone else while he was editing, the write will fail.
  98 This is called a ``conflicting write.''
  99 The submission is still saved in the history, so that
 100 the user can compare the page he submitted with the changes
 101 that were made while he was editing.
 102 .PP
 103 Each version of each page is described by a text file containing
 104 one or more metadata lines followed by the page contents.
 105 The metadata lines begin with a capital letter specifying the type of data.
 106 Currently the metadata types are:
 107 .TP
 108 .B D
 109 The date this page was written, in decimal seconds since the epoch.
 110 .TP
 111 .B A
 112 The author of this version of the page.  Typically the rest of the line
 113 takes the form
 114 .I name
 115 .IR ip-address .
 116 .TP
 117 .B X
 118 This page's contents were submitted but rejected due to a
 119 conflicting write.
 120 .PD
 121 .PP
 122 After the metadata comes the actual page contents; each line of
 123 page contents is prefixed with a
 124 .B #
 125 character.
 126 .PP
 127 The directory
 128 .IB dir /d
 129 contains all the wiki data.  Typically it is world-writable
 130 so that
 131 .I wikifs
 132 can run as none.
 133 Each page on the wiki has a unique sequence number
 134 .IR n ;
 135 for each page, the
 136 .B d
 137 directory contains three files
 138 .IR n ,
 139 .IB n .hist \fR,
 140 and
 141 .BI L .n \fR.
 142 The file
 143 .I n
 144 holds the current version of the page: the first line of
 145 .I n
 146 is the page title, followed by page metadata and contents as described above.
 147 The append-only file
 148 .IB n .hist
 149 holds the history of the page.
 150 The first line of
 151 .IB n .hist
 152 is the title of the page.
 153 The rest of the file is the metadata and contents of every
 154 version of the page that has been submitted to the wiki.
 155 .BI L .n
 156 is a lock file for the page: it must be
 157 held while reading or writing
 158 .I n
 159 and
 160 .IB n .hist \fR.
 161 The lock files allow multiple instances of
 162 .I wikifs
 163 to coexist peacefully.
 164 Finally, the
 165 .B map
 166 file (with associated lock
 167 .BR L.map )
 168 provides a mapping from
 169 sequence numbers to
 170 to page titles.
 171 Each map line is a decimal
 172 .IR n ,
 173 a single space,
 174 and then the title.
 175 Since titles are presented as names by
 176 .IR wikifs ,
 177 they cannot contain slashes.
 178 .PP
 179 .I Wikifs
 180 presents a three-level file system.
 181 The top level contains per-page directories
 182 named by the page titles with spaces turned
 183 into underscores.
 184 Each page also has a number associated with it
 185 (see the discussion of the wiki data files below).
 186 The number corresponding to a page may
 187 also be used to access it, although directory
 188 listings will always present the title.
 189 The
 190 .B new
 191 file is used to add new or revised pages to the wiki:
 192 writes to the file should be in the usual textual format:
 193 a title line, metadata lines, and page contents.
 194 Once all the contents have been written, a final zero-length
 195 message should be written to mark the end of the page.
 196 This last write will return an error if a conflicting
 197 write has occurred.
 198 After writing the file, the client may read from
 199 .B new
 200 to obtain the canonical title for the page, as presented
 201 by the file system.
 202 .PP
 203 The page directories contain subdirectories representing
 204 the history of the page, named
 205 by the decimal time stamp corresponding to each version.
 206 In addition to these history directories,
 207 the page directories contain the following files:
 208 .TP
 209 .B current
 210 The current raw data file for the page.
 211 .TP
 212 .B diff.html
 213 A web page listing the contents of every version of
 214 the page that has ever appeared on the wiki.
 215 The text is grey by default:
 216 differences between versions appear in black.
 217 .TP
 218 .B edit.html
 219 A web form for editing the the current version of the page.
 220 .TP
 221 .B history.html
 222 A web page listing the time stamps of the historical versions of the page.
 223 Each time stamp links to a page showing just
 224 that version.
 225 .TP
 226 .B history.txt
 227 A textual formatting of the history.  Each time stamp is prefixed with
 228 the name of the directory corresponding to that version.
 229 .TP
 230 .B index.html
 231 An HTML formatting of the current version of the page.
 232 .TP
 233 .B index.txt
 234 A textual formatting of the current version of the page.
 235 .TP
 236 .B werror.html
 237 An HTML error page to be returned by
 238 .I wikipost
 239 on conflicting writes.
 240 .PD
 241 .LP
 242 The HTML files are generated from the templates with the same names
 243 in
 244 .IR dir ,
 245 except that
 246 .B index.html
 247 and
 248 .B index.txt
 249 are generated from the templates
 250 .B page.html
 251 and
 252 .BR page.txt .
 253 .PP
 254 The history directories
 255 are similar to the page directories but only contain
 256 .BR current ,
 257 .BR index.html ,
 258 and
 259 .BR index.txt .
 260 This
 261 .B index.html
 262 and
 263 .B index.txt
 264 are generated from the templates
 265 .B oldpage.html
 266 and
 267 .BR oldpage.txt .
 268 .PP
 269 The
 270 .IR httpd (8)
 271 helper program
 272 .I wikipost
 273 is used to process editing requests posted
 274 to the web server by users.
 275 It expects the posted form to contain these
 276 (usually hidden) fields:
 277 .BR TITLE ,
 278 the title of the page;
 279 .BR VERSION ,
 280 the time stamp of the page that is being edited;
 281 .BR service ,
 282 the service name associated with this wiki
 283 .RI ( wikipost
 284 looks for
 285 .BI /srv/wiki. service \fR);
 286 and
 287 .BR base ,
 288 the base for wiki URLs in the response.
 289 .PP
 290 After mounting the wiki,
 291 .I wikipost
 292 writes a page update request to
 293 .B /mnt/wiki/new
 294 and then returns the contents of one HTML
 295 file in
 296 .BR /mnt/wiki/ title \fR.
 297 If the write succeeds,
 298 .I wikipost
 299 returns
 300 .BR index.html .
 301 if the write fails due to a conflicting write,
 302 .I wikipost
 303 returns
 304 .BR werror.html .
 305 .SH EXAMPLE
 306 The Plan 9 wiki at Bell Labs is started by running:
 307 .EX
 308 .ta +4n
 309         wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/lib/wiki
 310 .EE
 311 .PP
 312 The wiki is mounted for
 313 .IR httpd (8)
 314 by an entry in
 315 .BR /lib/namespace.httpd :
 316 .EX
 317 .ta +4n
 318         # wiki
 319         mount -b #s/wiki.plan9 /usr/web/wiki/plan9
 320 .EE
 321 Notice that the wiki service was explicitly posted with
 322 mode 666 so that
 323 .I httpd
 324 (running as none)
 325 would be able to mount it.
 326 .PP
 327 In the Plan 9 distribution, the directory
 328 .B /sys/lib/wiki
 329 contains sample files similar to those used
 330 to start the current Plan 9 wiki.
 331 .SH SOURCE
 332 .B /sys/src/cmd/wikifs
 333 .br
 334 .B /sys/src/cmd/ip/httpd/wikipost.c
 335 .SH SEE ALSO
 336 The original wiki,
 337 .B http://c2.com/cgi/wiki?WikiWikiWeb
 338 .br
 339 .B /acme/wiki/guide