PageRenderTime 467ms CodeModel.GetById 448ms RepoModel.GetById 0ms app.codeStats 0ms

/README.rst

http://github.com/cgay/wiki
ReStructuredText | 238 lines | 177 code | 61 blank | 0 comment | 0 complexity | 5ba559aacc5317524a47f32a80a99201 MD5 | raw file
  1. wiki
  2. ====
  3. This library is a wiki written in the Dylan language. It supports the
  4. following features:
  5. * All data is stored in a git repository so it can be edited offline
  6. if desired, backed up, reverted, etc.
  7. * Account verification.
  8. * Access controls -- each page in the wiki can be restricted to
  9. being viewed or edited by specific sets of users.
  10. * Page markup based on `ReStructured Text (RST)
  11. <http://docutils.sourceforge.net/rst.html>`_
  12. Configuration
  13. =============
  14. You will need to tweak these values in the config file:
  15. * **http-server.wiki.git-main-repository-root** -- Make it point to the root
  16. directory of your wiki git repository. Example::
  17. $ cd
  18. $ mkdir wiki-data
  19. $ cd wiki-data
  20. $ git init
  21. <wiki git-main-repository-root = "/home/you/wiki-data" ...>
  22. * **http-server.wiki.git-user-repository-root** -- Make this point to the
  23. root directory of the user data repository. This is separate from
  24. the page and group data so that it can easily be backed-up
  25. separately (e.g., by pushing to a different remote). Example::
  26. $ cd
  27. $ mkdir wiki-user-data
  28. $ cd wiki-user-data
  29. $ git init
  30. <wiki user-repository = "/home/you/wiki-user-data" ...>
  31. * **http-server.wiki.git-executable** -- If the "git" executable is not on the
  32. path of the user running the wiki, then you need to specify it in
  33. the <wiki> element::
  34. <wiki git-executable = "/usr/bin/git" ... />
  35. * **http-server.wiki.static-directory** -- Make it point at the "www" subdirectory
  36. (I guess this should be made relative to <server-root>.)
  37. * **http-server.wiki.administrator.password** -- Choose a password you like.
  38. * **http-server.wiki.rst2html** -- Path to the rst2html executable.
  39. Startup
  40. =======
  41. Build the library and then run it like this::
  42. wiki --config config.xml
  43. Markup Language
  44. ===============
  45. The markup language is an augmented version of `ReStructured Text
  46. (RST) <http://docutils.sourceforge.net/rst.html>`. An initial pass is
  47. made over the markup source to resolve wiki-specific markup and then
  48. the resulting text is passed directly to rst2html.
  49. All wiki directives start with ``{{`` and ends with ``}}``. Because
  50. page links are expected to be the most common by far, they have an
  51. optional shortened syntax::
  52. {{page: Foo, text: Bar}} -- link text "Bar" to page "Foo"
  53. {{Foo,Bar}} -- shorthand for {{page:Foo,text:Bar}}
  54. {{Foo}} -- shorthand for {{page:Foo,text:Foo}}
  55. {{page: "x,y"}} -- names may be quoted
  56. {{page: 'The "x" Page'}} -- single or double quotes work.
  57. {{user: jdoe, text: Jon}} -- a user link
  58. {{group: group}} -- a group link
  59. {{escape: "[[" "]]"}} -- use [[ and ]] instead of {{ and }}
  60. The wiki pre-parser knows nothing about RST parsing. It simply
  61. searches the raw markup for ``{{`` and assumes that's a wiki
  62. directive. If you need to put a literal ``{{`` or ``}}`` in the
  63. generated output it can be done by changing the escape character
  64. sequences::
  65. {{escape: "[[" "]]"}}
  66. Now {{ and }} are just normal text and [[Foo]] is a page link.
  67. [[escape: "{{" "}}"]]
  68. Dev Guide
  69. =========
  70. Admin
  71. -----
  72. The wiki repositories (main content and user data) make use of the
  73. "git notes" feature to store meta-data about each commit. Becaues of
  74. this they need some special attention when pushing/pulling.
  75. Clone::
  76. $ git clone git@github.com:cgay/dylan-wiki-data
  77. $ git pull origin refs/notes/commits:refs/notes/commits
  78. Push::
  79. $ git push origin
  80. $ git push origin refs/notes/commits
  81. Pull::
  82. $ git pull origin
  83. $ git pull origin refs/notes/commits:refs/notes/commits
  84. Data File Layouts
  85. -----------------
  86. All wiki data are stored in a git repository. "Public" data is stored
  87. in one repository and "private" data in another. The only private
  88. data is the user database. Pages and groups are stored in the public
  89. repo.
  90. In order not to end up with too many files in a single directory
  91. (which may just be a superstition these days, and is really only a
  92. worry for pages anyway) users, groups, and pages are divided into
  93. subdirectories using the first few letters of their name/title. e.g.,
  94. a page entitled "Green Stripe" would be stored in the directory named
  95. ``sandboxes/main/Gre/Green Stripe/``. Similarly for users and groups,
  96. although they use a shorter prefix on the theory that there will be a
  97. lot fewer of them.
  98. Example::
  99. <public-repo-root>/
  100. groups/
  101. a/
  102. <a-group-1>
  103. <a-group-2>
  104. ...
  105. b/
  106. <b-group-1>
  107. <b-group-2>
  108. ...
  109. c/
  110. ...
  111. pages/
  112. <sandbox-1>/
  113. <prefix-1>/
  114. <page-name-1>/content # page markup
  115. <page-name-1>/tags # page tags
  116. <page-name-1>/acls # page ACLs
  117. <page-name-1>/links # pages that link to this page
  118. <page-name-2>/content
  119. <page-name-2>/tags
  120. <page-name-2>/acls
  121. <page-name-2>/links
  122. ...
  123. <prefix-2>/
  124. ...
  125. <sandbox-2>/
  126. <prefix-1>/
  127. <page-name-1>/content
  128. <page-name-1>/tags
  129. <page-name-1>/acls
  130. ...
  131. <private-repo-root>/
  132. users/
  133. a/
  134. <a-user-1>
  135. <a-user-2>
  136. ...
  137. b/
  138. <b-user-1>
  139. <b-user-2>
  140. ...
  141. ...
  142. z/
  143. The default sandbox name is "main" and currently there is no way to
  144. create new sandboxes. In some other wikis these would be called
  145. "wikis". The format of each file is described below.
  146. content
  147. The ``content`` file contains the raw wiki page markup text and
  148. nothing else.
  149. tags
  150. The ``tags`` file contains one tag per line and nothing else. Tags may
  151. contain whitespace.
  152. acls
  153. The ``acls`` file has the following format::
  154. owner: <username>
  155. view-content: <rule>,<rule>,...
  156. modify-content: <rule>,<rule>,...
  157. modify-acls: <rule>,<rule>,...
  158. Rules are defined by the following pseudo BNF::
  159. <rule> ::= <access><name>
  160. <access> ::= - | + // '-' = deny, '+' = allow
  161. <name> ::= <user> | <group> | $any | $trusted | $owner
  162. <user> ::= any user name
  163. <group> ::= any group name
  164. The special name "$any" means any user, "$trusted" means logged in users
  165. and "$owner" means the page owner. "$" is not allowed in user or group
  166. names so there is no conflict.
  167. <a-group-1>
  168. iso8601-creation-date
  169. name:owner:member1:member2:...
  170. <n-bytes>
  171. ...description in n bytes...
  172. <a-user-1>
  173. iso8601-creation-date
  174. username1:Real Name:admin?:password:email:activation-key:active?
  175. Passwords are stored in base-64 for now, to be slightly better
  176. than clear text. This must be improved. Email is also in
  177. base-64.