/README.rst

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