/README.rst
ReStructuredText | 238 lines | 177 code | 61 blank | 0 comment | 0 complexity | 5ba559aacc5317524a47f32a80a99201 MD5 | raw file
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