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

Last change on this file since 31174 was 31174, checked in by sjamaan, 6 years ago

qwiki: hyper-estraier is optional

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