source: project/wiki/eggref/4/qwiki @ 32904

Last change on this file since 32904 was 32904, checked in by Mario Domenech Goulart, 6 years ago

qwiki (wiki): release note for version 1.8

File size: 14.1 KB
Line 
1[[tags: egg]]
2
3== qwiki
4
5[[toc:]]
6
7=== Description
8
9A fast and light-weight wiki.
10
11=== Author
12
13[[/users/ivan-raikov|Ivan Raikov]] and [[/users/peter-bex|Peter Bex]]
14
15=== Requirements
16
17* [[svnwiki-sxml]]
18* [[intarweb]]
19* [[uri-common]]
20* [[spiffy]]
21* [[doctype]]
22* [[sxml-transforms]]
23* [[sxpath]]
24* [[html-parser]]
25* [[colorize]]
26* [[estraier-client]]
27* [[svn-client]]
28* [[sha1]]
29
30=== Documentation
31
32qwiki is the "quick wiki".  It is a lightweight wiki which uses sxml
33for internal wiki page representation.  This makes it relatively easy
34to extend.
35
36In the future we also hope to support multiple storage backends but
37right now subversion is the only implementation of that.
38
39=== How to set it up
40
41==== Set up hyper-estraier
42
43If you want the wiki to be searchable (via the optional {{qwiki-search}}
44module), you should start by setting up a
45[[http://fallabs.com/hyperestraier/|Hyper Estraier]] server.  This is as
46simple as navigating to the directory under which you want the full text
47database to be created and entering the following commands:
48
49  # estmaster init estraierdb
50  # estmaster start estraierdb
51
52This creates the db and sets the server running.
53
54Later, if you are happy with the setup and the wiki is working
55properly, you can add this line to your startup scripts:
56
57  estmaster start -bg /path/to/estraierdb
58
59The {{-bg}} switch puts it into daemon mode (and makes it quiet).
60
61==== Create a subversion repository
62
63You should first create a subversion repository, if you don't already
64have one.  Then, make a script called {{post-commit}} which you put in
65repo's {{hooks}} directory.  This script should invoke the
66{{qwiki-post-commit-hook!}} procedure from the
67{{qwiki-post-commit-hook}} module.  Here's an example
68({{path/to/your/repo/hooks/post-commit}}):
69
70<enscript highlight=scheme>
71#! /usr/bin/csi -s
72
73(use qwiki qwiki-svn qwiki-post-commit-hook)
74
75;; the URI for the subversion repository from where a copy can be
76;; checked out
77(qwiki-repos-uri "file:///path/to/the/repository/directory")
78
79;; the path to where the checkout of the repository will be stored
80(qwiki-source-path "/path/to/the/checkout/directory")
81
82;; the path used by the web server to serve wiki pages
83(qwiki-web-path "/path/to/web/server/documents/directory")
84
85;; If you don't want to use these extensions, you can remove the lines
86(search-install!)
87(menu-install!)
88
89(qwiki-post-commit-hook!)
90</enscript>
91
92If you prefer, you can delay setting up the post-commit hook until
93after you got the wiki up and running (this is a good idea if people
94will be committing to the repository while you are setting this up).
95
96You can also call the {{post-commit}} scheme script (like the example
97above) from any other script you want to use as the actual
98{{post-commit}} script.  You can also call arbitrary other scripts
99from the Scheme script, of course.
100
101Don't forget to make the script executable!
102
103
104==== Deploy qwiki
105
106Now you are ready to run the qwiki installation procedure which will
107create an initial checkout, process all files to make a cached HTML
108file for each wiki page and populate the search index.
109
110The best way to do that is by creating a script which sets the required
111parameters and calls {{qwiki-install!}}.  Here's a simple example:
112
113<enscript highlight=scheme>
114(use qwiki qwiki-install qwiki-svn)
115
116;; the URI for the subversion repository from where a copy can be
117;; checked out
118(qwiki-repos-uri "file:///path/to/the/repository/directory")
119
120;; the path to where the checkout of the repository will be stored
121(qwiki-source-path "/path/to/the/checkout/directory")
122
123;; the path used by the web server to serve wiki pages
124(qwiki-web-path "/path/to/web/server/documents/directory")
125
126;; install qwiki
127(qwiki-install!)
128</enscript>
129
130Here's a more complex example:
131
132<enscript highlight=scheme>
133(use qwiki qwiki-install qwiki-search qwiki-menu qwiki-svn)
134
135;; Try to read the svnwiki user password
136(handle-exceptions
137 exn
138 (begin
139   (with-output-to-port (current-error-port)
140     (lambda ()
141       (print "Could not read the password file for the SVN user.  Aborting.")))
142   (exit 1))
143 (qwiki-repos-password
144  (with-input-from-file "the-password-file" read-line)))
145
146(search-install!)
147(menu-install!)
148(qwiki-repos-username "the-wiki-user")
149(qwiki-css-file "/wiki.css")
150(qwiki-title "The wiki")
151
152(qwiki-repos-uri "file:///var/svn/")
153(qwiki-source-path "/tmp/qwiki")
154(qwiki-web-path "/var/www/spiffy/wiki")
155
156(qwiki-install!)
157</enscript>
158
159The values for {{qwiki-source-path}} and {{qwiki-web-path}} should not
160overlap.
161
162The exact directory locations are up to you, of course, but they will
163have to match the locations of the post-commit-hook.  You can also set
164the search URI location through the {{QWIKI_SEARCH_URI}} environment
165variable if you changed the default admin account or want it to use
166some other location than localhost.
167
168Now, you can run this script to get started.
169
170==== Create a spiffy configuration
171
172Currently qwiki can only run under Spiffy, so you will either have to
173run spiffy as your main webserver, or proxy all requests for the wiki
174to it.
175
176<enscript highlight=scheme>
177(use spiffy qwiki qwiki-search qwiki-menu qwiki-svn)
178
179;; If you don't want these extensions, remove them from this script
180(search-install!)
181(menu-install!)
182
183(qwiki-repos-uri "file:///path/to/repos")
184(qwiki-source-path "/path/to/the/checkout/directory")
185
186;; Ensure this is an absolute path, if you are using Chicken 4.1 or earlier
187(root-path "/var/www/html/qwiki")
188
189;; Pass all requests to non-existent files through qwiki:
190(vhost-map `((".*" . ,(lambda (continue)
191                        (parameterize ((handle-not-found qwiki-handler)
192                                       (handle-directory qwiki-handler)
193                                       (index-files '()))
194                           (continue))))))
195
196(start-server)
197</enscript>
198
199When you run this, your qwiki installation should be available at
200http://localhost:8080
201
202==== Customizing Qwiki
203
204===== qwiki
205
206These parameters are exported by the {{qwiki}} module.
207
208<parameter>(qwiki-css-file [FILE])</parameter>
209
210Set an optional CSS file to use for styling the wiki.  {{FILE}} should
211be a string, which is parsed into an uri-common object by the
212{{uri-reference}} procedure.  This URI should be relative to the
213docroot.  Defaults to {{#f}}.
214
215<parameter>(qwiki-title [TITLE])</parameter>
216
217Set an optional global {{TITLE}} or "name" for the wiki.  This will
218appear on every page in the browser's titlebar to inform the user that
219he's on a page of this particular wiki. Defaults to {{#f}}.
220
221<parameter>(qwiki-source-path [DIRECTORY])</parameter>
222
223The directory where qwiki expects a checkout of the repository that
224holds the wiki pages.  When running the installation procedure, it
225will make this checkout.
226
227The value defaults to the environment variable {{QWIKI_SOURCE_PATH}}
228if set. Otherwise it will default to {{"/tmp/qwiki"}}.
229
230<parameter>(qwiki-web-path [DIRECTORY])</parameter>
231
232The directory where qwiki will write its generated and cached HTML files to.
233Defaults to the environment variable {{QWIKI_WEB_PATH}} if set, otherwise
234will default to {{"/var/www"}}.
235
236This variable is only for when qwiki is called from the commandline or
237through the post-commit hook.  It is ''ignored'' when running qwiki
238through {{qwiki-handler}} inside Spiffy.  In that case it will just
239use Spiffy's {{root-path}}.
240
241<parameter>(qwiki-docroot [DIRECTORY])</parameter>
242
243In case you want qwiki be accessible underneath a subdirectory of
244spiffy, you can use this.  (it's unsure whether this even works and
245whether it will stay)
246
247<parameter>(qwiki-base-uri [URI])</parameter>
248
249The URI (an [[uri-common]] object) under which this wiki is
250available.  All internal links will use this as their base URI.
251Defaults to {{/}}.
252
253<parameter>(qwiki-output-driver [TRANSFORMATION-RULES])</parameter>
254
255This defaults to {{qwiki-html-transformation-rules}} from the
256{{qwiki-sxml}} module.  It can be changed to
257{{qwiki-LaTeX-transformation-rules}} or
258{{qwiki-Texinfo-transformation-rules}} when generating offline
259documentation.
260
261<parameter>(qwiki-extensions [EXTENSIONS])</parameter>
262
263This parameter can be extended to add transformation rule extensions
264to the output driver.  Defaults to the empty list.
265
266A transformation rule is simply a ruleset accepted by {{pre-post-order*}}.
267
268<parameter>(qwiki-update-handlers [HANDLERS])</parameter>
269
270This parameter can be extended to add update callbacks which will be
271invoked when a wiki page was updated. Defaults to the empty list.
272
273An update hook is a procedure that accepts a path to the wiki page (a
274list of path components) and the sxml which represents the new
275contents.
276
277<parameter>(qwiki-delete-handlers [HANDLERS])</parameter>
278
279This parameter can be extended to add update callbacks which will be
280invoked when a wiki page was removed. Defaults to the empty list.
281
282<parameter>(blocked-ip-addresses-file [PATH])</parameter>
283
284A path relative to the qwiki checkout which points to a file
285containing IP addresses to be blocked, one address per line.
286Useful for combating spam.
287
288Defaults to {{"edit-deny"}}.
289
290<parameter>(qwiki-current-file [PATH])</parameter>
291
292Not to be touched in the configuration; this is a run-time parameter
293used to indicate the current wiki file being processed.  Useful for
294use in transformation rules.
295
296===== qwiki-svn
297
298These parameters are exported by the {{qwiki-svn}} module.
299
300<parameter>(qwiki-repos-uri [URI-STRING])</parameter>
301
302The URI to the subversion repository.  Defaults to #f, so you must
303configure this!
304
305<parameter>(qwiki-repos-username [USERNAME])</parameter>
306
307The username for commits done from the wiki interface when the user
308chooses not to authenticate.  Default: {{"anonymous"}}
309
310<parameter>(qwiki-repos-password [PASSWORD])</parameter>
311
312The password for the {{qwiki-repos-username}} user.
313Default: {{""}}
314
315===== qwiki-search
316
317These parameters are exported by the {{qwiki-search}} module.
318
319<parameter>(search-server-uri [URI])</parameter>
320
321Defaults to whatever the environment variable {{QWIKI_SEARCH_URI}}
322holds if it is set, or else {{"http://admin:admin@localhost:1978"}},
323which is the default estraier URI.
324
325
326===== qwiki-menu
327
328These parameters are exported by the {{qwiki-menu}} module.
329
330<parameter>(menu-file [PATH])</parameter>
331
332If not {{#f}}, this file will contain (in wiki syntax) the contents
333of the menu which is rendered on all wiki pages.  Should be relative
334to the wiki checkout directory.  Defaults to {{"/menu"}}.
335
336
337===== qwiki-install
338
339<procedure>(qwiki-install!)</procedure>
340
341Performs the steps for installing qwiki.  It uses the parameters
342{{qwiki-repos-uri}}, {{qwiki-source-path}} and {{qwiki-web-path}} and
343considers their values are valid ones.
344
345This procedure is to be used by installation scripts.
346
347
348===== qwiki-post-commit-hook
349
350<procedure>(qwiki-post-commit-hook!)</procedure>
351
352Executes the required steps after a commit is performed. It uses the
353parameters {{qwiki-repos-uri}}, {{qwiki-source-path}} and considers
354their values are valid ones.
355
356This procedure is to be used by Subversion post-commit scripts.
357
358
359=== Changelog
360
361* 1.8 - disallow backslashes in request paths
362* 1.7 - Remove dependency on the deprecated multidoc egg.  Many thanks to Arthur Maciel.  Make estraier/qwiki-search optional during installation as well.
363* 1.6 - Use {{finish-response-body}} from intarweb so that in case we start using chunking we get proper output.  Prevent error situation caused by failed authentication (reported by Alex Charlton).
364* 1.5.1 - Bugfix for edit pages.
365* 1.5 - Add {{nofollow}} attribute to historical links for better SEO results.  Add missing paging links to search results pages (pointed out by John Croisant)
366* 1.4.1 - Fix compatibility with message-digest/new version of sha1 egg
367* 1.4 - Improve page title extraction so it can handle some inline styling (but not links).  Add redirect when trying to access a path that treats an existing page as a parent directory (thanks to [[/users/alaric-blagrave-snellpym|Alaric]])
368* 1.3 - Fix wrong regex in qwiki-search which caused an internal server error on some machines.  Implement detection of conflicting concurrent edits. Remove use of deprecated make macro and add {{test}} egg to test dependencies.
369* 1.2.1 - Fix bug which caused files which were created through the web interface to cause 500 errors.
370* 1.2 - Fix require error in qwiki-install (load libs, don't just import them). Do not generate links ending with {{?action=show}}.  Allow missing CSS-files [thanks to Paul Nelson].  Add a fix for older Chickens which raise an error when calling {{symbolic-link?}} on a nonexistant file. [Also thanks to Paul Nelson] Update to latest svn-client (0.17)
371* 1.1 - Update handling of symbolic links, making them safer and getting rid of cache and text search database inconsistencies. Fix filename normalization for absolute path references in wiki page links.
372* 1.0 - First release, as deployed on [[http://wiki.call-cc.org]]
373
374=== License
375
376  Copyright (c) 2009-2015, Ivan Raikov and Peter Bex
377  All rights reserved.
378 
379  Redistribution and use in source and binary forms, with or without
380  modification, are permitted provided that the following conditions are
381  met:
382 
383  Redistributions of source code must retain the above copyright
384  notice, this list of conditions and the following disclaimer.
385 
386  Redistributions in binary form must reproduce the above copyright
387  notice, this list of conditions and the following disclaimer in the
388  documentation and/or other materials provided with the distribution.
389 
390  Neither the name of the author nor the names of its contributors may
391  be used to endorse or promote products derived from this software
392  without specific prior written permission.
393 
394  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
395  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
396  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
397  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
398  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
399  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
400  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
401  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
402  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
403  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
404  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
405  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.