wikifs 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338
  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. After the metadata comes the actual page contents; each line of
  122. page contents is prefixed with a
  123. .B #
  124. character.
  125. .PP
  126. The directory
  127. .IB dir /d
  128. contains all the wiki data. Typically it is world-writable
  129. so that
  130. .I wikifs
  131. can run as none.
  132. Each page on the wiki has a unique sequence number
  133. .IR n ;
  134. for each page, the
  135. .B d
  136. directory contains three files
  137. .IR n ,
  138. .IB n .hist \fR,
  139. and
  140. .BI L .n \fR.
  141. The file
  142. .I n
  143. holds the current version of the page: the first line of
  144. .I n
  145. is the page title, followed by page metadata and contents as described above.
  146. The append-only file
  147. .IB n .hist
  148. holds the history of the page.
  149. The first line of
  150. .IB n .hist
  151. is the title of the page.
  152. The rest of the file is the metadata and contents of every
  153. version of the page that has been submitted to the wiki.
  154. .BI L .n
  155. is a lock file for the page: it must be
  156. held while reading or writing
  157. .I n
  158. and
  159. .IB n .hist \fR.
  160. The lock files allow multiple instances of
  161. .I wikifs
  162. to coexist peacefully.
  163. Finally, the
  164. .B map
  165. file (with associated lock
  166. .BR L.map )
  167. provides a mapping from
  168. sequence numbers to
  169. to page titles.
  170. Each map line is a decimal
  171. .IR n ,
  172. a single space,
  173. and then the title.
  174. Since titles are presented as names by
  175. .IR wikifs ,
  176. they cannot contain slashes.
  177. .PP
  178. .I Wikifs
  179. presents a three-level file system.
  180. The top level contains per-page directories
  181. named by the page titles with spaces turned
  182. into underscores.
  183. Each page also has a number associated with it
  184. (see the discussion of the wiki data files below).
  185. The number corresponding to a page may
  186. also be used to access it, although directory
  187. listings will always present the title.
  188. The
  189. .B new
  190. file is used to add new or revised pages to the wiki:
  191. writes to the file should be in the usual textual format:
  192. a title line, metadata lines, and page contents.
  193. Once all the contents have been written, a final zero-length
  194. message should be written to mark the end of the page.
  195. This last write will return an error if a conflicting
  196. write has occurred.
  197. After writing the file, the client may read from
  198. .B new
  199. to obtain the canonical title for the page, as presented
  200. by the file system.
  201. .PP
  202. The page directories contain subdirectories representing
  203. the history of the page, named
  204. by the decimal time stamp corresponding to each version.
  205. In addition to these history directories,
  206. the page directories contain the following files:
  207. .TP
  208. .B current
  209. The current raw data file for the page.
  210. .TP
  211. .B diff.html
  212. A web page listing the contents of every version of
  213. the page that has ever appeared on the wiki.
  214. The text is grey by default:
  215. differences between versions appear in black.
  216. .TP
  217. .B edit.html
  218. A web form for editing the the current version of the page.
  219. .TP
  220. .B history.html
  221. A web page listing the time stamps of the historical versions of the page.
  222. Each time stamp links to a page showing just
  223. that version.
  224. .TP
  225. .B history.txt
  226. A textual formatting of the history. Each time stamp is prefixed with
  227. the name of the directory corresponding to that version.
  228. .TP
  229. .B index.html
  230. An HTML formatting of the current version of the page.
  231. .TP
  232. .B index.txt
  233. A textual formatting of the current version of the page.
  234. .TP
  235. .B werror.html
  236. An HTML error page to be returned by
  237. .I wikipost
  238. on conflicting writes.
  239. .PD
  240. .LP
  241. The HTML files are generated from the templates with the same names
  242. in
  243. .IR dir ,
  244. except that
  245. .B index.html
  246. and
  247. .B index.txt
  248. are generated from the templates
  249. .B page.html
  250. and
  251. .BR page.txt .
  252. .PP
  253. The history directories
  254. are similar to the page directories but only contain
  255. .BR current ,
  256. .BR index.html ,
  257. and
  258. .BR index.txt .
  259. This
  260. .B index.html
  261. and
  262. .B index.txt
  263. are generated from the templates
  264. .B oldpage.html
  265. and
  266. .BR oldpage.txt .
  267. .PP
  268. The
  269. .IR httpd (8)
  270. helper program
  271. .I wikipost
  272. is used to process editing requests posted
  273. to the web server by users.
  274. It expects the posted form to contain these
  275. (usually hidden) fields:
  276. .BR TITLE ,
  277. the title of the page;
  278. .BR VERSION ,
  279. the time stamp of the page that is being edited;
  280. .BR service ,
  281. the service name associated with this wiki
  282. .RI ( wikipost
  283. looks for
  284. .BI /srv/wiki. service \fR);
  285. and
  286. .BR base ,
  287. the base for wiki URLs in the response.
  288. .PP
  289. After mounting the wiki,
  290. .I wikipost
  291. writes a page update request to
  292. .B /mnt/wiki/new
  293. and then returns the contents of one HTML
  294. file in
  295. .BR /mnt/wiki/ title \fR.
  296. If the write succeeds,
  297. .I wikipost
  298. returns
  299. .BR index.html .
  300. if the write fails due to a conflicting write,
  301. .I wikipost
  302. returns
  303. .BR werror.html .
  304. .SH EXAMPLE
  305. The Plan 9 wiki at Bell Labs is started by running:
  306. .EX
  307. .ta +4n
  308. wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/lib/wiki
  309. .EE
  310. .PP
  311. The wiki is mounted for
  312. .IR httpd (8)
  313. by an entry in
  314. .BR /lib/namespace.httpd :
  315. .EX
  316. .ta +4n
  317. # wiki
  318. mount -b #s/wiki.plan9 /usr/web/wiki/plan9
  319. .EE
  320. Notice that the wiki service was explicitly posted with
  321. mode 666 so that
  322. .I httpd
  323. (running as none)
  324. would be able to mount it.
  325. .PP
  326. In the Plan 9 distribution, the directory
  327. .B /sys/lib/wiki
  328. contains sample files similar to those used
  329. to start the current Plan 9 wiki.
  330. .SH SOURCE
  331. .B /sys/src/cmd/wikifs
  332. .br
  333. .B /sys/src/cmd/ip/httpd/wikipost.c
  334. .SH SEE ALSO
  335. The original wiki,
  336. .B http://c2.com/cgi/wiki?WikiWikiWeb
  337. .br
  338. .B /acme/wiki/guide